【etcd】排障五轴：Raft/WAL/MVCC/Watch/Lease 口令表
内容提要
本文介绍etcd排障的五轴坐标系：Raft共识、WAL持久化、MVCC存储、Watch同步、Lease TTL。通过症状映射到对应轴，提供诊断工具和指标，如endpoint status字段解读。强调先定位问题轴再下钻组件，避免盲目defrag或restore。附K8s控制面对照表和证据包写法建议。
延伸解读
先定位轴，再动手
排障时不要一上来就 defrag 或 restore。文章强调先根据症状判断问题属于哪个轴：比如写超时先查 Raft 和 WAL，而不是直接升 quota；Watch 断开先查 compaction 和 start_rev，而不是加节点。一次只验证一个轴的假设，否证后再换轴，避免误操作放大问题。
committed 与 applied 的分列意义
Raft index 涨而 applied index 停，说明问题在 Apply/MVCC 轴；committed 不涨则问题在 Raft/WAL 轴。这个区分能快速缩小排查范围。例如，如果 committed 落后，优先检查网络分区、磁盘 fsync 延迟；如果 applied 落后，则关注 bbolt 批量提交和 MVCC 管道。
Lease 与 Raft 的联动
KeepAlive 不经过 Raft，所以 Leader 故障时 Lease 轴和 Raft 轴会同时亮红灯。修复 Leader 后要观察 Lease 是否集体过期，这可能是 Node NotReady 雪崩的根因。排障时不能只盯着一个轴，要留意轴之间的相互影响。
证据包按轴组织
写工单或 postmortem 时，建议按轴贴证据，而不是笼统地贴一段日志。比如 Axis1 贴 endpoint status 的 Leader/term/index，Axis2 贴 wal_fsync p99 和磁盘空间，Axis3 贴 db size、quota、alarm 等。这样能清晰展示排查思路，也便于他人快速定位问题。
Q&A
etcd 排障时，如何根据症状快速定位问题轴？
根据症状映射到对应轴：无 Leader 或选举风暴优先查 Raft 轴；写超时先查 Raft 和 WAL；database space exceeded 查 MVCC 轴；Watch 断开或 ErrCompacted 查 Watch 轴；Node 批量 NotReady 查 Lease 轴。默认顺序为 Raft → WAL → MVCC → Watch → Lease，一次否证一轴。
etcd 中 Raft 轴和 WAL 轴的区别是什么？
Raft 轴关注共识与成员，如 Leader、term、index、quorum；WAL 轴关注持久化与恢复，如 fsync、WAL 段、snapshot。若 committed index 不涨，问题在 Raft/WAL；若 committed 涨但 applied 不涨，问题在 Apply/MVCC。
etcd 出现 mvcc: database space exceeded 错误时，应该如何处理？
该错误属于 MVCC 轴，应先检查 quota 和 db size，并查看 alarm。处理顺序为：先 compact 清理历史版本，再在维护窗口 defrag，最后解除 alarm。避免在生产高峰对全集群同时 defrag。
etcd 中 ErrCompacted 错误是什么原因导致的？如何解决？
ErrCompacted 是 Watch 轴错误，通常因为客户端请求的 revision 已被 compaction 清理。解决方法是客户端全量 List 获取新 resourceVersion 再重新 Watch，无捷径。
etcd 中 Lease 集体过期可能是什么原因？
Lease 集体过期可能由 KeepAlive 停止、Leader 切换、时钟漂移或客户端崩溃导致。若 Leader 故障，Lease 轴与 Raft 轴同时亮，修复 Leader 后观察是否 mass expire。
etcdctl endpoint status 输出中，RAFT INDEX 和 RAFT APPLIED INDEX 的差值代表什么？
RAFT INDEX 是已提交日志位置，RAFT APPLIED INDEX 是已应用到 MVCC 的位置。若两者差值持续拉大，说明 Apply 管道或 MVCC 存储有问题，优先查 Apply/MVCC 轴；若两者都不涨，则问题在 Raft/WAL 轴。
etcd 排障时，为什么不能一上来就 defrag 或 restore？
因为不同症状对应不同轴，盲目 defrag 可能把 MVCC 维护窗口当成 Raft quorum 问题放大；未确认 Leader 时 restore 可能永久丢 quorum。应先定位问题轴再下钻组件。
K8s 中 apiserver 504 应该优先排查 etcd 的哪个轴？
apiserver 504 应优先排查 Raft、WAL、MVCC 轴（1-3），先看 apiserver metrics 分列，再落 etcd 轴。
