TDengine Enterprise 集群维护完全指南：数据重组、数据扫描与节点恢复实战

TDengine Enterprise 集群维护完全指南：数据重组、数据扫描与节点恢复实战

【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine

集群在长期运行过程中，会面临数据文件空洞、vgroup 负载不均、节点数据损坏、子表过多导致资源过载等一系列问题。本文基于 TDengine 官方维护手册（docs/en/12-operations-and-tooling/02-operations/04-maintenance.md），系统讲解 TDengine Enterprise 提供的集群高级维护能力：COMPACT数据重组、SCAN数据扫描、vgroup leader 再平衡、restore dnode节点恢复、taosd -r本地修复模式、split vgroup虚拟组拆分以及supportVnodes在线热更新。阅读本文后，你将掌握这些维护命令的完整语法、使用时机、限制条件与底层实现原理，能够针对不同故障场景选择正确的维护手段，保障集群长期稳定高效运行。

说明：本文所介绍的高级维护功能（数据重组、数据扫描、leader 再平衡、节点恢复、vgroup 拆分、在线配置更新）均属于 TDengine Enterprise（企业版）能力，需要对应版本授权方可使用。

节点管理

维护集群的第一步是掌握节点状态的查看与管理方法。dnode是运行taosd的数据节点，集群内部分布着管理节点（mnode）、查询节点（qnode）与虚拟节点（vnode）。节点管理涉及查看节点状态、添加/删除节点、修改节点配置等操作，完整命令请参阅 Node Management（节点管理）。

在后续的维护操作中，多数命令都以节点或 vgroup 为操作对象，因此先厘清节点与 vgroup 的对应关系至关重要。

数据重组（DATA COMPACT）

为什么要做数据重组

TDengine 面向多种写入场景设计，很多场景会造成存储层面的数据放大或数据文件空洞：

• 频繁的删除操作会在文件中留下已被删除的数据与空洞；
• 删除表（含超级表删除子表）后，旧文件仍残留无效数据；
• 大量小文件（STT 文件）堆积，增加了查询时需要合并的文件数量。

这些问题不仅降低存储效率，还会拖慢查询性能。为此，TDengine Enterprise 提供数据重组功能（DATA COMPACT），对存储中的数据文件进行重排，消除文件空洞与无效数据，改善数据组织方式，从而提升存储与查询效率。

数据重组功能最早在3.0.3.0版本发布，此后经历了多次迭代优化，官方建议尽量使用最新版本。

语法

COMPACT DATABASE db_name [start with 'XXXX'] [end with 'YYYY'] [META_ONLY] [FORCE]; COMPACT [db_name.]VGROUPS IN (vgroup_id1, vgroup_id2, ...) [start with 'XXXX'] [end with 'YYYY'] [META_ONLY] [FORCE]; SHOW COMPACTS; SHOW COMPACT compact_id; KILL COMPACT compact_id; KILL COMPACT compact_id FORCE;

从解析器源码（sql.y）可以看到，COMPACT DATABASE与COMPACT ... VGROUPS IN (...)两条语句分别生成createCompactStmt与createCompactVgroupsStmt语法树节点，SHOW COMPACTS/SHOW COMPACT id/KILL COMPACT id [FORCE]则对应createShowCompactsStmt、createShowCompactDetailsStmt与createKillCompactStmt（其中FORCE关键字对应一个布尔参数，见 sql.y）。

功能效果

• 扫描并压缩指定数据库所有 VGROUP 的 VNODE 上的全部数据文件；
• COMPACT会清除已删除的数据以及已删除表的数据；
• COMPACT会合并多个 STT 文件；
• 可通过start with关键字指定参与 COMPACT 的数据起始时间；
• 可通过end with关键字指定参与 COMPACT 的数据结束时间；
• 可通过META_ONLY关键字仅对元数据执行压缩（默认不压缩元数据）。注意：元数据压缩会阻塞写入，执行元数据压缩的数据库应停止写入与查询；
• 若某个文件组自上次压缩以来没有新数据写入，则不会被再次压缩，除非指定FORCE关键字；
• COMPACT命令会返回该压缩任务的 ID；
• 压缩任务在后台异步执行，可通过SHOW COMPACTS命令查看任务进度；
• SHOW命令会返回压缩任务 ID，可用KILL COMPACT命令终止压缩任务。

使用注意事项

• COMPACT是异步操作，执行命令后立即返回，不会等待压缩完成；若前一次压缩尚未结束，则新的COMPACT会等待前一个任务结束后才返回；
• COMPACT可能阻塞写入，尤其是在stt_trigger = 1的数据库中，但不会阻塞查询；
• 从管理实现看，压缩任务由 mnode 驱动调度，dnode 侧的 vnode 管理模块负责汇总各 vnode 的压缩进度（vnodeGetCompactProgress及各 vnode 的 progress 上报，见 vmHandle.c），可见压缩任务的生命周期由集群管理面统一跟踪。

关于 KILL COMPACT ... FORCE 的警告

KILL COMPACT compact_id FORCE会绕过 mnode 对压缩任务正常的清理流程，直接从 SDB（系统元数据库）中强制删除压缩记录，从而即使 dnode 离线也能立即终止任务，无需等待其恢复。但该操作存在风险：

• 压缩过程中正在修改的数据文件可能停留在中间状态；
• 因为强制删除记录不会在离线节点上触发清理，可能导致数据文件损坏；
• 仅当节点完全损坏且无法恢复时才应使用此命令；
• 只要节点还能启动，强烈建议先将其恢复上线，再用不带FORCE的KILL COMPACT正常终止任务。

扫描数据（SCAN）

语法

SCAN DATABASE db_name [start with 'XXXX'] [end with 'YYYY']; SCAN [db_name.]VGROUPS IN (vgroup_id1, vgroup_id2, ...) [start with 'XXXX'] [end with 'YYYY']; SHOW SCANS; SHOW SCAN <scan_id>; KILL SCAN <scan_id>;

对应语法树节点由createScanStmt、createScanVgroupsStmt、createShowScansStmt、createShowScanDetailsStmt与createKillStmt生成，见 sql.y 与 sql.y。

功能效果

• 扫描指定数据库所有 VGROUP 的 VNODE 上的全部时序数据文件，若数据文件存在问题，会输出到对应的服务器日志中；
• 扫描指定数据库中、给定 VGROUP 列表里的所有 VGROUP 的 VNODE 时序数据文件，db_name为空时默认使用当前数据库；数据文件如有问题同样会输出到对应服务器日志；
• 可通过start with/end with关键字限定扫描数据的起止时间；
• SCAN任务在后台异步执行，可通过SHOW SCANS查看任务列表；
• SHOW命令返回扫描任务 ID，可用KILL SCAN终止扫描任务。

使用注意事项

SCAN同样是异步操作：执行后立即返回，不等待扫描结束；若前一次扫描尚未完成，则新的SCAN会等待前一个任务结束后才返回。

扫描与压缩的配合

SCAN只负责“体检”，发现问题后数据文件层面的修复需要借助COMPACT（重组清理）或下文介绍的本地修复模式（taosd -r）来完成。建议的排查路径是：先SCAN定位问题，再根据损坏类型选择COMPACT或修复模式。

VGroup Leader 再平衡

背景与语法

在多副本集群中，当一个或多个节点因升级等原因重启时，各 dnode 上的负载可能出现不均衡；极端情况下，所有 vgroup 的 leader 可能集中在同一个 dnode 上。该功能最早在3.0.4.0版本发布，官方建议尽量使用最新版本。

balance vgroup leader; # 再平衡所有 vgroup leader balance vgroup leader on <vgroup_id>; # 再平衡某个 vgroup 的 leader balance vgroup leader database <database_name>; # 再平衡某个数据库内的所有 vgroup leader

从解析器语法（sql.y）可以看到，三种形式分别由createBalanceVgroupLeaderStmt与createBalanceVgroupLeaderDBNameStmt处理。

工作原理

该命令尝试将一个或全部 vgroup 的 leader 在其副本节点之间均匀分布：通过强制触发 vgroup 重新选举，在选举过程中改变 vgroup 的 leader，最终实现 leader 的均匀分布。在 mnode 的 vgroup 管理实现中，leader 再平衡通过事务方式为 vgroup 添加“平衡 leader”动作（mndAddBalanceVgroupLeaderAction，见 mndVgroup.c），动作下发后由 dnode 触发选举完成 leader 切换。

注意事项

• vgroup 选举本身具有随机性，因此再选举得到的均匀分布也是概率性的，并非严格均匀；
• 该命令的副作用是影响查询与写入：在 vgroup 重新选举期间，从选举开始到新 leader 产生，该 vgroup 无法写入和查询；
• 选举过程一般在数秒内完成；
• 所有 vgroup 会逐个依次重新选举，不会并行触发。

恢复数据节点（Restore Data Node）

适用场景与前提

当集群中某个 dnode 的数据完全丢失或损坏（例如磁盘损坏、目录被删除）时，可使用restore dnode命令恢复该数据节点上的部分或全部逻辑节点。该功能依赖集群中其他副本的数据复制，因此仅当集群 dnode 数量 ≥ 3 且副本数为 3 时才能生效。

语法

restore dnode <dnode_id>; # 恢复 dnode 上的 mnode、全部 vnode 和 qnode restore mnode on dnode <dnode_id>; # 恢复 dnode 上的 mnode restore vnode on dnode <dnode_id>; # 恢复 dnode 上的全部 vnode restore vnode on dnode <dnode_id> on vgroup <vgroup_id>; # 恢复 dnode 上某个 vnode restore qnode on dnode <dnode_id>; # 恢复 dnode 上的 qnode

语法树层面，上述语句分别生成createRestoreComponentNodeStmt（携带QUERY_NODE_RESTORE_DNODE/MNODE/QNODE/VNODE_STMT类型）以及带 vgroup id 的createRestoreComponentNodeStmtWithVgId，见 sql.y。在 vnode 管理侧，恢复操作会以“restore-vnodes”线程的方式并发重建多个 vnode（见 vmInt.c），并将 vgroup id 恢复到原有位置。

限制条件

• 该功能基于现有复制能力的恢复，并非容灾或备份恢复：对于要恢复的 mnode 和 vnode，前提是它们的另外两个副本仍能正常工作；
• 该命令无法修复数据目录中单个文件的损坏或丢失。例如 mnode 或 vnode 中某个文件或某块数据损坏时，无法单独恢复某个文件或数据块。这种情况下，可以选择将该 mnode/vnode 的数据彻底清空后再执行恢复。

本地修复模式（Local Repair Mode）

当问题仅局限于单个节点上的本地文件、且希望在启动时让 TDengine 自动执行修复检查时，可以以本地修复模式启动taosd。本地修复模式下，taosd会按照指定的修复目标（repair target）对损坏文件进行就地修复。完整的 CLI 语法、支持的 key、默认策略及更多示例，请参阅 taosd Reference（taosd 参考）。

基本用法

修复单个 vnode 的 meta 文件（使用默认策略）：

taosd -r --mode force --node-type vnode \ --repair-target meta:vnode=3

一次启动声明多个修复目标（同时修复 meta、tsdb、wal）：

taosd -r --mode force --node-type vnode --backup-path /tmp/repair-bak \ --repair-target meta:vnode=3 \ --repair-target tsdb:vnode=5:fileid=1809 \ --repair-target wal:vnode=6

用一个目标修复某个 vnode 内的全部 TSDB 文件集：

taosd -r --mode force --node-type vnode \ --repair-target 'tsdb:vnode=5:fileid=*'

修复目标语法

每个--repair-target的值遵循如下语法：

<file-type>:<key>=<value>[:<key>=<value>]...

规则要点：

• <file-type>必须是第一段，当前支持的文件类型为meta、tsdb、wal；
• 同一目标内 key 的顺序无关紧要，但重复同一 key 无效；
• 多个目标中重复声明同一修复对象无效；
• tsdb的fileid=*表示目标 vnode 的全部文件集，且不能与同一 vnode 内显式的fileid=<n>目标混用。

各文件类型支持的修复目标如下表：

策略说明

• tsdb的fileid在当前阶段为必填：fileid=<n>修复一个文件集，fileid=*修复一个 vnode 内的全部文件集；
• wal当前不支持strategy；
• --backup-path对整个修复启动过程是全局的，不针对单个目标；
• TSDB 修复策略行为：
  • drop_invalid_only：仅在做任何深度扫描前剔除明显损坏的“缺失文件”类问题，不会对照current.json检查大小不匹配（size-mismatch）类损坏；
  • head_only_rebuild：深度扫描有效核心块并仅重建.head文件，保持.data不变；若 SMA 元数据不可用则丢弃.sma；
  • full_rebuild：深度扫描有效核心块，并通过现有写入路径重建完整核心负载；
  • 当需要针对大小不匹配类损坏进行恢复时，应显式使用head_only_rebuild或full_rebuild。

当前限制

• 仅支持--mode force（另有--mode copy，用于损坏数据量过大时直接从健康源节点复制 vnode 文件，详见 taosd.md）；
• 仅支持--node-type vnode；
• tsdb修复目标必须包含fileid，可以是一个明确的文件集 ID，或*表示该 vnode 的全部文件集；
• 同一 vnode 内，fileid=*不能与显式fileid=<n>目标混用；
• wal修复目标当前不支持strategy；
• TSDB 默认策略drop_invalid_only只处理缺失文件类损坏；大小不匹配类恢复需要显式指定深度策略，如head_only_rebuild或full_rebuild。

拆分虚拟组（Splitting Virtual Groups）

适用场景与语法

当一个 vgroup 因为子表过多导致 CPU 或磁盘资源使用过载时，可以在添加 dnode 后，使用split vgroup命令将 vgroup 拆分为两个虚拟组。拆分后，新建的两个 vgroup 共同承担原来一个 vgroup 的读写服务。该命令最早在3.0.6.0版本发布，官方建议尽量使用最新版本。

split vgroup <vgroup_id>

拆分任务由 mnode 的 vgroup 管理模块以事务方式处理（mndProcessSplitVgroupMsg，见 mndVgroup.c），vnode 侧在事务提交时执行数据拆分（见 vmInt.c）。

注意事项

• 对于单副本 vgroup，拆分后历史时序数据的总磁盘占用可能翻倍。因此操作前务必确保集群已通过添加 dnode 具备充足的 CPU 和磁盘资源，避免资源短缺；
• 该命令属于数据库级事务：执行期间，当前数据库的其他管理事务将被拒绝；集群中其他数据库不受影响；
• 拆分任务期间读写服务可以继续，但读写操作可能出现可感知的短暂中断；
• 拆分过程中不支持流计算和订阅；拆分结束后，历史 WAL 会被清空；
• 拆分过程支持节点宕机重启级容错，但不支持节点磁盘故障级容错。

在线集群配置更新（supportVnodes）

背景

自3.1.1.0版本起，TDengine Enterprise 支持对 dnode 的重要配置参数supportVnodes进行在线热更新。该参数原本配置在taos.cfg文件中，表示 dnode 能够支持的最大 vnode 数量：创建数据库时会分配新的 vnode，删除数据库时其 vnode 会被销毁。

从参数注册源码看，supportVnodes在tglobal.c中以CFG_DYN_ENT_SERVER（服务器端可动态修改）方式注册，取值范围为 0–1024（见 tglobal.c），这正是其支持在线更新的底层机制。同时，mnode 在收到 dnode 状态上报时会检测supportVnodes是否发生变化（supportVnodesChanged，见 mndDnode.c），以便及时更新集群侧的容量视图。

注意事项

• supportVnodes的在线更新不会持久化：系统重启后，允许的最大 vnode 数量仍由taos.cfg中配置的supportVnodes决定；
• 如果通过在线更新或配置文件设置的supportVnodes小于dnode 当前实际 vnode 数量，已有 vnode 不受影响；
• 但新数据库能否成功创建，仍取决于实际生效的supportVnodes参数值。

维护命令速查

总结与推荐实践

TDengine Enterprise 的集群维护能力覆盖了从日常体检到故障恢复的完整链路：

1. 日常体检：定期执行SCAN扫描数据文件，发现异常后根据日志定位问题范围；
2. 性能治理：对删除频繁、STT 文件堆积的数据库执行COMPACT重组，消除文件空洞、合并小文件、清理无效数据；数据库建库参数中的ss_compact、compact_interval等选项（见 meta 系统表说明）可与手动 COMPACT 配合使用；
3. 负载均衡：节点重启或升级后，用balance vgroup leader重平衡 leader 分布；
4. 故障恢复：单节点本地文件损坏时用taosd -r修复模式；整节点数据丢失时（3 副本集群）用restore dnode从副本重建；
5. 容量扩展：vgroup 过载时先扩容 dnode，再执行split vgroup拆分虚拟组；vnode 配额紧张时在线调大supportVnodes（注意重启失效）。

需要强调的是：KILL COMPACT ... FORCE属于高风险操作，仅在节点彻底损坏、无法恢复的极端场景下使用；任何维护操作前都应确认集群版本满足功能引入版本要求，并在测试环境先行演练。

【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine