ape-dts 断点续传详解:任务中断后如何从 position.log 精准恢复
ape-dts 断点续传详解:任务中断后如何从 position.log 精准恢复
ape-dts 是 ApeCloud 用 Rust 编写的企业级数据迁移套件,支持 MySQL、PostgreSQL、Redis、MongoDB、Kafka、ClickHouse 之间的高速数据复制。当增量同步任务因网络抖动、机器重启等原因中断后,ape-dts 的断点续传功能可以从进度日志 position.log 中读取最近记录的位点,让任务精准恢复到中断处继续同步,既不丢数据,也不重复写入。本文带你完整掌握 ape-dts 断点续传的原理与配置方法。
一、什么是断点续传?为什么需要它 🧭
ape-dts 的同步任务由 extractor(抽取)→ pipeline(队列+并行化)→ sinker(写入) 组成。增量任务从源库读取 binlog / WAL / 变更流,解析后写入目标库:
任务运行期间,ape-dts 会定期把同步位点写入进度日志 position.log(默认每 10 秒,可通过 [pipeline] 的 checkpoint_interval_secs 调整)。
问题来了:任务中断后直接重启会怎样?
- ❌ 默认情况下,重启后的任务会从
task_config.ini中[extractor]配置的初始位点重新开始; - ❌ 已同步过的数据被重复写入,浪费资源甚至污染目标库。
而启用断点续传后,任务会从 position.log 记录的中断前的最新位点继续,实现"停在哪里、就从哪里继续"。在跨机房容灾、多节点长期同步等场景(如三节点间多个 task 持续运转),任务中断难以避免,断点续传几乎必不可少:
📖 完整原理参考官方文档:docs/zh/cdc/resume.md,位点详解见 docs/zh/monitor/position.md。
二、支持范围:哪些源端可以断点续传?
增量(CDC)任务断点续传目前支持三种源端:
| 源端 | 位点标识 | 说明 |
|---|---|---|
| MySQL | binlog_filename + next_event_position |
开启 GTID 时用 gtid_set |
| Postgres | lsn(事务日志序号) |
例如 0/406E2C30 |
| Mongo | operation_time 或 resume_token |
取决于 source 配置 |
⚠️ Redis 源端虽会记录位点,但暂不支持断点续传。
三、读懂 position.log:checkpoint_position 与 current_position 有何区别?
理解位点日志是精准恢复的关键。ape-dts 为增量任务记录两份位点信息:
current_position:已同步数据的位点,可能停在源库某个大事务 binlog 的中间;checkpoint_position:已同步的完整事务的位点。
ape-dts 只保证目标库与源库的最终一致性,不保证事务中途的原子性。如果从 current_position(事务中间位置)恢复,extractor 可能无法正确解析增量数据。因此:
💡 断点续传优先使用
checkpoint_position作为新任务的起点,牺牲极少量数据换来源端解析的可靠性。
各源端位点示例(MySQL,开启 GTID 时 gtid_set 不为空):
2024-10-18 05:21:45.207788 | checkpoint_position | {"type":"MysqlCdc","server_id":"","binlog_filename":"mysql-bin.000004","next_event_position":73685,"gtid_set":"","timestamp":"2024-10-18 05:21:44.000"}
Postgres 则记录 LSN:
2024-10-10 09:09:52.260052 | checkpoint_position | {"type":"PgCdc","lsn":"0/406E2C30","timestamp":"2024-10-10 08:12:31.421"}
这些位点的解析逻辑定义在 dt-common/src/meta/position.rs 中,ape-dts 会自动从日志行中提取 JSON 位点结构。
四、一键开启断点续传:[resumer] 配置完整指南 🔧
ape-dts 通过 <a href="https://link.gitcode.com/i/1571e1452c146c05d5d727f218b29842" target="_blank">resumer] 配置段控制断点续传行为,对应结构见 [dt-common/src/config/resumer_config.rs。共有三个参数:
resume_from_log:是否从position.log断点续传(推荐)resume_log_dir:位点日志目录,默认与任务日志同目录resume_config_file:用户自定义的位点文件,适用于自研管控系统
方法 1:从进度日志断点续传(推荐)
只需在 task_config.ini 中加一行:
[resumer]
resume_from_log=true
任务重启后,ape-dts 会读取 resume_log_dir/position.log 中最新的位置记录,自动以此作为同步起点。其加载逻辑在 dt-connector/src/extractor/resumer/cdc_resumer.rs。
⚠️ 注意:重启后的新任务和中断前的旧任务必须使用同一个日志目录,否则读不到旧的
position.log,断点续传不会生效。
方法 2:指定位点信息文件
如果你基于 ape-dts 开发了自己的管控系统,不想依赖默认的 position.log,可以手动准备一个位点文件:
[resumer]
resume_config_file=./resume.config
resume.config 内容格式与 position.log 的行格式保持一致(可省略行首时间戳)。MySQL 源端还会将该位点应用到 binlog 解析器:
dt-connector/src/extractor/mysql/mysql_cdc_extractor.rs
位点提取核心代码见 mysql_cdc_extractor.rs——从 checkpoint_position 中取出 binlog_filename、next_event_position、gtid_set 作为重启起点。
两种方法如何选择?
| 场景 | 推荐方式 |
|---|---|
| 单机运维、手动重启任务 | 方法 1(resume_from_log=true) |
| 自研管控平台、跨机器迁移任务 | 方法 2(resume_config_file) |
五、如何验证恢复成功?看 default.log 里的 resume from 日志 ✅
任务重启后,打开 default.log,看到类似下面的日志即表示断点续传生效:
2024-10-18 07:34:29.702024 - INFO - resume from: {"type":"MysqlCdc","server_id":"","binlog_filename":"mysql-bin.000004","next_event_position":73685,...}
2024-10-18 07:34:29.702621 - INFO - MysqlCdcExtractor starts, binlog_filename: mysql-bin.000004, binlog_position: 73685, ...
resume from 后面的位点,应该和中断前 position.log 中最后一条 checkpoint_position 完全一致。如果日志里没有 resume from,说明断点续传没有命中(通常是日志目录不一致或配置缺失)。
六、常见问题与注意事项 💡
-
源端 binlog 已被清理怎么办? 若
position.log记录的binlog_filename在源端已不存在,任务将启动失败。请务必保证源端 binlog 保留时间大于任务最长可能的中断时长。 -
使用 GTID 的 MySQL 任务如何恢复? 位点以
gtid_set(事务集合)为准,恢复时 ape-dts 会自动按 GTID 跳过已同步的事务,天然幂等。 -
Mongo 任务为什么用的是 current_position? Mongo 增量任务没有记录
checkpoint_position,op_log模式用operation_time、change_stream模式用resume_token恢复,见 mongo_cdc_extractor.rs。 -
位点记录频率可以调吗? 可以。
checkpoint_interval_secs越大,中断后可能"回退"重放的窗口越大;调小(如 5 秒)可减少重放范围,但会略增日志写压力。 -
全量(snapshot)任务也支持断点续传吗? 支持,原理类似但读取
position.log+finished.log,配置方式详见 docs/zh/snapshot/resume.md,官方测试用例见 dt-tests/tests/mysql_to_mysql/snapshot/resume_test。
总结
ape-dts 的断点续传机制非常清晰:运行中定期把完整事务位点写入 position.log → 任务重启时由 [resumer] 读取最新位点 → extractor 从该位点继续解析同步。只需一行 resume_from_log=true 配置,即可让中断的 MySQL、Postgres、Mongo 增量任务精准恢复到中断处,真正做到不丢数据、不重复写入,是搭建高可用容灾与迁移平台的必备能力。

