taps 断点续传详解:如何从存储的 Session 文件恢复中断的大表迁移
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:
- 跳过 schema 传输:
resuming?为 true 时不再重复拉取/推送表结构,直接进入数据阶段 - 续传中断的那张表:pull_partial_data(push 对应 push_partial_data)用
stream_state通过 DataStream.factory 重建数据流 - 按主键或偏移量定位:
- 带单整数主键的表使用 DataStreamKeyed,按上次传输到的主键值(
filter)继续,效率更高 - 无主键的表使用 DataStream,按
offset行偏移继续
- 带单整数主键的表使用 DataStreamKeyed,按上次传输到的主键值(
- 跳过已完成的表:tables 方法会过滤掉
completed_tables中的表 - 保留调优状态: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 就会自动跳过已完成的部分、从中断的行继续传输。