TDengine 数据备份与恢复实战指南:taosdump 逻辑备份与 TSDB Enterprise 增量备份

原创2026-09-21 19:47:141,904 阅读
文章标签:数据库时序数据库后端物联网大数据云原生

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 集群进行备份和恢复。其核心概念如下:

  1. 增量数据备份:基于 TDengine 的数据订阅功能,将备份对象的所有数据变更(包括:新增、修改、删除、元数据变更等)记录下来,生成备份文件。
  2. 数据恢复:使用增量数据备份生成的备份文件,将备份对象恢复到指定的时间点。
  3. 备份对象:用户备份的对象,可以是一个数据库,也可以是一个超级表。
  4. 备份计划:用户为备份对象创建一个周期性执行的备份任务。备份计划从指定的时间点开始,以备份周期为间隔,周期性地执行备份任务。备份任务每次生成一个备份点。
  5. 备份点:每次执行备份任务,生成一组备份文件,它们对应一个时间点,称为备份点。第一个备份点称为初始备份点。
  6. 恢复任务:用户选择备份计划的某个备份点,创建一个恢复任务。恢复任务从初始备份点开始,逐个回放备份文件中的数据变更,直到指定的备份点结束。

数据备份和恢复概念图

以上图为例:

  1. 用户创建了一个备份计划,从 2024-08-27 00:00:00 开始,每隔 1 天执行一次备份任务。
  2. 在 2024-08-27 00:00:00 执行了第一次备份任务,生成了一个初始备份点。
  3. 之后,每隔 1 天执行一次备份任务,生成了多个备份点。
  4. 用户可以选择某个备份点,创建一个恢复任务。
  5. 恢复任务会从初始备份点开始,逐个应用备份点,恢复到指定的备份点。

创建备份计划

通过浏览器访问 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 配置。

创建成功后,备份计划会开始按照配置的参数运行。在"备份计划"下的列表中,可以查看已创建的备份计划。备份计划支持以下操作:

  1. 查看:显示备份计划的详细信息。
  2. 修改:修改备份计划的配置。修改备份计划的配置后,当前运行的备份任务会先停止,然后按照新的配置重新运行。
  3. 复制:以选中的备份计划为模版,创建新的备份计划。除了数据库和超级表需要用户选择以外,其他配置项和被复制的计划相同。
  4. 删除:删除备份计划。删除备份计划时,可以选择是否删除关联的备份文件。
  5. 指标:查看备份计划的统计指标。
  6. 查看备份点:查看和备份计划关联的所有备份点。

开启 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:

  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 日志中的实际处理文件数和数据行数,并在目标集群执行查询核对恢复结果。命令退出码为 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)。

登录后查看全文
tdengine