ape-dts 断点续传详解:任务中断后如何从 position.log 精准恢复

原创2026-11-15 12:40:201,941 阅读

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 断点续传所处的 pipeline 同步架构

任务运行期间,ape-dts 会定期把同步位点写入进度日志 position.log(默认每 10 秒,可通过 [pipeline] 的 checkpoint_interval_secs 调整)。

问题来了:任务中断后直接重启会怎样?

  • ❌ 默认情况下,重启后的任务会从 task_config.ini 中 [extractor] 配置的初始位点重新开始;
  • ❌ 已同步过的数据被重复写入,浪费资源甚至污染目标库。

而启用断点续传后,任务会从 position.log 记录的中断前的最新位点继续,实现"停在哪里、就从哪里继续"。在跨机房容灾、多节点长期同步等场景(如三节点间多个 task 持续运转),任务中断难以避免,断点续传几乎必不可少:

ape-dts 断点续传适用的多节点同步容灾场景

📖 完整原理参考官方文档: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,说明断点续传没有命中(通常是日志目录不一致或配置缺失)。

六、常见问题与注意事项 💡

  1. 源端 binlog 已被清理怎么办? 若 position.log 记录的 binlog_filename 在源端已不存在,任务将启动失败。请务必保证源端 binlog 保留时间大于任务最长可能的中断时长。

  2. 使用 GTID 的 MySQL 任务如何恢复? 位点以 gtid_set(事务集合)为准,恢复时 ape-dts 会自动按 GTID 跳过已同步的事务,天然幂等。

  3. Mongo 任务为什么用的是 current_position? Mongo 增量任务没有记录 checkpoint_position,op_log 模式用 operation_time、change_stream 模式用 resume_token 恢复,见 mongo_cdc_extractor.rs。

  4. 位点记录频率可以调吗? 可以。checkpoint_interval_secs 越大,中断后可能"回退"重放的窗口越大;调小(如 5 秒)可减少重放范围,但会略增日志写压力。

  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 增量任务精准恢复到中断处,真正做到不丢数据、不重复写入,是搭建高可用容灾与迁移平台的必备能力。

登录后查看全文
ape-dts