从 Amazon DynamoDB 迁移到 Tair Serverless KV

使用 ddb-migrate 复制存量数据并持续同步增量变更，再使用 ddb-data-check 校验两端数据。本指南给出从迁移准备、数据同步、校验到业务切换的完整操作。

整体流程

1. ddb-migrate 扫描源表，将存量数据写入目标表。
2. 存量数据复制完成后，ddb-migrate 持续读取 DynamoDB Streams，同步新增、修改和删除。
3. ddb-data-check 逐条比较源表和目标表。
4. 停止源端写入，等待增量同步完成，然后切换业务流量。

迁移前准备

1. 从 GitHub Releases 下载与服务器操作系统和架构对应的压缩包。
2. 创建 Tair Serverless KV（DynamoDB 兼容版）实例和目标表。分区键和排序键（如有）的名称及类型需要与源表一致，非键属性无须预先定义。
3. 为源表开启 DynamoDB Streams，视图类型设为 NEW_IMAGE 或 NEW_AND_OLD_IMAGES。
4. 准备可以读取源表的 AWS 凭证。工具支持 AK/SK、AWS Profile、Web Identity、ECS 任务角色和 EC2 实例角色。
5. 准备用于运行工具的服务器，并确认服务器可以访问 AWS DynamoDB 和 Tair endpoint。

运行 ddb-migrate

解压下载的压缩包，编辑 ddb-migrate.toml。下面是从 AWS DynamoDB 迁移到 Tair 的精简配置：

[source]
access_key_id = "<aws-access-key-id>"
secret_access_key = "<aws-secret-access-key>"
region = "us-east-1"
table = "source_table"
checkpoint_enabled = true
checkpoint_file_path = "checkpoint.json"

[target]
access_key_id = "username:password"
secret_access_key = "dummy"
endpoint_url = "http://your-tair-endpoint:80"
table = "target_table"

请替换源端凭证、区域、表名、Tair 账号密码和 endpoint。源端根据 region 访问 AWS 官方端点；目标端填写 Tair 实例的 DynamoDB 兼容端点。AWS 各种凭证方式、目标端 endpoint 行为、检查点和并发参数见 ddb-migrate 配置。

启动迁移：

./ddb-migrate ddb-migrate.toml

日志显示 Scan 时，程序正在复制存量数据；显示 Stream 时，程序正在同步增量变更。

校验数据

当 ddb-migrate 稳定运行在 Stream 阶段，且同步 QPS 与源端业务写入 QPS 大致持平时，增量数据已基本追平。编辑 ddb-data-check.toml：

check_mode = "source"

[source]
access_key_id = "<aws-access-key-id>"
secret_access_key = "<aws-secret-access-key>"
region = "us-east-1"
endpoint_url = ""
table = "source_table"

[target]
access_key_id = "username:password"
secret_access_key = "dummy"
endpoint_url = "http://your-tair-endpoint:80"
table = "target_table"

两份配置可以复用源端凭证、区域和表名，以及 Tair 账号密码、endpoint 和表名。校验方向和凭证配置见 ddb-data-check 配置。

执行校验并生成 HTML 报告：

./ddb-data-check ddb-data-check.toml
python3 analyze_report.py ddb-data-check-diff/report.json

check_mode = "source" 检查每个源端 item 在目标端是否存在且内容一致。完成后将其改为 target 并再执行一次，可以检查目标端是否存在源端没有的 item。

切换业务

1. 在计划的切换窗口暂停所有源端业务写入。
2. 继续观察 ddb-migrate 日志，等待 Stream 同步 QPS 下降并稳定为 0。
3. 将应用配置指向新的 Tair 实例，然后重新启动服务。

常见问题

启动时报告 Stream 或 checkpoint 错误

程序在迁移数据前读取源表定义，并检查 DynamoDB Streams 是否启用，视图类型是否为 NEW_IMAGE 或 NEW_AND_OLD_IMAGES。日志报告 Stream 未启用或处于关闭状态时，先在 AWS 控制台启用 Stream；刚启用后表定义尚未更新时，等待几分钟再启动。视图类型不符合要求时需要修改配置，等待不会改变该错误。

checkpoint 记录源表名称、Stream ARN、保存时间、Scan 进度和各 shard 位点。以下情况不能使用原 checkpoint：

• checkpoint 属于另一张源表或另一个 Stream。
• checkpoint 最后保存时间已超过 23 小时的安全窗口。
• 日志明确报告 sequence number 超出 24 小时保留期、数据已被裁剪，或父 shard 在处理完成前消失。

这些错误表示增量数据的连续性已经无法确认。停止任务，确认需要重新全量迁移后删除 checkpoint.json，再使用原配置启动。删除文件会放弃已有的全部 Scan 和 Stream 进度。

目标端连接、表结构或写入失败

程序在启动阶段调用目标端 DescribeTable。此时失败时依次检查：

1. endpoint_url 是否包含正确的协议、主机名和端口。
2. Tair access_key_id 是否为“账号:密码”，secret_access_key 是否为 dummy。
3. 运行服务器的 IP 是否在目标实例白名单中，网络是否可以到达该 endpoint。
4. 目标表是否存在，分区键和排序键（如有）的名称及类型是否与源表一致。

迁移过程中出现 destination throttling 时，writer 会保留未完成批次并退避重试，最长等待 30 分钟。此时提高 workers 会增加目标端压力；应提高目标端写入能力，或降低 workers。日志报告 BatchWriteItem ... failed after AWS SDK retries 时，该错误不属于限流，按日志中的权限、请求或数据校验错误处理。

修复目标端问题后，使用同一配置和 checkpoint 重新启动即可续传。只有日志明确要求重新全量同步时才删除 checkpoint。

全量 Scan 速度较低

状态日志同时显示 Scan 读取速率、Write 写入速率和 backlog：

• backlog 长期接近 0，且 Scan 速率较低：读取端限制了速度。确认源表有可用 RCU 后提高 scan_segments。Scan 使用强一致读取，提高并行度会增加源表读取请求和 RCU 消耗。
• backlog 持续增长：目标端写入速度低于源端读取速度。没有限流日志时可以提高 workers；出现 destination throttling 时应提高目标端写入能力或降低 workers。

修改 scan_segments 后，未完成的旧 Scan checkpoint 不能继续使用，程序会从头扫描源表。需要调整该值时，先确认可以放弃当前全量进度。全量阶段接近 Stream 保留期时，应同时检查源端读取能力、目标端写入能力和 backlog，避免只提高读取并发后把数据积压到 writer。