11.1 etcd 进程结构:gRPC、rafthttp、storage 与 backend
10.3 从读模式的角度看了 etcd 的一致性选择。
串行化读、线性一致读、ReadIndex、Lease Read,差别全部落在「读本地 mvcc 之前要不要先做一次多数派确认」这一个判断上。
但读模式只是客户可见的冰山一角。
一次请求要穿过 gRPC、共识、持久化、存储四层,才是 etcd 作为分布式数据库的全貌。
本节把镜头从「读什么」转到「进程里有什么」,从工程实现视角拆解 etcd 单进程的四大层,并给出从客户端到落盘的完整请求路径。
这是第 11 章的分水岭:前 10 章在讲协议与原理,从本节开始进入 etcd 的工程实现视角。
etcd 单进程内的四大层
etcd 每个成员都是一个单进程,同时扮演三类角色:对外它是 gRPC 服务器,对内它是 raft 参与者,落地时它是存储引擎。
四层分工如下:
| 层 | 代表包 | 职责 |
|---|---|---|
| gRPC 服务层 | etcdserver/api/v3rpc | KV、Watch、Lease、Cluster、Maintenance 五个服务入口 |
| raft 共识层 | raft 库 + rafthttp | 选举、日志复制、提交;成员间消息传输 |
| storage 层 | wal、snap | 追加式写前日志(WAL)与快照持久化 |
| backend 层 | backend、mvcc | bbolt(bolt)事务存储 + 内存 btree 索引的多版本控制 |
理解层的顺序是关键。
客户端只碰最外层的 gRPC;gRPC 层把读写翻译成共识层能处理的提案(proposal);共识层负责让提案被多数派接受;接受后的日志条目经 apply 落到 backend。
storage 层则是共识层的持久化依托,确保日志和快照在崩溃后不丢。
读路径不一样——读不产生提案,只复用 backend 的 mvcc 存储,这正是第 10 章反复强调的「读写共享同一份存储」。
进程内的并发也按这四层划分:gRPC 服务层每服务一个 goroutine 池,共识层由 raftNode 主循环驱动,apply 是独立消费队列,backend 另有后台批提交线程。
四个 goroutine 之间用 channel 交接,互不阻塞:写请求在共识主循环里推进,apply 在后面消化,读请求在 mvcc 上并发读。
理解「层 = 职责 = 独立的执行流」很重要,后文所有路径描述都可以对应到某条 goroutine 上。
这四层还对应磁盘上的一组固定文件。
一个 etcd 成员的数据目录默认形如:
| 目录/文件 | 内容 | 由哪层写 |
|---|---|---|
| member/wal/ | WAL 日志文件(*.wal) | storage 层 |
| member/snap/ | 快照文件(*.snap) | storage 层 |
| member/snap/db | bbolt 数据库文件 | backend 层 |
所以「etcd 的持久化」不是一个文件,而是 WAL、快照、数据库三类文件分工协作的结果:WAL 保共识日志,snap 压缩日志,db 保最终数据。
查看一个运行中集群的磁盘占用时,这三类文件常常各占一块,分别对应三种不同的增长与回收规律,第 15 章讲运维时会再回到这些文件。
gRPC 服务层:五个服务入口
etcd v3 的 API 面是一组 gRPC 服务,全部定义在 etcdserver/api/v3rpc 下,每个服务对应一种客户端能力:
| 服务 | 核心方法 | 对应能力 |
|---|---|---|
| KV | Range、Put、DeleteRange、Txn、Compact | 键值读写与事务 |
| Watch | Watch | 事件流订阅(第 13 章) |
| Lease | LeaseGrant、LeaseRevoke、LeaseKeepAlive、LeaseTimeToLive | 租约管理(第 15 章) |
| Cluster | MemberAdd、MemberRemove、MemberUpdate、MemberList | 成员变更(第 8 章) |
| Maintenance | Alarm、Status、Defragment、Snapshot、Hash | 运维与备份 |
| Auth | Authenticate、UserAdd、RoleAdd | 权限认证 |
每个服务入口都是一个独立的 Go 对象(kvServer、watchServer、leaseServer……),它们本身不含任何分布式逻辑。kvServer.Put 只是参数校验后把请求转发给 etcdserver 核心,真正的共识发生在下一层。
这一层在 lab 里没有独立文件,因为 lab 聚焦的是「共识之后」的语义;读者只要记住 gRPC 层是翻译器即可。
两个实现细节值得注意:Watch 是唯一的流式服务,一条长连接上持续推送事件,其余服务都是请求-响应式。
Maintenance 的 Snapshot 把整棵 mvcc 数据流式导出,是备份工具 etcdutl 的数据来源。
v2 与 v3 双 API 的区别也在这里定界。
v2 API 是 JSON over HTTP,路径形如 /v2/keys/foo,语义上是简单的值存储。
v3 API 是 gRPC,用 revision 表达多版本,支持事务、租约、watch。
两套 API 是两套完全独立的 keyspace,互不可见。
Kubernetes 从一开始就只用 v3,v2 在 etcd 3.4 起默认关闭,需要显式 --enable-v2 才能打开。
为了兼容浏览器与脚本客户端,v3 还通过 gRPC gateway 暴露一套 HTTP JSON 端点,如 /v3/kv/put、/v3/kv/range、/v3/kv/deleterange、/v3/kv/txn、/v3/lease/grant、/v3/watch、/v3/cluster/member/list,它们与 gRPC 方法一一对应,只是传输层换成 HTTP JSON。
写路径上,KV 服务其实是共识层的「翻译器」:PutRequest 被填进 InternalRaftRequest,Txn 的 If/Then 被翻译成 mvcc 的 CAS 原语,Compact 被翻译成 mvcc 的压缩指令。
客户端侧也一样:clientv3 把用户操作编码成 RangeRequest、PutRequest 等 proto 消息,再走 gRPC 发出去。
所以这一层读起来最像「数据库接口」,而它自身不碰任何一致性逻辑——一致性全部在下一层。
raft 共识层与 rafthttp 成员传输
共识层由两部分组成,分工非常明确。
raft 库(etcd 内部 vendor 的 go.etcd.io/etcd/raft/v3)是一个纯粹的状态机实现,处理任期、日志、commitIndex 等全部共识逻辑,但它不做任何网络 I/O。
它对外只有两个通道:Propose(data) 接收新提案,Ready() 输出需要持久化的条目、需要发送的消息、需要 apply 的已提交条目。
rafthttp 是 raft 库与成员间网络之间的桥梁。rafthttp.Transport 把 raft 库产生的消息(MsgApp、MsgVote、MsgHeartbeat、MsgSnap 等)编码成 HTTP 请求发给对端成员的 /raft 路径,也接收对端发来的消息交回 raft 库;快照走独立的 /raft/snapshot 流式通道。
Ready 是这一层里最重要的数据结构,一次返回四组东西:Entries(需要落盘的日志条目)、Messages(需要发给对端的消息)、CommittedEntries(已经提交、需要 apply 的条目)、Snapshot(需要安装或持久化的快照)。
etcdserver 的 run() 循环拿到 Ready 后,依次把 Entries 写进 WAL、把 Messages 交给 rafthttp、把 CommittedEntries 送进 apply 队列,然后调用 raft 库的 Advance() 推进下一批。
这个循环把「共识计算」和「进程间传输」解耦:raft 库只管算,rafthttp 只管搬。
共识层内部的消息类型有限,第 6 章已经见过大部分:
| 消息 | 用途 | 谁发 |
|---|---|---|
| MsgHeartbeat / MsgHeartbeatResp | 维持 Leader 活性、推进 commit 边界 | Leader |
| MsgApp / MsgAppResp | 复制日志条目、确认进度 | Leader / Follower |
| MsgVote / MsgVoteResp | 正式选举 | Candidate |
| MsgPreVote / MsgPreVoteResp | 预投票,隔离分区节点(第 5.3 节) | Follower |
| MsgSnap | 安装快照(第 9 章) | Leader |
心跳与日志复制的区别只在 Entries 是否为空:心跳是空 AppendEntries,携带 LeaderCommit;带日志的 AppendEntries 才是复制。etcd 里 Leader 按 electionTimeout / 2 的间隔发心跳,这个节奏同时决定了 follower 的选举超时不会被误触发。
lab 的 raft/sim.go 是对这一层最直接的最小复刻。Sim.Step() 每推进一步就做四件事:投递积压消息、Leader 广播 AppendEntries、推进选举定时器、统计选票完成状态迁移。
消息用一条 inflight 队列模拟,等价于把 rafthttp 的传输收敛成「固定延迟 1 tick 的投递」;SetPartition 传入的分区函数等价于网络分区。
也就是说,lab 里 raft 包同时扮演了「raft 库 + rafthttp」两个角色,broadcastAppendEntries 就对应 Leader 每轮向全部可达 follower 发送 MsgApp 的行为。
storage 层与 backend 层:WAL、btree 与 bolt
共识层之上是持久化,etcd 把它拆成两个职责不同的子系统。
storage 层负责共识日志的持久化,包含两个组件。
WAL(write-ahead log)是追加式的日志文件。
raft 库每产生一批条目,etcdserver 就 wal.Write(entries) 追加进去,必要时 fsync。
WAL 是崩溃恢复的根基——只要 WAL 里有,共识就能重放。
snap 用于当日志过长时把已 apply 的状态固化成快照文件,日志可以压缩丢弃(第 9 章)。
etcdserver 的 raft.Storage 实现把 WAL、snap 和内存里的 raft log 包在一起,向 raft 库提供 FirstIndex、LastIndex、Entry、Term 等接口。
WAL 本身按段(segment)组织:每个 .wal 文件固定大小,写满就轮换新的段,防止单文件无限膨胀。
备份、截断、磁盘回收都以段为单位。
所以 WAL 目录里的文件数量是有限的,旧段在日志压缩后被清理。
backend 层负责业务数据(键值)的存储,也有两个组件。
bbolt(早期叫 bolt)是一个嵌入式 KV 数据库,数据落盘到 member/snap/db 单个文件,事务按批提交。
mvcc 在 bbolt 之上提供多版本语义:mvcc 在内存维护一棵 btree 索引,把 key 映射到它的版本链;版本数据本身存在 bbolt 的桶里。
第 12 章会详细展开 revision、版本链、墓碑、压缩。
bbolt 的写事务不逐条 fsync,而是攒批:默认攒满一批(约一万次写)或过了一个批间隔(默认约 100ms)才提交落盘。
这是 backend 与 WAL 在持久化节奏上的本质差别——WAL 是共识日志的落地点,讲究「该 fsync 时必须 fsync」;bbolt 是数据状态的落地点,讲究「攒批摊薄成本」。
storage 层与 backend 层写的东西不一样:WAL 记的是「共识日志」,backend 记的是「数据状态」。
这也是 etcd 能在崩溃后自愈的原因:WAL 保日志,backend 保数据,两者用 revision 与快照对齐。
崩溃恢复的次序也由此确定:重启时先读 snap + WAL 恢复 raft 日志,再打开 db 恢复 mvcc 存储,两者能对上,集群才继续对外服务。
一次写请求的完整路径
把四层串起来,看一次 etcdctl put /foo bar 在 Leader 成员上的完整旅程:
| 步骤 | 发生位置 | 动作 |
|---|---|---|
| 1 | gRPC 服务层 | 客户端 gRPC 到达 kvServer.Put,校验后转给 etcdserver |
| 2 | raft 共识层 | 封装成 InternalRaftRequest 提案,调 Propose |
| 3 | raft 共识层 | raft 库把提案追加进内存日志,经 Ready() 交回 |
| 4 | storage 层 | 条目写进本地 WAL,必要时 fsync |
| 5 | rafthttp | 同时把 MsgApp 广播给所有 follower |
| 6 | raft 共识层 | 多数派确认后 commitIndex 推进到这条日志 |
| 7 | backend 层 | apply 队列把 Put 应用到 mvcc(内存 btree + bolt 事务) |
| 8 | gRPC 服务层 | 响应头带上本次写产生的 revision 返回客户端 |
把这条路径压成一张 ASCII 图:
client gRPC
→ kvServer.Put(校验)
→ etcdserver:InternalRaftRequest 提案
→ raft.Propose → Ready
→ wal.Write + fsync (storage 层)
→ rafthttp 广播 MsgApp (并行)
→ 多数派确认 → commitIndex 推进
→ apply → mvcc backend (backend 层)
→ 响应头 revision 返回
第 4、5 步是并行的:WAL 持久化和网络复制没有先后依赖,谁先完成取决于磁盘与网络延迟。
真正决定写延迟的是「WAL fsync + 多数派确认」这两个串行环节——这是下一节的主角。
读路径在这一幅图里几乎相反:Range 请求不进第 2 步,而是在第 7 步的 mvcc 存储上直接读,第 10 章讲过的 ReadIndex、Lease Read 只是给读额外加一层确认。
两个失败场景值得预先画出来。
其一,客户端把写发到了 follower:follower 收到提案后不会自己提交,而是返回带 Leader 地址的错,客户端 clientv3 据此重定向到 Leader 再重试——所以正常负载下写只落在 Leader。
其二,Leader 在复制中途崩溃:多数派未确认,提案未提交,客户端收不到成功响应,日志可能留在旧 Leader 的 WAL 里被新 Leader 用日志对齐规则覆盖或保留,但绝不可能「先成功、后丢失」。
这两个场景把四层的边界又描了一遍:哪一层出错,都由哪一层兜底。
与 lab 的模块映射
lab 按模块划分,恰好对应本节四层中「共识之后」的三层:
| lab 包 | 对应 etcd 层 | 代表文件 |
|---|---|---|
| raft | 共识层 + rafthttp 传输抽象 | raft/sim.go 事件驱动 Step |
| store | backend 的 mvcc | store/mvcc.go(revision、版本链、墓碑、compact) |
| watcher | 事件流 | watcher/watch.go(版本区间、扇出、限流) |
| lease | 租约管理 | lease/lease.go(TTL、续约、过期删 key) |
gRPC 服务层没有对应文件,因为 lab 只仿真「共识之后」的存储语义;storage 层的 WAL 在 lab 里被抽象成 raft 日志追加,快照对应 raft/snapshot.go。
这样四层结构在 lab 里都有落点,读者可以用真实测试印证本节讲的分层。
raft 包验证共识层的行为:选举、日志复制、commit 推进、快照、成员变更,对应 raft/raft_test.go、raft/replication_test.go 两组用例。
store、lease、watcher 三个包验证 backend 之上、gRPC 之下的存储语义:mvcc 的 revision 与版本链、租约的 TTL、watch 的版本区间事件。
本节 lab
本节不引入新的测试文件,而是用已有包印证四层结构的划分。
先跑全量确认基线:
cd private/labs/k8s-etcd-lab
go test ./... -count=1
当前全量 46 个用例通过,按包分布为:raft 21、store 8、watcher 7、lease 4、clock 3、consistency 3。
重点看 raft/raft_test.go 的 TestElectionReachesAgreement:
go test ./raft -run TestElectionReachesAgreement -v
预期断言:5 节点、固定随机种子 20261112 的仿真里,随机选举超时(5~10 tick)下最多 500 步必定选出一位 Leader,且其任期 Term ≥ 1。
这正是「随机超时最终收敛到一位任期递增 Leader」的最小验证,对应 etcd 中 raft 库 + rafthttp 完成选举的全部行为。
其余包合起来覆盖 storage/backend 层:store 的 8 个用例验证 mvcc 的 revision 与版本链,lease 的 4 个用例验证租约,watcher 的 7 个用例验证事件流。
一套 go test ./... 就能把本节的四层结构全数跑绿。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。