TDengine 数据备份与恢复实战:taosdump 全量逻辑备份与 taosx 增量恢复详解
TDengine 数据备份与恢复实战:taosdump 全量逻辑备份与 taosx 增量恢复详解
TDengine 提供了两条互补的备份恢复路线:开源版使用 taosdump 工具将数据库以逻辑数据单元形式导出到本地文件并可跨集群导入;企业版则基于数据订阅实现增量备份,通过 taosx 命令行将备份文件链重放恢复到指定时间点。本文结合仓库中 taosdump 的源码实现,完整讲解备份、恢复、备份计划管理、跨集群迁移与常见故障排查,帮助你在数据丢失或损坏时能够快速、可验证地完成恢复。
一、两种备份方案总览
TDengine 的备份与恢复能力分为两层:
-
taosdump(开源工具,全量/时间范围逻辑备份)
taosdump支持从运行中的 TDengine 集群导出数据,并恢复到同一集群或另一个运行中的集群。它既可以按数据库整体备份(逻辑数据单元),也可以只备份数据库中指定时间段内的数据记录。使用时可指定备份文件的存放目录;若不指定,默认备份到当前目录。工具源码位于 tools/taosdump,包含备份(backup/)、恢复(restore/)、存储适配(storage/,支持 binary 与 parquet 两种数据文件格式)等子模块。 -
企业版增量备份与恢复(基于数据订阅) TDengine Enterprise 利用数据订阅能力实现增量备份:备份对象(数据库或超级表)的全部数据变更(新增、修改、删除、元数据变更等)被记录为备份文件,配合周期性备份计划形成一系列备份点,最终可将对象恢复到任意指定备份点。
两者定位不同:taosdump 适合离线导出、迁移、归档与灾难恢复演练;企业版增量备份适合需要周期性、小粒度备份与时间点恢复(PITR)的生产场景。
二、使用 taosdump 备份数据
基本备份命令
taosdump -h localhost -P 6030 -D dbname -o /file/path
执行后,taosdump 连接 localhost:6030 上的 TDengine 集群,查询数据库 dbname 中的全部数据并导出到 /file/path。
重要约束:如果指定的输出路径中已存在数据文件,taosdump 会提示用户并立即退出,以避免覆盖已有数据。也就是说同一存储路径只能用于一次备份,看到相关提示时务必谨慎操作,避免误删或误覆盖导致数据丢失。
从源码看,该行为与工具的"优雅退出"设计一致:main 入口注册了 SIGINT/SIGTERM 信号处理(Windows 下使用控制台控制处理器),中断路径会输出统计摘要并以用户取消码退出,见 tools/taosdump/src/main.c。
完整命令行参数
taosdump 的完整用法与选项定义在 tools/taosdump/src/core/bckArgs.c 的 printUsage 中,运行 taosdump --help 即可看到,核心参数如下:
| 参数 | 说明 |
|---|---|
-h, --host=HOST |
服务器主机,默认 localhost |
-P, --port=PORT |
服务器端口,默认 6030 |
-u, --user=USER |
用户名,默认 root |
-p / -pPASSWORD / --password=PASSWORD |
密码;单独 -p 会交互式提示输入(回显关闭),密码不会以明文写入日志(main.c 中对 -p/-X 参数做了脱敏处理) |
-c, --config-dir=CONFIG_DIR |
配置文件目录,默认 /etc/taos(Windows 为 C:\TDengine\cfg) |
-D, --databases=DB1,DB2 |
要备份/恢复的数据库列表,逗号分隔;缺省时为全部(备份时排除系统库) |
位置参数 dbname [tbname ...] |
指定单个数据库及若干表名 |
-o, --outpath=OUTPATH |
备份输出路径 |
-i, --inpath=INPATH |
恢复时的输入文件路径 |
-F, --format=FORMAT |
数据文件格式:binary(默认)或 parquet |
-M, --content=CONTENT |
备份内容范围:basic(默认,超表/子表/普通表元数据与时序数据)、ext-meta(流/虚拟表/主题元数据)、all(两者之和) |
-S, --start-time / -E, --end-time |
备份时间范围,支持 epoch 毫秒或 ISO8601,如 2025-10-01T00:00:00.000+0800 |
-T, --thread-num |
数据备份/恢复线程数,默认 8 |
-m, --tag-thread-num |
Tag 备份线程数,默认 2 |
-k, --retry-count / -z, --retry-sleep-ms |
失败重试次数(默认 10)与重试间隔毫秒(默认 1000) |
-s, --schemaonly |
仅备份表结构,不导出数据 |
-C, --checkpoint |
断点续传:从上次检查点继续(检查点文件始终会写入,-C 用于跳过已完成项) |
-X, --dsn=DSN |
连接云服务的 DSN,如 https://host?token=<TOKEN>;也支持环境变量 TDENGINE_CLOUD_DSN |
-Z, --driver=DRIVER |
连接协议:Native(6030 端口,默认,更快)或 WebSocket(6041 端口,无需安装客户端驱动);设置 DSN 时默认 WebSocket |
-W, --rename=RENAME-LIST |
恢复时重命名数据库,格式 "db1->newdb1|db2->newdb2|..."(目标库名会经标识符合法性校验后才会拼入 SQL) |
-v, --stmt-version |
恢复使用的 STMT API 版本:2(默认,更快)或 1(旧版) |
-B, --data-batch |
恢复时单条 insert stmt 的行数(仅恢复生效) |
-g, --debug / -V, --version |
调试模式 / 打印版本 |
备份流程与产物
从源码结构看,备份入口是 backupMain,恢复入口是 restoreMain,main.c 负责连接池初始化(数据线程每个需要 2 个连接、Tag 线程每个 1 个连接,外加少量主线程连接)、启动摘要打印与进度显示。
运行结束时,taosdump 会打印(并写入日志)一份完整的统计摘要,包括:数据库总数/成功/失败数、超表数、子表数、总行数、普通表数、数据文件总数/跳过数/失败数、输出目录总大小、耗时与起止时间,见 printEndSummary。因此判断一次备份是否真正成功,应以该摘要中的 Result: SUCCESS 与行数统计为准,而不是仅看进程退出码。
日志行为值得注意:
- 备份模式下日志写入
<outPath>/backup.log,每次运行截断;但使用-C断点续传时改为追加,避免丢失上次尝试的日志; - 恢复模式下日志写入当前目录
restore.log,跨运行追加; - 日志中记录的命令行会对密码与 DSN 自动脱敏。
典型备份命令示例:
# 备份整个数据库(默认二进制格式、全量数据)
taosdump -h localhost -P 6030 -u root -D db1 -o /backup/db1_full
# 只备份 2025 年内的数据
taosdump -h localhost -D db1 -S 2025-01-01T00:00:00.000+0800 \
-E 2026-01-01T00:00:00.000+0800 -o /backup/db1_2025
# 仅备份表结构
taosdump -D db1 -s -o /backup/db1_schema
# 备份失败中断后断点续传
taosdump -D db1 -o /backup/db1_full -C
三、使用 taosdump 恢复数据
将本地备份文件恢复到运行中的 TDengine 集群,使用 -i 指定备份文件路径:
taosdump -i /file/path -h localhost -P 6030
执行后,taosdump 连接 localhost:6030 的集群,并将 /file/path 中的备份文件恢复进去。恢复时的实用参数:
# 恢复到不同库名(不覆盖原库)
taosdump -i /backup/db1_full -W 'db1->db1_restored' -h localhost -P 6030
# 调大恢复批次、使用 STMT2 加速
taosdump -i /backup/db1_full -v 2 -B 1024 -T 16
恢复同样支持 -C 断点续传(跳过检查点中已完成的数据文件),结束后会打印"已恢复子表数 / 总行数 / 跳过文件数"等摘要。
四、TDengine 企业版增量备份与恢复
核心概念
企业版的备份与恢复功能包含以下 6 个概念(原文档定义,此处完整保留):
- 增量数据备份(Incremental data backup):基于 TDengine 的数据订阅功能,备份对象的所有数据变更(新增、修改、删除、元数据变更等)被记录并生成备份文件。
- 数据恢复(Data recovery):使用增量备份生成的备份文件,将备份对象恢复到指定时间点。
- 备份对象(Backup object):用户备份的对象可以是数据库或超级表。
- 备份计划(Backup plan):为备份对象创建的周期性备份任务。计划从指定时间点开始,按备份周期周期执行;每次执行生成一个备份点。
- 备份点(Backup point):每次备份任务执行产生一组备份文件,对应一个时间点,称为一个备份点;第一个备份点称为初始备份点。
- 恢复任务(Restore task):用户从备份计划中选定某个备份点并创建恢复任务;恢复任务从初始备份点开始,逐个重放备份文件中的数据变更,直到指定备份点结束。
以"每天执行一次、从 2024-08-27 00:00:00 开始的备份计划"为例,过程为:
- 用户创建备份计划,从 2024-08-27 00:00:00 起每 1 天执行一次备份任务;
- 首次备份任务于 2024-08-27 00:00:00 执行,生成初始备份点;
- 此后每天执行一次备份任务,生成多个备份点;
- 用户选择某个备份点并创建恢复任务;
- 恢复任务从初始备份点开始,逐个应用备份点,最终恢复到指定备份点。
在 taosExplorer 中创建备份计划
- 在浏览器中打开运行 TDengine 的主机名或 IP 地址上的 6060 端口的 taosExplorer 界面;
- 在左侧主菜单点击 Management,打开 Backup 选项卡;
- 在 Backup Plan 下点击 Create New Backup,定义备份计划,各字段说明如下:
- Database:选择要备份的数据库;
- Super Table(可选):选择要备份的超级表。不选则备份数据库中全部数据;
- Next execution time:本次计划首次备份的日期时间。若指定了过去的时间,则立即执行首次备份;
- Backup Cycle:增量备份的周期。该值必须小于所指定数据库的
WAL_RETENTION_PERIOD; - Retry times:备份任务失败后的重试次数(适用于重试可能解决的瞬时故障);
- Retry interval:两次重试之间的间隔秒数;
- Directory:备份文件存储目录的完整路径;
- Backup file max size:单个备份文件的最大大小;总大小超过该值时,备份会被拆分为多个文件;
- Compression level:选择 fastest(性能最快、压缩率最低)、best(压缩率最高、性能最慢)或 balanced(性能与压缩率的折中)。
- 可启用 S3 dumping,将备份文件上传到 S3 存储服务。启用时需填写:
- Endpoint:S3 端点地址;
- Access Key ID:认证用访问密钥 ID;
- Secret Access Key:认证用秘密访问密钥;
- Bucket:目标桶名称;
- Region:桶所在区域;
- Object Prefix:备份文件对象的前缀,类似 S3 上的目录路径;
- Backup Retention Period:本地备份的保留时长。所有早于
当前时间 - backup_retention_period的文件都必须已上传到 S3; - Backup Retention Count:本地保留的备份份数,仅保留最新
backup_retention_size份备份文件。
- 点击 Confirm 创建备份计划。
创建后可在列表的 Operation 列修改、克隆或删除计划,点击 Refresh 刷新状态。注意:必须先停止备份计划才能删除它。也可以点击 Backup File 列的 View 查看各备份点生成的备份记录与文件。
在 taosExplorer 中执行恢复
- 找到包含目标数据的备份计划,点击 Backup File 列的 View;
- 确定要恢复到的备份记录点,点击 Operation 列的 Restore 图标;
- 选择备份文件时间戳与目标数据库,点击 Confirm。
五、使用 taosx 恢复到另一个集群
除了在 taosExplorer 中创建恢复任务,还可以将备份文件复制到另一个集群,用 taosx 命令行接口完成跨集群恢复(如灾备切换、测试环境重建)。
备份目录结构
新的任务级备份直接存放在任务 ID 目录中:
<backup-root>/
└── <task_id>/
├── .taosx-backup-layout
├── <topic>-<timestamp>-<vgroup>-<index>.z
├── <topic>-<timestamp>-<vgroup>-<index>.mz
└── ...
关键规则:
- 新的任务级备份写入器会在任务 ID 目录中创建隐藏的
.taosx-backup-layout标记文件,声明备份产物是直接存放在任务目录(task_dir)还是历史-1子目录(legacy_job_dir)。存在该标记时,taosx以它为准,不再探测另一种布局。必须保留该标记,不要手工编辑或重建它。 - 布局标记不是 HA 锁。 升级期间,不要让不识别该标记的旧版
taosx与识别它的新版并发写入同一个备份任务:应停止备份任务并确认旧进程已退出后再切换版本。若task_dir标记已经创建,则即使新进程已退出,也不要用不识别该标记的旧版恢复同一任务与备份根目录继续追加,否则新旧文件会被写入不同目录。回滚时应使用新的任务 ID 或新的备份根目录,而不是继续向既有备份链追加。 - 只有真正从任务中拆分出的 job 才使用
<task_id>/<job_id>子目录;任务级备份不需要 job 目录,恢复命令中也无需 job ID。恢复流程会自动识别早期版本创建的任务级目录。 - 若要从实际的 job 恢复,复制包含
.z和.mz文件的 job 目录,并让local:直接指向该目录。
跨集群恢复步骤(以任务级备份为例)
-
停止集群 A 上的备份任务,或确认待恢复的备份点已经生成。
-
将完整任务目录复制到集群 B,保持目录层级与原始备份文件名不变。例如:
rsync -a /backup/10/ user@cluster-b:/tmp/10/必须复制包含隐藏文件
.taosx-backup-layout在内的完整任务目录。rsync -a会保留隐藏文件;不要用/backup/10/*这类 shell 通配符复制,它会漏掉隐藏文件。增量恢复需要"从初始备份点到目标点"的完整文件链;若备份目录中存在.mz文件,也要一并复制。 -
在集群 B 上递归校验任务目录包含备份文件:
find /tmp/10 -type f \( -name '.taosx-backup-layout' -o -name '*.z' -o -name '*.mz' \) -print -
在
local:后直接指定复制好的任务目录。下例将任务10的备份恢复到集群 B 的db01库:taosx run \ -f 'local:/tmp/10?to=now&watch=false' \ -t 'taos:///db01' \ -vv对于没有布局标记的历史任务级目录,可以显式指定布局以跳过旧版兼容性探测:
# 备份文件直接存放在 /tmp/10 taosx run \ -f 'local:/tmp/10?to=now&watch=false&layout=task_dir' \ -t 'taos:///db01' \ -vv # 备份文件存放在 /tmp/10/-1 taosx run \ -f 'local:/tmp/10?to=now&watch=false&layout=legacy_job_dir' \ -t 'taos:///db01' \ -vvlayout参数只适用于任务级备份。当布局标记存在时,显式layout必须与之匹配,否则恢复失败。只读恢复不会创建布局标记。 -
检查
taosx日志中处理的文件数与行数,并查询目标集群验证恢复的数据。仅凭零退出码不能证明数据已被恢复。
当布局标记与显式 layout 都不存在时,taosx 会执行旧版兼容性探测,并记录告警 backup layout marker is missing; using legacy layout detection。只有在这种情况下,如果任务目录与其历史 -1 子目录中同时存在备份文件,恢复才会报出目录布局冲突。此时应检查两处位置,把完整文件链合并整理到一个独立的恢复目录中再重试;内容不同的同名文件不要互相覆盖。
六、故障排查
端口访问异常
典型报错:
Error: tmq to td task exec error
Caused by:
[0x000B] Unable to establish connection
出现该错误时,检查数据源 FQDN 是否可达、6030 端口是否在监听且可访问。
连接问题(WebSocket)
任务无法启动并报 DNS 相关错误:
Error: tmq to td task exec error
Caused by:
0: WebSocket internal error: IO error: failed to lookup address information: Temporary failure in name resolution
1: IO error: failed to lookup address information: Temporary failure in name resolution
2: failed to lookup address information: Temporary failure in name resolution
WebSocket 连接的常见错误及排查方向:
- "Temporary failure in name resolution":DNS 解析错误。检查所指定的 IP 地址或 FQDN 是否可正常访问;
- "IO error: Connection refused (os error 111)":端口访问失败。检查端口是否正确配置、已启用且可访问;
- "IO error: received corrupt message":消息解析失败。可能是以 WSS 方式启用了 SSL,但源端口不支持;
- "HTTP error: *":确认连接的是正确的 taosAdapter 端口,且负载均衡/Nginx/代理配置正确;
- "WebSocket protocol error: Handshake not finished":WebSocket 连接错误,通常由端口配置不正确引起。
WAL 配置问题
任务无法启动并报:
Error: tmq to td task exec error
Caused by:
[0x038C] WAL retention period is zero
原因是备份对象数据库的 WAL 保留期为 0。增量备份依赖 WAL 中保留的变更日志,因此备份周期必须小于 WAL_RETENTION_PERIOD。解决方法是为受影响数据库设置 WAL 保留期:
ALTER DATABASE test WAL_RETENTION_PERIOD 3600;
从源码看,该校验落在管理节点(mnode):创建/修改数据库配置时,mnode 会校验 walRetentionPeriod 不得小于 TSDB_DB_MIN_WAL_RETENTION_PERIOD,修改时仅允许增大(或保持不变),见 source/dnode/mnode/impl/src/mndDb.c;数据库配置结构体中该字段定义于 mndDef.h。这也解释了文档中"备份周期必须小于 WAL_RETENTION_PERIOD"这一约束的由来:WAL 日志被清理后,超出保留期的变更将无法被增量备份捕获。
七、小结
- 开源场景下,
taosdump是数据备份与恢复的主力工具:支持全库或时间范围导出、binary/parquet 格式、多线程、断点续传与恢复时库重命名;备份输出目录不可复用,成功与否应以运行摘要的统计为准(参数全集见 tools/taosdump/src/core/bckArgs.c)。 - 企业版增量备份以数据订阅为底座,通过"备份计划 + 备份点 + 恢复任务"三个层次实现周期性时间点恢复;备份周期必须小于目标库
WAL_RETENTION_PERIOD(见 source/dnode/mnode/impl/src/mndDb.c)。 - 跨集群恢复时,务必使用
rsync -a复制包含.taosx-backup-layout隐藏标记在内的完整任务目录,恢复后用日志行数与目标集群查询双重验证,不能只看退出码。