TDengine 数据备份与恢复实战:taosdump 全量逻辑备份与 taosx 增量恢复详解

原创2026-09-19 09:20:151,908 阅读
文章标签:数据库时序数据库后端物联网大数据云原生

TDengine 数据备份与恢复实战:taosdump 全量逻辑备份与 taosx 增量恢复详解

TDengine 提供了两条互补的备份恢复路线:开源版使用 taosdump 工具将数据库以逻辑数据单元形式导出到本地文件并可跨集群导入;企业版则基于数据订阅实现增量备份,通过 taosx 命令行将备份文件链重放恢复到指定时间点。本文结合仓库中 taosdump 的源码实现,完整讲解备份、恢复、备份计划管理、跨集群迁移与常见故障排查,帮助你在数据丢失或损坏时能够快速、可验证地完成恢复。

一、两种备份方案总览

TDengine 的备份与恢复能力分为两层:

  1. taosdump(开源工具,全量/时间范围逻辑备份) taosdump 支持从运行中的 TDengine 集群导出数据,并恢复到同一集群或另一个运行中的集群。它既可以按数据库整体备份(逻辑数据单元),也可以只备份数据库中指定时间段内的数据记录。使用时可指定备份文件的存放目录;若不指定,默认备份到当前目录。工具源码位于 tools/taosdump,包含备份(backup/)、恢复(restore/)、存储适配(storage/,支持 binary 与 parquet 两种数据文件格式)等子模块。

  2. 企业版增量备份与恢复(基于数据订阅) 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 个概念(原文档定义,此处完整保留):

  1. 增量数据备份(Incremental data backup):基于 TDengine 的数据订阅功能,备份对象的所有数据变更(新增、修改、删除、元数据变更等)被记录并生成备份文件。
  2. 数据恢复(Data recovery):使用增量备份生成的备份文件,将备份对象恢复到指定时间点。
  3. 备份对象(Backup object):用户备份的对象可以是数据库或超级表。
  4. 备份计划(Backup plan):为备份对象创建的周期性备份任务。计划从指定时间点开始,按备份周期周期执行;每次执行生成一个备份点。
  5. 备份点(Backup point):每次备份任务执行产生一组备份文件,对应一个时间点,称为一个备份点;第一个备份点称为初始备份点。
  6. 恢复任务(Restore task):用户从备份计划中选定某个备份点并创建恢复任务;恢复任务从初始备份点开始,逐个重放备份文件中的数据变更,直到指定备份点结束。

以"每天执行一次、从 2024-08-27 00:00:00 开始的备份计划"为例,过程为:

  1. 用户创建备份计划,从 2024-08-27 00:00:00 起每 1 天执行一次备份任务;
  2. 首次备份任务于 2024-08-27 00:00:00 执行,生成初始备份点;
  3. 此后每天执行一次备份任务,生成多个备份点;
  4. 用户选择某个备份点并创建恢复任务;
  5. 恢复任务从初始备份点开始,逐个应用备份点,最终恢复到指定备份点。

在 taosExplorer 中创建备份计划

  1. 在浏览器中打开运行 TDengine 的主机名或 IP 地址上的 6060 端口的 taosExplorer 界面;
  2. 在左侧主菜单点击 Management,打开 Backup 选项卡;
  3. 在 Backup Plan 下点击 Create New Backup,定义备份计划,各字段说明如下:
    1. Database:选择要备份的数据库;
    2. Super Table(可选):选择要备份的超级表。不选则备份数据库中全部数据;
    3. Next execution time:本次计划首次备份的日期时间。若指定了过去的时间,则立即执行首次备份;
    4. Backup Cycle:增量备份的周期。该值必须小于所指定数据库的 WAL_RETENTION_PERIOD;
    5. Retry times:备份任务失败后的重试次数(适用于重试可能解决的瞬时故障);
    6. Retry interval:两次重试之间的间隔秒数;
    7. Directory:备份文件存储目录的完整路径;
    8. Backup file max size:单个备份文件的最大大小;总大小超过该值时,备份会被拆分为多个文件;
    9. Compression level:选择 fastest(性能最快、压缩率最低)、best(压缩率最高、性能最慢)或 balanced(性能与压缩率的折中)。
  4. 可启用 S3 dumping,将备份文件上传到 S3 存储服务。启用时需填写:
    1. Endpoint:S3 端点地址;
    2. Access Key ID:认证用访问密钥 ID;
    3. Secret Access Key:认证用秘密访问密钥;
    4. Bucket:目标桶名称;
    5. Region:桶所在区域;
    6. Object Prefix:备份文件对象的前缀,类似 S3 上的目录路径;
    7. Backup Retention Period:本地备份的保留时长。所有早于 当前时间 - backup_retention_period 的文件都必须已上传到 S3;
    8. Backup Retention Count:本地保留的备份份数,仅保留最新 backup_retention_size 份备份文件。
  5. 点击 Confirm 创建备份计划。

创建后可在列表的 Operation 列修改、克隆或删除计划,点击 Refresh 刷新状态。注意:必须先停止备份计划才能删除它。也可以点击 Backup File 列的 View 查看各备份点生成的备份记录与文件。

在 taosExplorer 中执行恢复

  1. 找到包含目标数据的备份计划,点击 Backup File 列的 View;
  2. 确定要恢复到的备份记录点,点击 Operation 列的 Restore 图标;
  3. 选择备份文件时间戳与目标数据库,点击 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: 直接指向该目录。

跨集群恢复步骤(以任务级备份为例)

  1. 停止集群 A 上的备份任务,或确认待恢复的备份点已经生成。

  2. 将完整任务目录复制到集群 B,保持目录层级与原始备份文件名不变。例如:

    rsync -a /backup/10/ user@cluster-b:/tmp/10/
    

    必须复制包含隐藏文件 .taosx-backup-layout 在内的完整任务目录。rsync -a 会保留隐藏文件;不要用 /backup/10/* 这类 shell 通配符复制,它会漏掉隐藏文件。增量恢复需要"从初始备份点到目标点"的完整文件链;若备份目录中存在 .mz 文件,也要一并复制。

  3. 在集群 B 上递归校验任务目录包含备份文件:

    find /tmp/10 -type f \( -name '.taosx-backup-layout' -o -name '*.z' -o -name '*.mz' \) -print
    
  4. 在 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' \
      -vv
    

    layout 参数只适用于任务级备份。当布局标记存在时,显式 layout 必须与之匹配,否则恢复失败。只读恢复不会创建布局标记。

  5. 检查 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 隐藏标记在内的完整任务目录,恢复后用日志行数与目标集群查询双重验证,不能只看退出码。
登录后查看全文
tdengine