TDengine 集群维护实战指南数据重整、扫描、节点恢复与在线运维【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本文聚焦 TDengine TSDB Enterprise 在集群长期运行中提供的高阶维护手段涵盖数据重整compact、数据扫描scan、虚拟组 Leader 再平衡、数据节点恢复、本地修复模式、虚拟组分裂与在线热更新集群配置。读完本文你将掌握一套可落地的集群体检—重整—修复—扩容运维闭环让 TDengine 集群在工业物联网IIoT场景下长期运行得更健壮、更高效。维护能力全景为什么集群需要高阶维护TDengine 面向大量写入场景不同写入模式会在存储层留下痕迹数据存储放大、数据文件出现空洞、被删除的表与数据残留在文件中等。这些问题一方面降低存储效率磁盘空间被无效数据占用另一方面拖累查询性能需要扫描更多无效文件与空洞。为解决这些问题TDengine 企业版TSDB Enterprise提供了一整套集群维护手段核心能力包括数据重整Data Compact重新整理存储的数据文件删除文件空洞和无效数据提高数据组织度数据扫描Scan后台巡检 vnode 的所有时序数据文件发现问题时在服务端日志输出告警Leader 再平衡Balance让多副本集群的 vgroup leader 在各 replica 上均匀分布数据节点恢复Restore基于多副本复制能力恢复 dnode 上的 mnode / vnode / qnode本地修复模式Repair以taosd -r启动针对单个节点本地文件进行强制修复虚拟组分裂Split将负载过高的 vgroup 一分为二分摊读写压力在线配置热更新动态调整supportVnodes等关键参数。这些能力中的大部分以 SQL 命令形式通过taos客户端下发由 mnode 协调、vnode 执行任务均在后台异步运行可随时查看进度或终止。节点管理集群维护的第一层是节点管理。组成 TDengine 集群的物理实体是dnodedata node即运行在操作系统上的进程在 dnode 内可创建负责时序数据存储的vnodevirtual node。多副本集群中当某数据库replica为 3 时每个vgroup由 3 个 vnode 组成replica为 1 时由 1 个 vnode 组成。dnode 上还可创建mnodemanagement node最多三个、qnodequery node用于存算分离与bnode订阅节点。节点的创建、查看、删除、参数修改等完整操作请参考节点管理即docs/zh/05-tdengine-sql/08-cluster-management/01-node.md。其中与维护相关的高频操作包括-- 查看所有 dnode、mnode、qnode、bnode SHOW DNODES; SHOW MNODES; SHOW QNODES; SHOW BNODES; -- 查询集群可用状态0 不可用 / 1 完全可用 / 2 部分可用 SHOW CLUSTER ALIVE; -- 动态修改 dnode 配置v3.3.4.0 起修改会自动持久化 ALTER DNODE 1 debugFlag 143;结合本文主题最值得关注的是ALTER DNODE/ALTER ALL DNODES动态修改能力它与后文的在线更新集群配置一脉相承——部分参数无需重启即可生效详见 taosd 参考手册。数据重整compact 命令详解数据重整功能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;效果扫描并压缩指定 DB 中所有 vgroup 内 vnode 的所有数据文件或仅压缩 DB 中指定的 vgroup 列表内 vnode 的所有数据文件db_name为空时默认为当前数据库compact 会删除被删除的数据以及被删除的表的数据compact 会合并多个 STT 文件可用start with指定起始时间、end with指定终止时间可用META_ONLY只压缩元数据——元数据默认不压缩且元数据压缩会阻塞写入和查询被压缩数据库应停止写入和查询可用FORCE强制执行 compact即使自上次 compact 以来没有新数据写入compact 命令返回 compact 任务的 ID任务在后台异步执行可通过show compacts查看进度可通过kill compact终止任务。补充说明compact 为异步操作执行命令后不会等待任务结束即返回若上一个 compact 尚未完成时再次发起则会等上一个任务完成后再返回。compact 可能阻塞写入尤其在stt_trigger 1的数据库中但不阻塞查询。kill compact compact_id force会绕过 mnode 对 compact 任务的正常清理流程强制从 SDB 中删除 compact 记录允许在某个 dnode 离线时立即终止任务而无需等待其恢复。此操作存在风险compact 执行过程中正在修改的数据文件可能处于中间状态强制删除记录不会触发离线节点侧的清理可能导致数据文件损坏。建议仅在节点彻底损坏、无法恢复的极端情况下使用若节点尚能正常启动应优先将其拉起再使用不带force的kill compact终止任务。源码视角compact 的 mnode 协调实现从源码结构看compact 的元数据管理与任务调度位于 mndCompact.csource/dnode/mnode/impl/src/mndCompact.c。关键实现细节包括每个 compact 任务通过tGenIdPI32()生成全局唯一的compactId随响应返回给客户端与文档所述命令返回任务 ID一一对应show compacts的进度查询会逐 vgroup 汇总各 dnode 上 vnode 上报的numberFileset与finished状态见mndUpdateCompactProgress实现任务进度的后台跟踪kill compact走的是 mnode 事务transaction机制通过mndBuildKillCompactReq构造 kill 请求逐 vgroup 向 vnode 下发mndAddKillCompactAction而kill compact force对应的强制路径mndKillCompactForce在构造事务时会跳过离线 dnodednodeId not found, skip redo action/is offline, skip redo action等告警日志直接在 mnode 侧从 SDB 中删除 compact 记录——这正是文档中警告的绕过正常清理流程的底层行为因此务必只在节点彻底损坏时使用。数据扫描scan 命令详解数据扫描用于定期巡检数据文件的完整性是发现磁盘静默损坏bit rot等隐性故障的重要手段。语法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;效果扫描指定 DB 中所有 vgroup 内 vnode 的所有时序数据文件若数据文件存在问题则在相应的服务端日志中输出或扫描指定的 vgroup 列表中 vnode 的所有数据文件db_name为空时默认为当前数据库可用start with/end with限定扫描的时间范围scan 任务在后台异步执行可通过show scans查看任务列表show命令返回 scan 任务 ID可通过kill scan终止任务。补充说明scan 同样为异步操作执行命令后不会等任务结束即返回若上一个 scan 未完成时再次发起则会等上一个任务完成后再返回。源码视角scan 的执行链路数据扫描的底层实现分布在 vnode 侧与 mnode 侧vnode 侧入口为 vnodeScan.csource/dnode/vnode/src/vnd/vnodeScan.c其中的vnodeProcessScanVnodeReq、vnodeQueryScanProgress、vnodeProcessKillScanReq分别对应扫描执行、进度查询与终止请求在 vnodeSvr.csource/dnode/vnode/src/vnd/vnodeSvr.c中被注册分发扫描引擎对 TSDB 文件的深层校验位于 tsdbScan.csource/dnode/vnode/src/tsdb/tsdbScan.c它负责逐文件检查数据文件的一致性发现问题时通过服务端日志输出——这与文档中若数据文件存问题则在相应的服务端日志中输出的描述一致mnode 侧的任务记录与进度汇总位于 mndScan.csource/dnode/mnode/impl/src/mndScan.c通过mndUpdateScanProgress聚合各 vnode 上报的扫描进度。实践中建议将 scan 纳入例行巡检如每日或每周配合日志监控尽早发现数据文件异常。虚拟组 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; -- 再平衡一个 database 内所有 vgroup 的 leader功能该命令尝试让一个或所有 vgroup 的 leader 在各自的 replica 节点上均匀分布。实现方式是强制 vgroup 重新选举在选举过程中改变 leader最终让 leader 均匀分布。注意vgroup 选举本身带有随机性因此通过选举重新分布产生的均匀分布也带有一定概率不会完全均匀副作用是影响查询和写入vgroup 重新选举期间从开始选举到选出新 leader该 vgroup 无法写入和查询选举过程一般在秒级完成所有 vgroup 会依次逐个重新选举避免同时影响整个集群。测试佐证仓库测试用例 test_balance_leader.pytest/cases/02-Databases/05-Sync/test_balance_leader.py验证了balance vgroup leader命令的可用性同类用例还包括 test_balance_leader_replica2.py 与 test_balance1.py 等覆盖不同副本数场景可作为功能行为参考。恢复数据节点restore dnode当集群中某个 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 上指定 vgroup 的 vnode restore qnode on dnode dnode_id; -- 恢复 dnode 上的 qnode限制该功能基于已有的复制功能实现是复制恢复而非灾难恢复或备份恢复对于要恢复的 mnode 和 vnode前提是还存在该 mnode 或 vnode 的其它两个副本且均能正常工作该命令不能修复数据目录中个别文件的损坏或丢失。若某个 mnode 或 vnode 中个别文件损坏无法单独恢复损坏的文件或某块数据此时应将该 mnode/vnode 的数据全部清空再执行恢复。源码视角从源码结构看restore 相关逻辑集中在 mnode 的 dnode 与 vgroup 管理中mndDnode.csource/dnode/mnode/impl/src/mndDnode.c与 mndVgroup.csource/dnode/mnode/impl/src/mndVgroup.c中均包含 restore dnode / restore vgroup 的处理函数且 mnode 会基于 dnode 状态上报vnodeRestore状态位驱动副本数据补齐这也解释了为什么该功能强依赖副本数与 dnode 数量。本地修复模式taosd -r如果问题只涉及单个节点上的本地文件并且希望在启动过程中执行修复检查可以用taosd -r以修复模式启动。除本文档示例外完整的命令行语法、字段约束、默认策略与更多示例见 taosd 参考手册docs/zh/12-operations-and-tooling/03-components/01-taosd.md。修复单个目标taosd -r --mode force --node-type vnode \ --repair-target meta:vnode3在同一次启动中声明多个修复目标taosd -r --mode force --node-type vnode --backup-path /tmp/repair-bak \ --repair-target meta:vnode3 \ --repair-target tsdb:vnode5:fileid1809 \ --repair-target wal:vnode6一次修复同一 vnode 下全部 TSDB filesettaosd -r --mode force --node-type vnode \ --repair-target tsdb:vnode5:fileid*当前限制当前只支持--mode force当前只支持--node-type vnodetsdbrepair target 必须显式指定fileid可以是单个 fileset 的 ID也可以是*表示该 vnode 下全部 fileset同一个 vnode 内fileid*不能与显式fileidntarget 混用walrepair target 当前不支持strategyTSDB 默认策略drop_invalid_only只处理缺失文件这类损坏如果要处理 size mismatch请显式指定head_only_rebuild或full_rebuild。repair-target 语法与策略参考手册延伸每个--repair-target的取值格式为file-type:keyvalue[:keyvalue]...规则如下file-type必须放在第一个 segment当前支持meta、tsdb、wal三种类型keyvalue的顺序不影响语义同一条 target 内 key 不允许重复多条 target 命中同一修复对象会直接报错对tsdbfileid*表示命中该 vnode 下全部 fileset且不能与同一 vnode 下的显式fileidntarget 混用。各类型的必填/可选字段与策略如下文件类型必填字段可选字段默认策略支持的策略metavnodestrategyfrom_uidfrom_uid、from_redotsdbvnode、fileidstrategydrop_invalid_onlydrop_invalid_only、head_only_rebuild、full_rebuildwalvnode无无无TSDB repair 策略语义drop_invalid_only仅在 deep scan 前删除明显的缺失文件场景不会检查与current.json不一致的 size mismatch 损坏head_only_rebuild对有效 core block 做 deep scan只重建.head保留.data如果.sma元数据不可用则删除.smafull_rebuild对有效 core block 做 deep scan并沿用现有 writer 路径重建完整 core 数据。补充说明--backup-path是本次 repair 启动的全局参数不属于某个特定 target旧版修复参数--file-type、--vnode-id、--replica-node已从这套接口中移除。若损坏数据量巨大、常规修复性能不足还可使用拷贝模式--mode copy从健康源节点拷贝 vnode 文件拷贝模式要求--source-cfg必填并支持--vnode 3,5-8,10形式的 ID 列表。分裂虚拟组split vgroup当一个 vgroup 因子表数过多导致 CPU 或 Disk 资源使用量负载过高时增加 dnode 节点后可通过split vgroup命令把该 vgroup 分裂为两个虚拟组。分裂完成后新产生的两个 vgroup 共同承担原来一个 vgroup 提供的读写服务。该命令在 3.0.6.0 版本第一次发布建议尽可能使用最新版本。split vgroup vgroup_id注意单副本库虚拟组在分裂完成后历史时序数据总磁盘空间使用量可能翻倍。因此执行前应通过增加 dnode 节点确保集群有足够的 CPU 和磁盘资源避免资源不足该命令为 DB 级事务执行过程中当前 DB 的其它管理事务会被拒绝但集群中其它 DB 不受影响分裂任务执行过程中可持续提供读写服务期间可能存在可感知的短暂读写业务中断分裂过程中不支持流stream和订阅subscription分裂结束后历史 WAL 会清空分裂过程支持节点宕机重启容错但不支持节点磁盘故障容错。测试佐证仓库为 split 提供了覆盖不同副本数的测试test/cases/02-Databases/05-Sync/下的 test_split_vgroup_replica1.py、test_split_vgroup_replica2.py、test_split_vgroup_replica3.py 分别验证了 1/2/3 副本场景下分裂后的读写可用性与数据一致性可作为该功能的行为参考。在线更新集群配置supportVnodes 热更新从v3.1.1.0开始TDengine TSDB Enterprise 支持在线热更新supportVnodes这一重要的 dnode 配置参数。参数含义supportVnodes的原始配置方式是在taos.cfg配置文件中设置表示该 dnode 能够支持的最大的 vnode 数量。当创建数据库时需要分配新的 vnode当删除数据库时其 vnode 都会被销毁。该参数在配置文件中的示例可见 taos.cfgpackaging/cfg/taos.cfg。热更新行为若通过在线更新或配置文件方式设置的supportVnodes小于 dnode 当前已经实际存在的 vnode 数量已存在的 vnode 不会受影响但创建新的 database 时能否成功仍由实际生效的supportVnodes参数决定。源码视角从源码结构看dnode 上报状态时携带numOfSupportVnodes字段mnode 在收到状态上报后会检测supportVnodesChanged见 mndDnode.c据此刷新元数据中的 dnode 能力信息作为后续数据库创建时 vnode 分配的依据——这正是热更新后新建 database 受新值约束的底层机制。仓库测试 test_com_config.py 与 test_com_config_refresh.py 覆盖了配置刷新与持久化相关行为。维护操作最佳实践小结结合本文各项能力推荐的集群例行维护流程如下例行巡检定期执行scan DATABASE检查数据文件完整性结合服务端日志监控数据异常按需重整当发现存储放大明显、数据空洞较多或查询性能下降时执行compact DATABASE db_name写入密集场景注意stt_trigger 1时 compact 可能阻塞写入应安排在业务低峰期负载均衡节点升级或重启后执行balance vgroup leader使 leader 均匀分布注意选举期间对应 vgroup 有秒级读写中断故障处置节点数据全失时用restore dnode需 dnode ≥ 3 且副本数为 3单节点本地文件损坏时用taosd -r --mode force修复指定 vnode 的 meta / tsdb / wal极端场景才使用kill compact ... force并立即安排后续数据校验容量扩展vgroup 负载过高时先扩容 dnode再执行split vgroup分摊压力并留意单副本场景磁盘占用可能翻倍动态调优优先用ALTER DNODE/ALTER ALL DNODES在线调整supportVnodes等参数v3.1.1.0 起支持减少重启窗口。以上命令的完整语法与参数细节可随时查阅 taosd 参考手册 与 节点管理各功能的源码实现分别位于 mndCompact.c、mndScan.c、vnodeScan.c、mndDnode.c 等文件中测试用例集中在 test/cases/02-Databases/05-Sync/ 目录可供深入研读。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考