XTDB节点AWS S3检查点配置及持续失败问题排查

故障特征 #

• 部署环境：AWS ECS Fargate，XTDB 1.21.0版本，RocksDB存储引擎，配置30分钟周期S3检查点
• 异常表现：前几次检查点正常生成，后续检查点持续失败，XTDB日志抛出AWS HTTP请求类异常；S3存储桶内残留不完整检查点目录，目录下仅存在SST文件及其他RocksDB附属文件，缺失关联的EDN索引文件
• 异常日志截图：
  
• 残缺检查点文件示例：
  

根因 #

XTDB默认初始化的S3异步客户端使用Netty默认连接池参数，连接获取超时阈值过低、并发连接数不足，大体积SST文件上传时无法从连接池获取有效连接，导致上传流程中断，EDN索引文件未完成写入，最终留下残缺检查点。

落地修复步骤 #

1. 实现自定义S3Configurator #

不需要深入掌握Netty框架，直接重写makeClient方法覆盖HTTP客户端配置即可，完整Java实现代码如下：

package com.yourorg.xtdb;

import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import xtdb.s3.S3Configurator;
import java.time.Duration;

public class CustomS3Configurator implements S3Configurator {
    @Override
    public S3AsyncClient makeClient(S3AsyncClient.Builder s3ClientBuilder) {
        // 自定义Netty异步HTTP客户端参数
        NettyNioAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
                .maxConcurrency(200)
                .connectionAcquisitionTimeout(Duration.ofMillis(20000))
                // 补充大文件上传超时配置，避免大SST文件上传过程中连接超时断开
                .writeTimeout(Duration.ofMinutes(5))
                .readTimeout(Duration.ofMinutes(5))
                .build();

        return s3ClientBuilder
                .httpClient(httpClient)
                .build();
    }
}

将该类编译后打包到XTDB节点的项目依赖中即可。

2. EDN配置文件接入自定义配置 #

XTDB的EDN配置原生支持传入自定义S3Configurator实例，不需要修改配置加载逻辑，在原有S3检查点配置段添加configurator字段即可：

{
 ;; 其余原有XTDB配置保持不变
 :xtdb.s3/checkpoint-store {
  :bucket "你的检查点S3桶名称"
  :prefix "检查点存储路径前缀"
  ;; 传入自定义Configurator实例，替换为你自己实现类的全限定名
  :configurator (com.yourorg.xtdb.CustomS3Configurator.)
 }
}

如果直接使用Clojure启动XTDB节点，不需要单独编写Java类，可以直接在EDN配置中通过reify内联实现S3Configurator接口：

:configurator (reify xtdb.s3.S3Configurator
                (makeClient [_ s3ClientBuilder]
                  (let [http-client (-> (NettyNioAsyncHttpClient/builder)
                                        (.maxConcurrency 200)
                                        (.connectionAcquisitionTimeout (Duration/ofMillis 20000))
                                        (.writeTimeout (Duration/ofMinutes 5))
                                        (.readTimeout (Duration/ofMinutes 5))
                                        (.build))]
                    (-> s3ClientBuilder
                        (.httpClient http-client)
                        (.build)))))

3. 存量脏数据清理 #

配置生效前，手动删除S3桶内所有缺失EDN索引文件的不完整检查点目录，避免XTDB启动或故障恢复时识别到无效检查点抛出异常。

Fargate环境适配优化 #

• 给Fargate任务分配足够的CPU、内存与临时存储配额：RocksDB检查点生成、上传过程会占用本地临时存储与网络带宽，单任务建议至少分配0.5vCPU + 1GB内存，检查点体积较大时按需提升配额
• 给S3检查点桶配置生命周期规则，自动清理超过保留周期的历史检查点，避免无效文件占用存储
• 单检查点文件体积超过100MB时，可在自定义S3客户端中开启多部分上传配置，进一步提升大文件上传稳定性

内容的提问来源于stack exchange，提问作者modality