11.2 写入路径:Put→commit→apply→落盘
11.1 把 etcd 单进程的四大层画了出来:gRPC 服务层把写请求翻译成提案,raft 共识层负责让提案被多数派接受,storage 层用 WAL 保日志,backend 层用 mvcc 落数据。
本节沿这条路径走完一次真正的写:etcdctl put /foo bar 从客户端出发,经过提案、WAL、复制、确认、apply,最终落盘并返回带 revision 的响应头。
读路径在第 10 章已经讲透,这里只看写,并把延迟、批量、租约这三个工程细节一并说清。
整条路径可以用一句话概括:提案进共识,共识写 WAL,WAL 换多数,多数定提交,提交再 apply,apply 才可见。
一次 etcdctl put /foo bar 的完整旅程
在 Leader 成员上,一次 Put 的完整旅程可以拆成七个环节:
| 环节 | 组件 | 是否阻塞响应 |
|---|---|---|
| gRPC 入口 | kvServer.Put | 否,毫秒级翻译 |
| 构造提案 | etcdserver 封装 InternalRaftRequest | 否 |
| 追加本地日志 + WAL fsync | storage 层 wal | 是,磁盘延迟 |
| 广播复制 | rafthttp 发 MsgApp | 与第 3 步并行 |
| 多数派确认 | raft 库推进 commitIndex | 是,网络延迟 |
| apply 落 mvcc | backend 层 | 否,本机内存 |
| 返回响应 | gRPC 带 revision | — |
按序展开。
- gRPC 入口:客户端 gRPC 到达 Leader 的
kvServer.Put,做参数校验(key 非空、value 大小限制),随后转给 etcdserver 核心。 - 构造提案:etcdserver 把操作封装成
InternalRaftRequest(一个 proto 消息,含 Put 的 key/value),marshalling 后作为提案数据交给 raft 库的Propose。 - 追加本地日志:raft 库把提案作为一条新日志条目追加进内存日志,产生
Ready,etcdserver 把条目写进本地 WAL(必要时 fsync)。 - 广播复制:raft 库同时产生 MsgApp 消息,经 rafthttp 广播给所有 follower;follower 追加成功后回 AppendEntriesResponse。
- 多数派确认:Leader 收到含自己在内的多数派确认后,把 commitIndex 推进到这条日志的位置,并通过心跳里的 LeaderCommit 字段让 follower 同步推进本地 commit。
- apply:apply 队列取出已提交条目,把 Put 应用到 mvcc backend(内存 btree 更新 + bolt 事务)。
- 返回响应:响应头带上本次写产生的 revision 与该成员自己的 ID、任期信息返回客户端。
第 3、4 步并行,第 5 步是「多数派确认」的唯一同步点。
对客户端来说,「写成功」意味着步骤 5 完成、步骤 6 已在多数成员上可见;而步骤 4 只对 follower 的日志持久化负责,不直接决定响应时机。
两个细节容易被忽略。
其一,etcdctl 走的是 clientv3 的负载均衡:它会把请求发给任意成员,follower 收到写请求后返回带 Leader 地址的错误,clientv3 自动重定向重试,最终落在 Leader。
其二,响应头里的 revision 是「本成员 apply 该条目时已经推进到的全局主版本号」,同一批并发写共享同一次推进,所以响应头的 revision 不一定等于这一笔写单独产生的 mod_revision——它们之间是「推进到 ≥ 本次写」的关系。
WAL 与 fsync:写路径的核心延迟
写路径上最慢的单个操作几乎总是 WAL 的 fsync:条目要先写进 WAL 文件再 fsync 到磁盘,磁盘控制器确认写入完成,这笔条目才在崩溃后可靠。
量级对比一目了然:
| 存储 | 单次 fsync 延迟 |
|---|---|
| NVMe SSD | 约 0.1~0.5 ms |
| 普通 SSD | 约 0.5~2 ms |
| 机械盘 | 约 5~10 ms |
一次同可用区网络往返通常也在 0.5~2 ms。
所以对 SSD 上的集群,fsync 与网络往返大体同量级;对机械盘,fsync 直接成为写延迟的天花板。
这也是为什么生产 K8s 集群把 etcd 放在 NVMe 盘上:换盘相当于把写路径的一半延迟砍掉。
etcd 降低这块成本的办法是批量提交:不是每一条日志 fsync 一次,而是把一小段时间内到达的多个提案聚合成一个 WAL 批,一次 wal.Write 写一批、一次 fsync 落盘。
这样 fsync 的固定开销被摊到一批条目上,单位写成本随批大小下降。
工程上的取舍是「攒批」和「延迟」之间的平衡:
| 策略 | 代价 | 收益 |
|---|---|---|
| 每条都 fsync | 延迟高,每写一次磁盘同步 | 响应最及时 |
| 批量攒一批再 fsync | 批量边界稍晚响应 | 单位写成本显著下降 |
etcd 的默认是后者:WAL 按批写、按批 sync,同时保证「这批里如果有已提交条目,必须 fsync 完成才允许继续」,从而既不牺牲批量摊薄,也不破坏「写成功即持久」的语义。
具体到实现,etcdserver 用 Ready.MustSync 标记强制同步点:含有已提交条目的批会带 MustSync,写完后立即 wal.Sync(),未提交的普通批则留给攒批节奏。
--unsafe-no-fsync 这种开关会带来数据丢失风险的直接原因也在这里:关掉 fsync,写延迟骤降,但机器一掉电,WAL 里可能只有部分条目落盘,未 fsync 的已确认写入可能丢失。
生产环境绝不该开这个开关,它就是给「要吞吐、不心疼数据」的实验场景留的逃生口。
复制、确认与 commitIndex 推进
提案一旦进了 raft 库,剩下的就是第 6 章讲过的复制协议。
Leader 用 MatchIndex、NextIndex 记录每个 follower 的复制进度:NextIndex[f] 是 Leader 认为 follower 下一条该收到的日志位置,复制成功则推进,一致性检查失败则逐条回退——第 6 章讲过的日志对齐规则在这里落地。
commitIndex 的推进规则只有一个:日志条目只有在多数派(含 Leader 自身)的日志里都存在,才允许提交。
Leader 维护每个 follower 的 MatchIndex,取排序后中位数的 MatchIndex 作为可提交位置。
这正好对应第 2 章的「过半即安全」:中位数所在位置必然已被多数派复制。
用具体数字走一遍。
- 3 节点集群,多数派 = 2。
Leader 收到自己 + 任意 1 个 follower 的确认即可提交。 - 5 节点集群,多数派 = 3。
Leader 收到自己 + 任意 2 个 follower 的确认才可提交。 - 一个 follower 掉队(日志落后 100 条)不影响提交,只要其余节点凑够多数;掉队节点通过后续 AppendEntries 补日志。
写响应必须等 commit 完成,这一点把「线性一致写」和「可能丢失的写」划清了界限。
提交前(多数派未确认),Leader 崩溃会丢日志,客户端收不到成功响应。
提交后,即使 Leader 崩溃,新 Leader 也必然带有这条日志(第 7.2 节 Leader 完整性),写不丢。
所以从客户端的视角,成功响应的到达时间 ≈ WAL fsync 完成时间 + 多数派确认完成时间——两者有一个没有先完成,响应就得等。
etcd 对「写并发」还有一层聚合:多个并发写请求在 raft 里是同一轮 AppendEntries 里的一批条目,Leader 按日志顺序 apply,所以同一批写的响应顺序与日志顺序一致。
这让批量 fsync 的收益在并发写下被放大:一个 WAL 批可以同时服务几十笔并发写,每笔摊到的 fsync 成本极低。
apply:日志变成 mvcc 数据,读写共用一份存储
commitIndex 推进只是「日志被多数派接受」,数据要变成可读的键值,还要经过 apply。
apply 队列消费已提交条目,逐条调用 mvcc 的 Put/Txn,把新值写入内存 btree 索引,并归入 backend 的 bolt 批事务。
apply 和读的关系是本节的要点:apply 写的就是读路径读的那份存储。
第 10 章说过串行化读和线性一致读最终都在成员本机读 mvcc,这里的 mvcc 正是 apply 写出来的状态。
两条路径共用一棵 btree 索引、一个 bolt 事务池,不存在「写一份、读另一份」的中间缓存。
这也解释了为什么写响应返回后立刻读一定能看到刚写的值:读走的是同一条内存索引,revision 已经推进。
apply 阶段还承担另外两类工作。
- watch 事件分发:Put 产生的事件会广播给所有订阅该 key 的 watcher,事件的 revision 就是这次写的 revision——第 13 章的扇出与限流在这里发生。
- 租约关联登记:如果 Put 的请求里带了 lease ID,mvcc 会在索引里记下「这个 key 属于某租约」,为第 15 章说的过期自动删除做准备。
还有一个失败路径。
apply 本身出错时,etcd 不会假装成功,而是让该成员退出 Leader 角色并重新协商,保证「已提交但未 apply 成功」的状态不会长期悬挂。
这条路径平时不会触发,但它解释了为什么 apply 队列与共识主循环是分离的两个 goroutine:共识只负责推进 commit,apply 只负责消费,任何一方卡住都不影响另一方继续工作。
从「日志顺序」到「apply 顺序」再到「revision 顺序」,写路径全程是串行的:raft 保证日志顺序,apply 按日志顺序执行,mvcc 每次写推进全局 revision。
这条链上的顺序性是 K8s resourceVersion 单调递增的前提,第 11.3 节会看到它如何被利用。
挂租约的 key:写入、续约与过期删除
不是所有 key 都永续存在。
etcd 允许 Put 时带一个 lease ID,把 key 挂到租约上,租约到期时这些 key 会被自动删除。
写入挂租约 key 的路径多两步。
- 写入时:Put 请求里带 lease ID,apply 阶段在 mvcc 写入新值的同时,调用 lease 管理器登记「该 key 绑定租约 L」。
- 租约生命周期:租约通过 KeepAlive 续约刷新 TTL;Tick 推进时间,剩余时间递减;归零时租约过期,lease 管理器返回「过期租约 + 它关联的全部 key」,删除动作随即在 mvcc 里逐 key 执行。
Kubernetes 里最典型的挂租约用法是节点心跳租约与事件清理,而控制器选主用的是独立的 Lease 资源对象(第 15 章和第 11.3 节)。
这里要分清两个层次:etcd 键级租约(Put 时挂 lease ID,到期自动删 key)与 K8s Lease 对象(一个普通对象,内容由控制器读写,是否续约由持有者决定)是两回事。
前者是 etcd 的存储机制,后者是 K8s 的应用协议。
租约语义的关键点有两个:一是「TTL 递减」由时钟驱动,二是「过期删 key」是批量动作而非每 key 单独检查——这两点在 lab 里都有直接断言。
过期删除的次序也很讲究:lease 管理器先返回一批过期租约及其 key,mvcc 再统一做删除事务,而不是逐个 key 判断,这样一次过期可以打包成一个批量事务,避免大量小事务。
租约还与读路径的 Lease Read 相关,但注意区分:第 10.2 节的 Lease Read 用「时钟租约」省掉 ReadIndex 的往返,是针对读的一致性优化;本节的键级租约是针对「数据生命周期」的机制。
两者共享 lease 这个词,语义完全不同,K8s 里两处都用到。
与 lab 的映射
写入路径的两段核心语义在 lab 里分别有对应用例。
- raft 复制与 apply:
raft/replication_test.go的TestAppendEntriesReplicatesLog。
它构造 3 节点集群,让 Leader 追加 3 条命令(set:a=1、set:b=2、set:c=3),跑 300 步仿真直到全部节点 commit 完毕,然后断言:每个节点日志长度都等于 3,且每个节点的状态机都包含已应用命令。
这正好覆盖「追加 → 复制 → 多数派确认 → commit → apply」整条链路。 - 租约 TTL 递减:
lease/lease_test.go的TestLeaseGrantAndRemainingDecay。
它创建 TTL=5 的租约,断言创建时剩余时间等于 5、未过期;仿真时钟 Tick 两次后,断言剩余时间递减为 3。
这是挂租约 key 自动清理机制的基础语义。
两个用例都是「写入侧」的最小闭环:前者验证日志从 Leader 复制到全部节点并被 apply,后者验证时间推进对租约的影响。
读路径的对应在 store 包,第 12 章会继续。
本节 lab
分别跑两个用例:
cd private/labs/k8s-etcd-lab
go test ./raft -run TestAppendEntriesReplicatesLog -v
go test ./lease -run TestLeaseGrantAndRemainingDecay -v
预期断言:
TestAppendEntriesReplicatesLog:3 节点集群,Leader 提交 3 条命令后,所有节点日志长度 = 3,且状态机均包含已应用命令set:c=3——验证写路径的日志复制与 apply。TestLeaseGrantAndRemainingDecay:TTL=5 的租约 Tick 两次后剩余时间 = 3,TTL 未归零前租约不过期——验证挂租约 key 的 TTL 递减。
两个用例分别压住写路径的「共识侧」与「租约侧」。
合起来覆盖本节从 Put 到 commit 再到 apply、以及租约过期删除的完整语义。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。