【etcd】排障五轴：Raft/WAL/MVCC/Watch/Lease 口令表

「etcd 挂了」在工单里可能指五种互不相同的失败：Leader 丢失、WAL fsync 拖尾、quota 写拒绝、Watch 全量重同步、或 Node Lease 集体过期。一上来对所有节点 defrag，可能把 MVCC 轴 的维护窗口当成 Raft 轴 的 quorum 问题放大；在未确认 Leader 时对 follower 做破坏性 restore，则可能永久丢 quorum。

前序篇已分轴讲机制；本文是系列第 15 篇：症状 → 轴 映射与 etcdctl 字段语义。口诀不变：先点名轴，再下钻组件。K8s 耦合见 第 13 篇；运维动作见 第 14 篇。无 etcd 集群则不粘贴伪造 endpoint status 表格。

本篇在系列中的位置

篇目	核心内容
第 14 篇 · 运维与升级	member change、backup/restore
第 15 篇 · 排障五轴	Raft/WAL/MVCC/Watch/Lease 口令表
第 16 篇 · 选型收束	排除树、开放问题、边界关闭
系列目录	全部篇目

版本锚定：etcd v3.5.33（tag v3.5.33）。etcdctl endpoint status 列名以该版本 CLI 为准。distributed/50 的百科单篇可速览 Watch/MVCC；本篇坐标系仅指 etcd 生产内核五轴，不与 Istio/Linkerd 等同名五轴混用。

一、口诀与总图

轴 1 Raft 共识与成员   — Leader、term、index、learner、quorum、复制 lag
轴 2 WAL 持久化与恢复 — fsync、WAL 段、snapshot、committed vs applied、NOSPC
轴 3 MVCC 存储与容量  — Revision、treeIndex、bbolt、quota、compaction、defrag
轴 4 Watch 客户端同步 — start_rev、synced/unsynced、ErrCompacted、背压
轴 5 Lease TTL 与语义  — grant/KeepAlive/checkpoint、Leader 切换、Txn 锁边界

Raft lag 与 apply lag 分列：Raft index 涨而 applied index 停 → 优先 Apply/MVCC 轴；committed 不涨 → Raft/WAL 轴。

flowchart TD
  symptom["Symptom"]
  symptom --> name["Name etcd axis first"]
  name --> a1["Axis1 Raft quorum"]
  name --> a2["Axis2 WAL fsync"]
  name --> a3["Axis3 MVCC quota"]
  name --> a4["Axis4 Watch rev"]
  name --> a5["Axis5 Lease TTL"]
  a1 --> drill["Drill component metrics logs"]
  a2 --> drill
  a3 --> drill
  a4 --> drill
  a5 --> drill

全链路位置见 第 1 篇 与 PLAN.md §八。

二、症状 → 轴（入口表）

默认顺序：轴 1 quorum → 轴 2 磁盘 → 轴 3 容量 → 轴 4 Watch → 轴 5 Lease。一次否证一轴。

三、轴 1：Raft 共识与成员

表象：集群不可写；etcdserver: no leader；Raft 选举频繁；follower RAFT INDEX 长期落后。

committed index vs applied index（第 3、6 篇）：

• committed 落后：复制/fsync（轴 1–2）；
• applied 落后 committed：Apply 管道 / bbolt batch（轴 3）。

与 distributed/13 分工：PreVote、ReadIndex 代码走读 → distributed/13；本篇只问「是否 Leader、是否 quorum」。

四、轴 2：WAL 持久化与恢复

表象：进程 crash 后长时间 starting；corrupt WAL；磁盘满；snapshot 失败。

指标（语义，非阈值截图）：

官方 hardware 文档给出 WAL fsync、backend commit 的 p99 告警参考（A 级）——具体毫秒数以 Hardware guidelines 为准，本站不固化「绿线」截图。

五、轴 3：MVCC 存储与容量

表象：database space exceeded；alarm NOSPACE；读延迟升；defrag 后仍满；大 Value 写失败。

alarm 处理顺序（语义）：compact → defrag（维护窗）→ alarm disarm——详见官方 alarm 文档；不要在生产高峰对全集群同时 defrag。

读旧 revision：Range 带 revision 参数读历史是 MVCC 特性；若业务「应读最新」却读到旧值，回到 第 8 篇 读一致性分列，不要与 Watch 轴混谈。

六、轴 4：Watch 客户端同步

表象：Watch 断流；etcdserver: mvcc: required revision has been compacted；apiserver/controller 大量 List；内存涨（unsynced watcher 追赶）。

ErrCompacted 标准动作：全量 List 拿新 resourceVersion 再 Watch——无捷径。大集群成本是 开放问题（第 16 篇 §三）。

与轴 3 关系：compaction 清历史 rev → 触发轴 4 失败；调 retention 是 联合调参，不是单轴旋钮。

七、轴 5：Lease TTL 与语义

表象：Lease 集体过期；分布式锁提前释放；K8s Node NotReady 雪崩；TTL「重置」。

KeepAlive 不经 Raft——Leader 故障时轴 5 与轴 1 同时亮；修复 Leader 后观察 Lease 是否 mass expire。

八、etcdctl 字段语义

以下解释 命令语义（A 级：etcdctl endpoint status、endpoint health 文档）。不粘贴本环境输出。

8.1 etcdctl endpoint health

• 对每个 endpoint 发 health RPC；
• 失败常见：无 Leader、超时、证书错误；
• 全绿不等于无 lag——需结合 status。

8.2 etcdctl endpoint status --write-out=table

常见列（v3；具体以 --help 为准）：

分列口诀：RAFT INDEX − RAFT APPLIED INDEX 持续拉大 → Apply/MVCC；两者都不涨 → Raft/WAL。

8.3 其它常用命令（语义）

九、K8s 控制面对照

完整耦合见 第 13 篇。

十、证据包写法

工单或 postmortem 建议 按轴贴证据，避免「etcd 日志一段」：

Axis1: endpoint status (Leader/term/index/applied)
Axis2: wal_fsync p99, disk free
Axis3: db size, quota, alarm, last compact
Axis4: compacted rev, client start rev, apiserver watch errors
Axis5: lease count, recent leader change, checkpoint flag

一次 incident 只验证一轴假设；否证后再换轴。

参考资料

规范 / 官方文档（A）

• etcd v3.5 · Monitoring
• etcd v3.5 · Hardware guidelines
• etcd v3.5 · Maintenance（alarm、defrag）

源码（A）

• etcd-io/etcd tag v3.5.33：etcdctl/ctlv3/command/endpoint_status_command.go；server/storage/mvcc/watchable_store.go

站内

• 第 1 篇 · 生产全景
• 第 8–12 篇 各轴机制
• distributed/13 · Raft 深读

实验台账

• endpoint status/health：未在本环境执行；字段语义来自官方文档与源码。

上一篇：运维与升级

下一篇：选型收束与开放问题