TDengine 数据备份与恢复实战指南:taosdump 逻辑备份与 TSDB Enterprise 增量备份
TDengine 数据备份与恢复实战指南:taosdump 逻辑备份与 TSDB Enterprise 增量备份
TDengine 提供了从开源逻辑备份工具 taosdump 到企业版增量备份/恢复的完整数据保护体系,覆盖"按库全量备份""按时间范围备份""按备份点增量恢复""异地恢复"等多种容灾场景。本文以 数据备份和恢复 为骨架,结合仓库中的 taosdump 源码与数据库 DDL 文档,完整讲解 taosdump 的备份/恢复命令与参数、TSDB Enterprise 基于数据订阅的备份计划/备份点/恢复任务机制、S3 转储配置以及 taosx 命令行异地恢复流程,并给出常见错误的排查方法。读完本文,你将能够独立规划并执行 TDengine 集群的逻辑备份、增量备份、按时间点恢复与跨集群数据迁移。
备份恢复体系总览
为了防止数据丢失、误删操作,TDengine 提供全面的数据备份、恢复、容错、异地数据实时同步等功能,以保证数据存储的安全。当前仓库中可用的备份恢复能力分为两条路径:
| 方案 | 适用对象 | 备份粒度 | 增量能力 | 入口 |
|---|---|---|---|---|
| taosdump | 开源社区版 | 数据库、超级表、子表、普通表、时间范围、仅 Schema | 支持断点续传,但不产生增量备份点 | 命令行工具,见 taosdump 参考手册 |
| TDengine TSDB Enterprise | 企业版 | 数据库、超级表 | 基于数据订阅的增量备份,按备份点回放恢复 | taosExplorer(端口 6060)与 taosx 命令行 |
其中,企业版增量备份基于 数据订阅(文档原文,转译为仓库根路径为 数据订阅)能力实现,备份的数据变更包括新增、修改、删除与元数据变更。下面分别展开。
基于 taosdump 进行数据备份恢复
taosdump 是什么
taosdump 是一个开源工具,用于支持从运行中的 TDengine 集群备份数据并将备份的数据恢复到相同或另一个正在运行的 TDengine 集群中。taosdump 可以将数据库作为逻辑数据单元进行备份,也可以对数据库中指定时间段内的数据记录进行备份。
taosdump 在 TDengine 服务器或客户端安装包中均提供,支持 Windows/MacOS/Linux 平台,在命令行终端中运行,运行时必须带参数,指明备份操作(-o)或恢复操作(-i)。运行 taosdump 之前要确保目标 TDengine 集群已经正确运行。
从仓库源码结构看,taosdump 的实现按功能模块拆分,位于 tools/taosdump/src:main.c 为命令行入口,backup/ 目录下的 backup.c、backupData.c、backupMeta.c 分别负责备份调度、时序数据导出与元数据导出,restore/ 目录负责恢复流程,storage/ 目录提供存储后端(Parquet、Taos 存储等),bck*.h 系列头文件定义了参数解析、进度、日志、校验、Schema 变更等基础设施。
数据备份命令
以下为 taosdump 执行数据备份的使用示例:
taosdump -h localhost -P 6030 -D dbname -o /file/path
执行上述命令后,taosdump 会连接 localhost:6030 所在的 TDengine 集群,查询数据库 dbname 中的所有数据,并将数据备份到 /file/path 下。
如果不指定 -D 参数,默认备份所有用户数据库(information_schema 和 performance_schema 系统库除外)。常用参数说明如下(完整参数表见 taosdump 参考手册):
| 参数 | 说明 | 默认值 |
|---|---|---|
-h, --host |
TDengine 服务端 FQDN 或 IP | localhost |
-P, --port |
服务端端口号 | 6030 |
-u, --user |
连接用户名 | root |
-p, --password |
交互式输入密码,也可 -pPASSWORD 紧贴指定 |
taosdata |
-o, --outpath |
备份输出目录 | ./output |
-i, --inpath |
恢复时指定备份文件所在输入路径 | 无 |
-D, --databases |
指定要备份/恢复的数据库,多个以逗号分隔 | 所有用户数据库 |
-s, --schemaonly |
仅备份表结构和标签,不备份时序数据 | 关闭 |
-S / -E, --start-time / --end-time |
备份数据的起止时间,支持毫秒时间戳或 ISO8601 格式 | 全部时间 |
-T, --thread-num |
数据备份/恢复并行线程数 | 8 |
-C, --checkpoint |
断点续传开关 | 关闭 |
-k / -z, --retry-count / --retry-sleep-ms |
连接或查询失败重试次数及间隔 | 3 / 1000 |
典型场景示例:
# 备份所有用户数据库
taosdump -h my-server -o /root/backup/
# 备份指定多个数据库
taosdump -h my-server -D db1,db2 -o /root/backup/
# 按时间范围备份 2024 年全年数据
taosdump -h my-server -D test -S "2024-01-01T00:00:00.000+0800" -E "2024-12-31T23:59:59.999+0800" -o /root/backup/
# 仅备份表结构与标签(快速迁移表结构)
taosdump -h my-server -D test -s -o /root/backup/
# 断点续传:中断后再次运行,跳过已完成的库/超级表/子表
taosdump -h my-server -D test -o /root/backup/ -C
备份目录复用保护
在使用 taosdump 时,如果指定的存储路径已经包含数据文件,taosdump 会提示用户并立即退出,以避免数据被覆盖。这意味着同一存储路径只能用于一次备份。如果你看到相关提示,请谨慎操作,以免误操作导致数据丢失。
需要说明的是:-o 参数指定的目录下如果已存在备份文件,taosdump 在未开启断点续传模式时会直接覆盖同名文件,建议使用空目录进行全量备份;若备份数据量很大,建议配合 -S/-E 参数分段备份,或使用 -C 断点续传。
数据恢复命令
要将本地指定文件路径中的数据文件恢复到正在运行的 TDengine 集群中,可以通过指定命令行参数和数据文件所在路径来执行 taosdump 命令。以下为 taosdump 执行数据恢复的示例代码:
taosdump -i /file/path -h localhost -P 6030
执行上述命令后,taosdump 会连接 localhost:6030 所在的 TDengine 集群,并将 /file/path 下的数据文件恢复到 TDengine 集群中。恢复时会自动创建对应的数据库、超级表及子表(若已存在则跳过建表)。
常用恢复场景:
# 仅恢复指定数据库
taosdump -h my-server -D test -i /root/backup/
# 恢复时重命名数据库(适合测试验证或平行运行)
taosdump -h my-server -i /root/backup/ -W "db1->db1_restored|db2->db2_restored"
# 断点续传恢复
taosdump -h my-server -i /root/backup/ -C
# 恢复时遇到 "WAL size exceeds limit" 错误,减小批量写入行数
taosdump -h my-server -i /root/backup/ -B 2000
备份内容选择与备份文件结构
从 v3.4.2.5 开始,taosdump 通过 -M, --content 参数支持指定备份/恢复内容:
| 取值 | 包含内容 |
|---|---|
basic(默认) |
超级表、子表、普通表及标签和时序数据 |
ext-meta |
虚拟表、流、订阅(Topic) |
all |
basic + ext-meta |
恢复分为两个阶段执行:第一阶段完成所有数据库的实体表创建及时序数据导入(basic);第二阶段在所有数据库就绪后统一执行所有库的虚拟表、流、订阅 DDL(ext-meta)。这样即使虚拟表跨库引用(如 db2 的虚拟表引用 db1 的实体表),无论数据库以何种顺序列出,跨库引用都能正确解析。分阶段恢复的价值还在于:扩展元数据中个别对象导入失败时,不会影响已经导入完成的基础数据,修正问题后只需单独重跑 --content=ext-meta。
备份输出目录下,每个数据库对应一个子目录,典型结构如下(binary 格式扩展名为 .dat,Parquet 格式为 .par):
{outpath}/
└── {dbname}/
├── db.sql # 建库 SQL
├── stb.sql # 所有超级表 DDL(每行一个,含虚拟超级表)
├── ntb.sql # 所有普通表 DDL
├── {stbname}.csv # 超级表列/标签 Schema(DESCRIBE 输出)
├── tags/{stbname}_data{N}.{ext} # 子表标签数据
├── {stbname}_data{dirIndex}/ # 子表时序数据文件
├── _ntb_data{dirIndex}/ # 普通表时序数据文件
├── vtb.sql / vtags/ # 虚拟表 DDL 与标签(ext-meta)
├── stream.sql / topic.sql # 流与订阅 DDL(ext-meta)
└── backup_complete.flag # 备份完成标记
基于 TDengine TSDB Enterprise 进行数据备份恢复
核心概念
基于 TDengine 的数据订阅功能,TDengine TSDB Enterprise 实现了数据的增量备份和恢复。用户可以通过 taosExplorer 对 TDengine 集群进行备份和恢复。其核心概念如下:
- 增量数据备份:基于 TDengine 的数据订阅功能,将备份对象的所有数据变更(包括:新增、修改、删除、元数据变更等)记录下来,生成备份文件。
- 数据恢复:使用增量数据备份生成的备份文件,将备份对象恢复到指定的时间点。
- 备份对象:用户备份的对象,可以是一个数据库,也可以是一个超级表。
- 备份计划:用户为备份对象创建一个周期性执行的备份任务。备份计划从指定的时间点开始,以备份周期为间隔,周期性地执行备份任务。备份任务每次生成一个备份点。
- 备份点:每次执行备份任务,生成一组备份文件,它们对应一个时间点,称为备份点。第一个备份点称为初始备份点。
- 恢复任务:用户选择备份计划的某个备份点,创建一个恢复任务。恢复任务从初始备份点开始,逐个回放备份文件中的数据变更,直到指定的备份点结束。
数据备份和恢复概念图
以上图为例:
- 用户创建了一个备份计划,从 2024-08-27 00:00:00 开始,每隔 1 天执行一次备份任务。
- 在 2024-08-27 00:00:00 执行了第一次备份任务,生成了一个初始备份点。
- 之后,每隔 1 天执行一次备份任务,生成了多个备份点。
- 用户可以选择某个备份点,创建一个恢复任务。
- 恢复任务会从初始备份点开始,逐个应用备份点,恢复到指定的备份点。
创建备份计划
通过浏览器访问 taosExplorer 服务,访问地址通常为 TDengine 集群所在 IP 地址的端口 6060,如 http://localhost:6060。在 taosExplorer 服务页面中,进入"系统管理 - 备份"页面,在"备份计划"标签页下,点击"创建备份计划",填写备份计划的相关信息。
需要填写的信息包括:
| 配置项 | 说明 |
|---|---|
| 数据库 | 需要备份的数据库名称。一个备份计划只能备份一个数据库/超级表 |
| 超级表 | 需要备份的超级表名称。如果不填写,则备份整个数据库 |
| 下次执行时间 | 首次执行备份任务的日期时间 |
| 备份周期 | 备份点之间的时间间隔。注意:备份周期必须小于数据库的 WAL_RETENTION_PERIOD 参数值 |
| 错误重试次数 | 对于可通过重试解决的错误,系统会按照此次数进行重试 |
| 错误重试间隔 | 每次重试之间的时间间隔 |
| 目录 | 存储备份文件的目录 |
| 备份文件大小 | 备份文件的大小限制。当备份文件大小达到此限制时,会自动创建新的备份文件 |
| 文件压缩等级 | 备份文件的压缩等级。支持:最快速度、最佳压缩比、兼具速度和压缩比 |
其中"备份周期必须小于数据库的 WAL_RETENTION_PERIOD 参数值"这一约束直接来源于增量备份的订阅机制:增量备份依赖数据订阅读取 WAL 中的变更记录,若备份周期超过 WAL 保留时长,期间产生的变更可能已被清理,导致备份点不完整。关于 WAL_RETENTION_PERIOD:它是为了数据订阅消费而设置、WAL 日志文件额外保留的最大时长,单位为秒,默认为 3600,即保留最近 3600 秒的数据,WAL 日志清理不受订阅客户端消费状态影响(详见 数据库 DDL 文档)。因此创建备份计划前,应先确认源数据库的 WAL_RETENTION_PERIOD 配置。
创建成功后,备份计划会开始按照配置的参数运行。在"备份计划"下的列表中,可以查看已创建的备份计划。备份计划支持以下操作:
- 查看:显示备份计划的详细信息。
- 修改:修改备份计划的配置。修改备份计划的配置后,当前运行的备份任务会先停止,然后按照新的配置重新运行。
- 复制:以选中的备份计划为模版,创建新的备份计划。除了数据库和超级表需要用户选择以外,其他配置项和被复制的计划相同。
- 删除:删除备份计划。删除备份计划时,可以选择是否删除关联的备份文件。
- 指标:查看备份计划的统计指标。
- 查看备份点:查看和备份计划关联的所有备份点。
开启 S3 转储
用户可以通过开启 S3 转储,将备份文件上传至 S3 存储服务上。开启 S3 转储,需要填写以下信息:
| 配置项 | 说明 |
|---|---|
| S3 节点 | S3 节点的地址 |
| 访问密钥 ID | 访问密钥 ID |
| 访问密钥 | 访问密钥 |
| 存储桶 | 存储桶名称 |
| 区域 | 存储桶所在的区域 |
| 对象前缀 | 备份文件的对象前缀,类似于 S3 上的目录 |
| 本地备份文件的保留时长 | 本地备份的保留时间,所有早于 当前时间 - backup_retention_period 的文件都需要上传到 S3 |
| 本地备份文件的保留个数 | 本地备份文件的保留个数,本地只保留最新的 backup_retention_size 个备份文件 |
S3 转储适合将备份文件异地归档,配合本地保留时长/保留个数策略,可以实现"本地短留存 + S3 长期归档"的分层备份。
备份文件与数据恢复
在"备份文件"列表中,可以查看备份文件的详细信息。在"备份文件"列表中,选择一个备份点,可以创建一个恢复任务,数据库恢复到指定的时间。在"恢复任务"列表中,可以查看已创建的恢复任务。恢复任务可以终止。
使用 taosx 命令行进行异地恢复
除通过 taosExplorer 创建恢复任务外,也可以将备份文件复制到另一套集群,在目标集群上使用 taosx 命令行恢复。这是实现跨集群灾备(集群 A 备份、集群 B 恢复)的推荐方式。
备份目录布局
新建的任务级备份直接保存在任务 ID 目录中:
<备份根目录>/
└── <task_id>/
├── .taosx-backup-layout
├── <topic>-<timestamp>-<vgroup>-<index>.z
├── <topic>-<timestamp>-<vgroup>-<index>.mz
└── ...
关于目录布局有几点需要特别注意:
- 新版
taosx写入任务级备份时,会在任务 ID 目录中创建隐藏的布局标记文件.taosx-backup-layout。该文件声明备份文件位于任务目录本身(task_dir),还是位于历史兼容子目录-1(legacy_job_dir)。标记文件存在时,taosx以其中记录的布局为准,不再探测另一目录。请保留该文件,不要手工修改或重新创建。 - 布局标记不是 HA 锁。升级期间,不要让不识别该标记的旧版和新版
taosx同时写入同一备份任务。切换版本前应停止备份任务,并确认旧进程已经退出。布局为task_dir的标记一旦产生,即使新版进程已经退出,也不要再用不识别该标记的旧版继续写入同一任务和备份根目录,否则新旧文件会分散到两个目录。回退到旧版时,请使用新的任务 ID 或新的备份根目录,不要向原备份链追加文件。 - 只有真正拆分出的作业才使用
<task_id>/<job_id>子目录。任务级备份不需要作业目录,也不需要在恢复命令中指定作业 ID。恢复程序会自动兼容旧版本生成的任务级目录。 - 如果需要恢复真实作业的备份,请复制实际包含
.z、.mz文件的作业目录,并将local:直接指向复制后的目录。
异地恢复操作步骤
以下步骤以任务级备份为例,演示如何将集群 A 的备份恢复到集群 B:
-
在集群 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日志中的实际处理文件数和数据行数,并在目标集群执行查询核对恢复结果。命令退出码为 0 不能单独证明数据已经恢复。
如果布局标记和显式 layout 都不存在,taosx 会执行历史兼容探测,并记录 backup layout marker is missing; using legacy layout detection warning。仅在这种情况下,如果任务目录直属位置和历史 -1 子目录中同时存在备份文件,恢复程序才会报告目录布局冲突。请先核对两处文件并将完整备份链整理到独立的恢复目录;同名文件内容不一致时不要直接覆盖。
常见错误排查
端口访问异常
如果任务启动失败并报以下错误:
Error: tmq to td task exec error
Caused by:
[0x000B] Unable to establish connection
产生原因是与数据源的端口链接异常,需检查数据源 FQDN 是否联通及端口 6030 是否可正常访问。
连接异常
如果使用 WebSocket 连接,任务启动失败并报以下错误:
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 连接时可能遇到多种错误类型,错误信息可以在"Caused by"后查看,以下是几种可能的错误:
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 端口或 LSB/Nginx/Proxy 配置错误。WebSocket protocol error: Handshake not finished:WebSocket 连接错误,通常是因为配置的端口不正确。
任务启动失败:WAL retention period is zero
如果任务启动失败并报以下错误:
Error: tmq to td task exec error
Caused by:
[0x038C] WAL retention period is zero
是由于源端数据库 WAL 配置错误,无法订阅。解决方式:修改数据 WAL 配置,例如:
alter
database test wal_retention_period 3600;
WAL_RETENTION_PERIOD 单位为秒,默认值即为 3600。该参数为数据订阅消费保留 WAL 日志的时长,是增量备份周期配置的上限依据,务必确保它大于备份计划的备份周期。
总结
TDengine 的数据保护体系覆盖了两种互补的路径:taosdump 适合开源场景下的全量逻辑备份、时间范围备份、Schema-only 备份与断点续传,且支持 Parquet 导出与大数据生态对接;TDengine TSDB Enterprise 的增量备份则基于数据订阅,通过备份计划周期性地生成备份点,支持按时间点回放恢复、S3 异地归档以及使用 taosx 命令行跨集群异地恢复。规划容灾方案时,应重点关注 WAL_RETENTION_PERIOD 与备份周期的匹配关系、备份目录布局标记 .taosx-backup-layout 的保留,以及恢复完成后通过日志与目标库查询的双重校验。
如需进一步深入,可继续阅读仓库中的 taosdump 参考手册、数据订阅文档 以及 taosdump 源码(tools/taosdump/src/backup/backup.c、tools/taosdump/src/restore)。