《Kubernetes 分布式系统原理深入解析》11.1 etcd 进程结构:gRPC、rafthttp、storage 与 backend

etcd 单进程由 gRPC 服务层、raft 共识层(raft 库 + rafthttp)、storage 层(WAL + snapshot)与 backend 层(btree + bolt 的 mvcc)四层构成,写请求经提案、WAL、复制、apply 一路落到 backend。lab 用 raft/sim.go 事件驱动 Step 模拟共识层与传输,store、lease、watcher 包对应 backend 之上的 mvcc、租约与事件流,全量 46 用例通过。

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/v3rpcKV、Watch、Lease、Cluster、Maintenance 五个服务入口
raft 共识层raft 库 + rafthttp选举、日志复制、提交;成员间消息传输
storage 层wal、snap追加式写前日志(WAL)与快照持久化
backend 层backend、mvccbbolt(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/dbbbolt 数据库文件backend 层

所以「etcd 的持久化」不是一个文件,而是 WAL、快照、数据库三类文件分工协作的结果:WAL 保共识日志,snap 压缩日志,db 保最终数据。
查看一个运行中集群的磁盘占用时,这三类文件常常各占一块,分别对应三种不同的增长与回收规律,第 15 章讲运维时会再回到这些文件。

gRPC 服务层:五个服务入口

etcd v3 的 API 面是一组 gRPC 服务,全部定义在 etcdserver/api/v3rpc 下,每个服务对应一种客户端能力:

服务核心方法对应能力
KVRange、Put、DeleteRange、Txn、Compact键值读写与事务
WatchWatch事件流订阅(第 13 章)
LeaseLeaseGrant、LeaseRevoke、LeaseKeepAlive、LeaseTimeToLive租约管理(第 15 章)
ClusterMemberAdd、MemberRemove、MemberUpdate、MemberList成员变更(第 8 章)
MaintenanceAlarm、Status、Defragment、Snapshot、Hash运维与备份
AuthAuthenticate、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 成员上的完整旅程:

步骤发生位置动作
1gRPC 服务层客户端 gRPC 到达 kvServer.Put,校验后转给 etcdserver
2raft 共识层封装成 InternalRaftRequest 提案,调 Propose
3raft 共识层raft 库把提案追加进内存日志,经 Ready() 交回
4storage 层条目写进本地 WAL,必要时 fsync
5rafthttp同时把 MsgApp 广播给所有 follower
6raft 共识层多数派确认后 commitIndex 推进到这条日志
7backend 层apply 队列把 Put 应用到 mvcc(内存 btree + bolt 事务)
8gRPC 服务层响应头带上本次写产生的 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
storebackend 的 mvccstore/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 ./... 就能把本节的四层结构全数跑绿。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图