taps 断点续传详解:如何从存储的 Session 文件恢复中断的大表迁移

原创2026-10-13 13:03:431,340 阅读

taps 断点续传详解:如何从存储的 Session 文件恢复中断的大表迁移

taps 是一款简单的数据库导入/导出工具(simple database import/export app),可以通过 push / pull 在两个数据库之间传输数据。当你迁移几十上百万行的大表时,传输可能因网络抖动、服务器异常或误按 Ctrl+C 而中断——taps 内置的断点续传机制会在中断瞬间把迁移进度写入本地的 Session 文件,下次执行时带上 -r 参数即可从断点恢复,不必从头再来。

一、taps Session 文件是如何生成的

Session 文件在客户端运行目录自动生成,有两类触发时机:

中断方式 触发路径 结果
按 Ctrl+C(INT/TERM 信号) setup_signal_trap 捕获信号后打印 Completing current action...,再调用 store_session 保存 Session,进程正常退出(exit 0)
网络错误、服务器异常 catch_errors 捕获到 RestClient::Exception 或 Taps::BaseError 后自动保存 保存 Session,进程以 exit 1 退出

文件命名规则是前缀 + 时间戳:

  • pull 操作:pull_202610130609.dat
  • push 操作:push_202610130609.dat

⚠️ 注意:Session 文件写在你执行命令时所在的当前目录,中断后先 ls pull_*.dat push_*.dat 找到它。

二、Session 文件里记录了什么

Session 是一个 JSON 文本文件(由 OkJson 编码),可直接用文本编辑器打开,核心字段有 6 个:

{
  "klass": "Taps::Pull",
  "database_url": "postgres://dbuser:***@localhost/dbname",
  "remote_url": "http://httpuser:***@example.com:5000",
  "session_uri": "/sessions/123456789",
  "stream_state": { "table_name": "logs", "offset": 58000, "chunksize": 320, "..." : "..." },
  "completed_tables": ["users", "tags"],
  "table_filter": "^log_"
}

各字段含义:

  • klass:操作类型(Taps::Pull 或 Taps::Push),恢复时据此决定如何续传
  • stream_state:中断时那张表的传输位置,包括表名、offset 偏移量或主键位置、chunksize 分片大小等(详见 data_stream.rb)
  • completed_tables:已经传输完的表清单,恢复时直接跳过
  • session_uri:远程 taps server 上对应的会话键(服务端会话由 DbSession 管理)

💡 也就是说:Session 文件 = “哪张表 + 传到哪一行 + 哪些表已完成 + 连的是哪个服务器”,信息足够让 taps 精准续传。

三、三步恢复中断的大表迁移

第 1 步:确认 taps server 仍在运行

taps server 端保存着会话信息,恢复前请先确认服务进程还活着(可用 curl <remote_url>/health 探测)。

第 2 步:执行带 -r 参数的恢复命令

-r, --resume=file 参数即“Resume a Taps Session from a stored file”,定义见 cli.rb。

# 恢复一次中断的 pull
taps pull -r pull_202610130609.dat postgres://dbuser:dbpass@localhost/dbname

# 恢复一次中断的 push(remote_url 可省略,会自动从 Session 文件读取)
taps push -r push_202610130609.dat mysql://dbuser:dbpass@localhost/dbname http://httpuser:httppassword@example.com:5000

解析逻辑在 clientresumexfer:读取 Session 文件 → 反序列化 → 合并 :resume => true 标记 → 交给 Operation.factory 按 klass 重建对应操作对象。

第 3 步:观察输出,确认从断点继续

恢复运行时你会看到类似这样的输出:

Resuming logs, 1,204,555 records

说明 taps 正基于 stream_state 重建数据流,从中断的那张表继续传输,而不是从头开始。

四、断点续传的内部机制:如何精准定位断点

taps 的续传并不是“重传整张表”,而是行级定位,核心流程在 Pull#run / Push#run:

  1. 跳过 schema 传输:resuming? 为 true 时不再重复拉取/推送表结构,直接进入数据阶段
  2. 续传中断的那张表:pull_partial_data(push 对应 push_partial_data)用 stream_state 通过 DataStream.factory 重建数据流
  3. 按主键或偏移量定位:
    • 带单整数主键的表使用 DataStreamKeyed,按上次传输到的主键值(filter)继续,效率更高
    • 无主键的表使用 DataStream,按 offset 行偏移继续
  4. 跳过已完成的表:tables 方法会过滤掉 completed_tables 中的表
  5. 保留调优状态:taps 会动态调整 chunksize 分片大小(目标让每个分片网络传输耗时保持在合理区间),这个状态也保存在 Session 中,恢复后传输速率无需重新爬坡

五、实用注意事项与常见问题

  • ✅ Ctrl+C 是正确姿势:优雅中断会触发信号陷阱并保存 Session;kill -9 强制杀死进程则不会保存任何信息
  • ✅ 恢复时必须提供本地 database_url;remote_url 可以省略,taps 会从 Session 文件里取
  • ⚠️ 远程 server 不能重启过:默认情况下服务端的会话存储在临时 SQLite 文件里(见 cli.rb 第 8-14 行),server 进程重启后旧的 session_uri 失效,Session 文件也就无法使用了
  • ⚠️ 版本要求:服务端会校验版本,不一致时返回 HTTP 417(见 server.rb 的 before 钩子),请先升级客户端再恢复
  • ⚠️ Session 文件与过滤条件绑定:table_filter 也记录在 Session 中,如果中断后你想改用不同的 --tables / --filter 参数,建议使用较新的 Session 文件或重新发起传输
  • 💡 迁移完成后 taps 会自动调用 DELETE /sessions/:key 清理服务端会话,无需手动处理

六、相关源码与资料

模块 文件 作用
操作与 Session 保存 lib/taps/operation.rb Pull/Push 主流程、store_session、信号捕获
命令行参数 lib/taps/cli.rb -r 参数解析与 clientresumexfer 恢复逻辑
数据流与断点定位 lib/taps/data_stream.rb DataStream / DataStreamKeyed 状态管理
分片调优 lib/taps/chunksize.rb 动态计算传输 chunksize
服务端会话 lib/taps/server.rb、lib/taps/db_session.rb 会话创建、push/table、pull/table 接口
使用说明 README.rdoc server/pull/push 基础用法

掌握以上机制后,面对任何一次中断的大表迁移,你只需要找到对应的 .dat Session 文件,用 -r 参数重新执行原命令,taps 就会自动跳过已完成的部分、从中断的行继续传输。

登录后查看全文
taps