核心问题Sync leader is unreachable/Some vnode/qnode/mnode(s) are out of service/ 掉一个节点到底会怎样 / 副本与仲裁怎么配适用版本TDengine TSDB 3.x副本/仲裁/选举机制以 3.3 为准面向读者集群规划与运维人员被掉一个节点整个集群不可用困扰的实施工程师文档定位所有行为判定均给出源码位置文件:行号可自行核对1. 先纠正三个最普遍的误解误解一“三副本 可以挂两台”事实三副本只能挂一台。TDengine 的副本同步走 Raft提交需要多数派// source/libs/sync/src/syncUtil.c:115int32_tsyncUtilQuorum(int32_treplicaNum){returnreplicaNum/21;}副本数多数派quorum能容忍几个节点同时故障110 个2仲裁20 个仲裁只能帮它选出 leader不能帮它凑够数据321 个三副本挂掉两台后只剩 1 个副本凑不够 2 个确认无法选主、无法写入客户端会收到Sync leader is unreachable [0x8000090C]误解二“副本数可以随便设 2”事实社区版只允许 1 或 3企业版允许 2但必须同时启用仲裁节点。// source/dnode/mnode/impl/src/mndDb.c:543-548建库校验节选if((pCfg-replications2)^(pCfg-withArbitratorTSDB_MAX_DB_WITH_ARBITRATOR)){returnTSDB_CODE_MND_INVALID_DB_OPTION;// 2 副本与仲裁必须同时出现}...// 社区版只允许 1 或 3而且2 副本和 3 副本之间不能互转mndDb.c:618-641返回TSDB_CODE_OPS_NOT_SUPPORT。误解三“No enough dnodes是节点不够用”事实它的含义是在线 dnode 数少于副本数。// source/dnode/mnode/impl/src/mndVgroup.c:1054-1058int32_tsizetaosArrayGetSize(pArray);if(sizepVgroup-replica){mError(db:%s, vgId:%d, not enough online dnodes:%d to alloc %d replica,...);TAOS_RETURN(TSDB_CODE_MND_NO_ENOUGH_DNODES);// Out of dnodes (0x80000334)}集群里从没建过足够节点或者部分节点当前是离线的都会报这个错。2. 先记住这五个数字项值源码 / 文档依据多数派公式replica / 2 1syncUtil.c:115库副本数取值1 / 3企业版可 2须配仲裁mndDb.c:543-548、tdef.h:595-597mnode 数量上限最多 3 个最少 1 个mndMnode.c:744-747、mndMnode.c:909节点判离线超时statusTimeoutMs默认5000 mstglobal.c:68-71心跳/选举间隔mnode 心跳 1000 ms、选举 4000 msvnode 同为 1000/4000 mstglobal.c:220-223仲裁相关参数企业版双副本参数默认值含义arbHeartBeatIntervalSec2 s仲裁心跳arbCheckSyncIntervalSec3 s同步状态检查arbSetAssignedTimeoutSec14 s指派 leader 的超时来源tglobal.c:249-254、tglobal.c:1200-1205。3. 三分钟自查TL;DR-- ① 集群整体可用性0 不可用 / 1 完全可用 / 2 部分可用showcluster alive;-- ② 各节点在线状态与 vnode 占用selectid,endpoint,vnodes,support_vnodes,statusfrominformation_schema.ins_dnodes;-- ③ mnode 的 role找 leaderselectid,endpoint,role,statusfrominformation_schema.ins_mnodes;-- ④ 每个 vgroup 各副本的状态leader / follower / offlineselectvgroup_id,db_name,v1_dnode,v1_status,v2_dnode,v2_status,v3_dnode,v3_status,is_readyfrominformation_schema.ins_vgroupswheredb_name你的库;-- ⑤ 双副本场景仲裁是否同步完成showarbgroups;判读要点观察结论④ 里某 vgroup 只剩 1 个leader、另两个offline三副本已失去多数派写入会失败② 里有节点statusofflinenote有原因先修节点再谈其他③ 里没有任何leadermnode 失去多数派全局不可用⑤ 中is_sync为false仲裁尚未完成同步双副本此时不能切主① 返回2部分可用有 vgroup 处于降级状态需逐个查4. 症状对号入座表#报错 / 现象错误码真实含义章节H1Sync leader is unreachable0x8000090C凑不够多数派选不出也有不到 leader§6H2Some vnode/qnode/mnode(s) are out of service0x80000020部分节点不可达常见于 hosts 未配全§5H3Out of dnodes0x80000334在线 dnode 数 副本数§7H4VGroup is offline0x800003AE该 vgroup 当前不可读写如单副本所在节点离线§6H5Invalid option, wal_level 0 should be used with replica 10x8000039CwalLevel0与多副本冲突§8H6Offline dnode exists0x800003B6有节点离线时不允许做副本再平衡§7H7Vnodes exhausted0x800003BA该节点supportVnodes用满见第 02 篇H8Cannot drop mnode which is leader0x80000333不能删 leader mnode§8H9Mnode has not caught up with the leader0x80000412新 mnode 还没追上 leader§8H10The replica of mnode cannot exceed 30x800003A9mnode 超过 3 个§8H11Sync timeout0x80000903副本同步超时§6H12Sync write stall0x80000917副本落后太多写被减速§6H13Vgroup peer is not synced0x80000537对端副本未同步§8H14关掉一个节点后整个服务不可用—多为 mnode 单副本 该节点离线§6.3H15升级后某些 vgroup 的 leader 分布不均—需要手动触发 leader 再平衡§95. 决策树先分清是少数派还是连不上0 不可用2 部分可用每个 vgroup 都还有 leader某些 vgroup 已无 leader1 完全可用集群报错show cluster alive 返回几§6.3 mnode 层问题查 ins_mnodes 有没有 leaderins_vgroups 里leader 还剩几个§7 可写但降级优先修离线节点§6 失去多数派凑不回多数派就只能等节点回来§5 报错是客户端侧多查 hosts / EP 解析6. 副本、多数派与选举6.1 写入为什么必须到 leader写请求只认 leader非 leader 会重定向并返回明确的错误码// source/dnode/vnode/src/tsdb/… → source/dnode/vnode/src/vnd/vnodeSync.c:55-67重定向// 非 leader 时构造重试 epset并回 TSDB_CODE_SYN_NOT_LEADER// source/dnode/vnode/src/vnd/vnodeSvr.c:4640-4645// vnodeCheckState状态不是 leader → TSDB_CODE_SYN_NOT_LEADER所以0x8000090C有两层含义客户端连到了 follower正常现象客户端会自动重试到 leader整个 vgroup 没有 leader异常通常是凑不够多数派。区分方法看ins_vgroups里该 vgroup 的v1_status/v2_status/v3_status。若三个都不是leader属于第 2 种。6.2 选举与状态机副本状态取值include/libs/sync/sync.h:78-86值状态展示字符串0OFFLINEoffline100FOLLOWERfollower101CANDIDATEcandidate102LEADERleader103ERRORerror104LEARNERlearner105ASSIGNED_LEADERassigned leader选举规则得票数 ≥quorum才能当选syncVoteMgr.c:64单副本时自投即 leader启动直接syncNodeBecomeLeadersyncElection.c:117-126、syncMain.c:1616-1621learner学习者没有投票权TSDB_CODE_SYN_LEARNER_NO_VOTE。6.3 为什么关一台机器整个集群就不可用这一类投诉在代码上有三个常见对应根因代码依据表现mnode 是单副本且正好落在被关的节点上mndIsLeader找不到 leadermndSync.c:740-760全局不可用客户端报0x80000020vgroup 是单副本其所在节点离线TSDB_CODE_MND_VGROUP_OFFLINEmndDb.c:2340该库不可读写三副本但同时关了两台凑不够 quorum0x8000090C规划建议从代码推出来的mnode 至少 3 个、库副本数为 3才能真正容忍任意一台机器下线。只加库副本、不给 mnode 加副本集群仍会全局不可用。6.4 节点是怎么被判离线的// source/dnode/mnode/impl/src/mndDnode.c:422-431// mndIsDnodeOnline|lastAccessTime - curMs| tsStatusTimeoutMs 才算在线// 超时 → offlineReason DND_REASON_STATUS_MSG_TIMEOUTstatusInterval默认 1 sstatusTimeoutMs默认 5000 ms节点必须连续 5 秒没上报才被判离线。未上报 vnode 时还有一个宽限窗口max(3 × statusIntervalMs, statusTimeoutMs)mndDnode.c:1212-1265默认也是 5 秒。判定离线的瞬间mnode 会把该节点上所有vnode 的syncState置为OFFLINEmndMain.c:354-399这就是你在show vgroups里看到offline的来源。网络抖动导致statusTimeoutMs内没收到心跳也会被误判离线。跨机房部署时可适当调大statusTimeoutMs。7. vgroup 是怎么分布到节点上的7.1 打分选节点// source/dnode/mnode/impl/src/mndVgroup.c:1019-1045// 打分公式越小的节点越优先// score (numOfVnodes numOfOtherNodes * 0.9 add) / numOfSupportVnodes排序后取前replica个 dnodemndVgroup.c:1054-1073。遇到问题依次返回检查不通过的错误码在线 dnode 数 replica0x80000334Out of dnodesnumOfVnodes numOfSupportVnodes0x800003BAVnodes exhausted内存额度不足0x800003B1No enough memory in dnode7.2 副本分布的顺序mndSortVnodeGid按dnodeId升序排列mndVgroup.c:1033-1041这决定了show vgroups里v1_dnode/v2_dnode/v3_dnode的顺序——排查时不要假设v1就是 leader。7.3 再平衡rebalance有节点离线时禁止再平衡// source/dnode/mnode/impl/src/mndVgroup.c:2732-2744// 存在离线 dnode → TSDB_CODE_MND_HAS_OFFLINE_DNODE (0x800003B6)带仲裁节点的库不参与自动 balancemndVgroup.c:3936日志with arbitrator, balance vgroup not allowed。8. 副本与仲裁的配置边界操作结果依据社区版配replica 2拒绝mndDb.c:548企业版配replica 2但不带仲裁拒绝MND_INVALID_DB_OPTIONmndDb.c:543-5452 副本 ↔ 3 副本互转拒绝OPS_NOT_SUPPORTmndDb.c:618-641walLevel0 多副本拒绝0x8000039CmndDb.c:618-641副本数 在线 dnode 数拒绝0x80000334mndDb.c:556建第 4 个 mnode拒绝0x800003A9mndMnode.c:744-747同一个 dnode 上建 2 个 mnode拒绝test/cases/70-Cluster/test_5dnode1mnode.py:96删 leader mnode拒绝0x80000333文档05-tdengine-sql/08-cluster-management/01-node.md双副本 仲裁的关键机制每个 vgroup 生成一个arbTokensyncMain.c:1305仲裁端超时判定lastHbMs nowMs - tsArbSetAssignedTimeoutMsmndArbGroup.c:552vnode 侧校验 token不匹配 →TSDB_CODE_MND_ARB_TOKEN_MISMATCHvnodeSvr.c:4640-4705仲裁通过后副本进入ASSIGNED_LEADER105状态。双副本是企业版能力3.3.0.0 起并且需要额外部署arbitrator进程、配套arbHeartBeatIntervalSec等参数。9. 运维动作掉节点前 / 后该做什么9.1 计划内停机滚动升级、换硬件-- 先看哪些 vgroup 的 leader 在目标节点上selectvgroup_id,db_name,v1_dnode,v1_status,v2_dnode,v2_status,v3_dnode,v3_statusfrominformation_schema.ins_vgroups;-- 逐个把 leader 迁走避免停机后被选主balance vgroup leader;-- 全部balance vgroup leaderdatabasedb_name;-- 指定库balance vgroup leaderonvgroup_id;-- 指定 vgroupbalance的完整语法见docs/zh/12-operations-and-tooling/02-operations/04-maintenance.md:72-79。9.2 节点已经离线-- 看离线原因note 列会写明例如 status 消息超时、版本不匹配selectid,endpoint,status,notefrominformation_schema.ins_dnodes;-- 看哪些 vgroup 受影响status 为 offline 的那一列selectvgroup_id,db_name,v1_dnode,v1_status,v2_dnode,v2_status,v3_dnode,v3_statusfrominformation_schema.ins_vgroups;恢复优先级先让节点回来多数派会自动恢复再考虑数据修复。9.3 删除节点-- 在线节点可以直接删dropdnodeid;-- 单副本且已离线必须加 UNSAFE数据不可再恢复慎用dropdnodeidunsafe;来源docs/zh/05-tdengine-sql/08-cluster-management/01-node.md:31-37。9.4 数据一致性自查scan;-- 全量一致性扫描异步scanstartwithtsendwithts;showscans;-- 查看进度killscanid;-- 取消来源docs/zh/12-operations-and-tooling/02-operations/04-maintenance.md:55-64。10. 参数速查表参数默认值单位范围作用statusInterval1秒50 ~ 30000msdnode 状态上报间隔statusTimeoutMs5000ms50 ~ 30000多久未上报判为离线syncElectInterval4000ms10 ~ 172800000mnode 选举间隔syncHeartbeatInterval1000ms10 ~ 172800000mnode 心跳间隔syncVnodeElectIntervalMs4000ms10 ~ 172800000vnode 选举间隔syncVnodeHeartbeatIntervalMs1000ms10 ~ 172800000vnode 心跳间隔syncTimeout0ms0 ~ 172800000同步超时0 不额外限制arbHeartBeatIntervalSec2秒—仲裁心跳arbCheckSyncIntervalSec3秒—仲裁同步检查arbSetAssignedTimeoutSec14秒—指派 leader 超时supportVnodes核数 × 2 5个0 ~ 1024单节点 vnode 上限来源tglobal.c各注册行文档docs/zh/12-operations-and-tooling/03-components/01-taosd.md。11. 五个最常见的错误认知#错误认知事实1“三副本能挂两台”quorum replica/2 1三副本只能挂一台2“副本数可以设 2”社区版只允许 1 或 3企业版 2 副本必须配仲裁节点3“库配了 3 副本就高可用了”mnode 若为单副本它所在节点离线仍会全局不可用4“看到Sync leader is unreachable就说明集群坏了”连到 follower 也会报它客户端会自动重定向只有所有副本都不是 leader 才是真故障5“节点一离线就能做再平衡”存在离线 dnode 时会直接拒绝0x800003B6带仲裁的库也不参与自动 balance附集群问题提工单时建议一并收集的信息【集群规模】dnode 数、mnode 数、每个库的副本数与 vgroups 【可用性】show cluster alive 的返回值 【节点】select id, endpoint, vnodes, support_vnodes, status, note from information_schema.ins_dnodes; 【mnode】select id, endpoint, role, status from information_schema.ins_mnodes; 【vgroup】select vgroup_id, db_name, v1_dnode, v1_status, v2_dnode, v2_status, v3_dnode, v3_status, is_ready from information_schema.ins_vgroups; 【仲裁】show arbgroups;双副本场景 【参数】statusTimeoutMs、syncElectInterval、syncHeartbeatInterval、supportVnodes 的实际取值 【时间线】故障发生与恢复的准确时间点、期间做过什么操作 【服务端日志】离线前后的 taosdloggrep -i offline\|not leader\|quorum
