1.3 本书路线图与 lab 结构
一张地图如果没有比例尺和地名,就没法导航。第 1.2 节给了「目标 × 挑战」这张地图,本节给它装上坐标:四卷分别处理哪些问题、每卷配套哪个 lab 工程、每节怎么用 lab 验证、读者需要什么前置、按什么路径读。如果你只想快速判断「这本书值不值得读」,看四卷路线表就够了;如果你想边读边动手,看 lab 结构。
四卷路线:从内核到边界
四卷的推进顺序就是「从内核到边界」:先讲状态怎么被一致地存住(卷一),再讲状态怎么流动、怎么收敛(卷二),然后讲决策与资源(卷三),最后把前面所有承诺推到跨节点、跨集群的边界(卷四)。
| 卷 | 主题 | 回答的问题 |
|---|---|---|
| 一 | 共识与存储:Raft 与 etcd | 集群状态怎么被一致地存储起来?Raft 每一步为什么这样设计? |
| 二 | 控制面与调谐循环 | 状态怎么变成事件流?控制器怎么让系统收敛到期望状态? |
| 三 | 调度与资源 | 决策怎么做出?资源怎么衡量、怎么驱逐、怎么伸缩? |
| 四 | 网络、存储、多集群与一致性边界 | 跨节点、跨集群时,一致性承诺还剩多少?边界在哪里? |
每一卷的内容主线如下:
- 卷一沿着 etcd 的三层往下挖:Raft 共识(怎么让所有副本同意同一份日志)→ mvcc 状态机(怎么把日志变成可查询、可 watch 的多版本键值)→ watch 与 lease(怎么把存储变成事件流与心跳)。一致性模型、时钟与顺序、CAP 的精确表述都在这卷正面处理。
- 卷二把镜头移到 apiserver 与控制器:list-watch 如何把 etcd 变成事件流,informer 如何在本地缓存上建立增量视图,控制器如何用调谐循环让系统收敛到期望状态,领导者选举在控制面里扮演什么角色。
- 卷三处理决策与资源:调度器怎么 Filter 又怎么 Score,资源请求与限制如何被量化,驱逐与优先级在过载时怎么保住关键负载,水平与垂直伸缩如何基于指标闭环。
- 卷四是「一致性边界」:CNI 网络数据面把数据包跨节点搬运,CSI 存储插件把持久卷接进 Pod,多集群联邦在更广的地域里重演一致性问题——最终一致在这里不再是被容忍的缺点,而是被当作第一公民。
卷一之内:第 1–5 章的地图
卷一全卷 5 章,lab 的三个包正好对齐这三段主线:
| 章节 | 主题 | 对应 lab 包 |
|---|---|---|
| 第 1 章 | 目标、挑战与路线图(本章) | —— |
| 第 2 章 | 一致性模型与 CAP 的精确表述 | consistency |
| 第 3 章 | 时钟与顺序:Lamport / 向量时钟 / HLC | clock |
| 第 4 章 | 共识问题、FLP、Paxos 简述与 Raft 动机、集群结构 | raft |
| 第 5 章 | 选举协议、选举限制、pre-vote 与异常场景 | raft |
也就是说,raft 包承担卷一的「重头戏」:从 quorum 数学到提交轮数、从选举收敛到 pre-vote 隔离、再到 FLP 的不终止演示。每章约 9 个用例的规划密度,保证每个机制都能被单独拿出来验证。
每卷一个 Go lab:四个可运行工程
「可运行」是本书区别于纯理论书稿的承诺。每一卷配套一个独立的 Go lab 工程,放在 private/labs/ 下:
| 卷 | lab 工程 | 位置 | 规划用例数 |
|---|---|---|---|
| 一 | k8s-etcd-lab | private/labs/k8s-etcd-lab | 45 |
| 二 | k8s-ctrl-lab | private/labs/k8s-ctrl-lab | 45 |
| 三 | k8s-sched-lab | private/labs/k8s-sched-lab | 45 |
| 四 | k8s-net-lab | private/labs/k8s-net-lab | 45 |
几个要点:
- 每卷 45 个用例是硬目标,确保每个核心机制至少有一个可运行断言,而不是靠通读源码获得印象。卷一共 5 章,平均每章约 9 个用例;当前已落地 13 个,随第 2–5 章推进补齐到 45。
- lab 是读者侧的验证载体,不是书稿的一部分。它位于 git-ignored 的
private/labs/,不进入 Hugo 构建;你需要本地有 Go 工具链才能运行。 - 每个 lab 都自带 README,说明模块划分与章节对照。以
k8s-etcd-lab为例,README 明确写着:consistency对应第 2 章一致性模型,clock对应第 3 章时钟与顺序,raft对应第 4–5 章共识与选举,store/mvcc、watcher、lease随后续批次加入。
每节如何用 lab
正文遇到机制性内容时,会给出三样东西:lab 路径、运行命令、该用例断言什么。格式约定如下:
cd private/labs/k8s-etcd-lab
go test ./consistency -run TestCAPPartitionTradeoff -v
约定有三条:
- 断言数取真实运行输出,不写静态猜测。正文里出现的「这个用例断言 X」都来自实际
go test的判定,读者在本地重跑能得到同样的--- PASS。 - 一个
TestXxx对应一个核心机制。用-run定向跑单个用例,用./... -v跑全量回归;正文会明确区分这两种用法。 - 用例注释里标注章节。每个测试函数顶部都有一行
// TestXxx(N.M 章节)的注释,方便你在正文与代码之间来回跳。
以第 2.1 节的例子预热:TestCAPPartitionTradeoff 用两个仿真器分别演示「线性一致 + 分区 → 分区副本写被拒绝」与「最终一致 + 分区 → 两侧各自接受写并各自可见」,断言直接写在测试里,跑一遍就是一次直观的定理演示。
lab 的边界:仿真不替代真实系统
为了让每个结论可复现,lab 用了「tick 驱动的离散事件仿真」:网络用可编程的分区函数与传播延迟建模,时钟用计数器与逻辑时间建模,节点状态用结构化 struct 建模。这带来两个直接好处:
- 确定性:同一随机种子,同一结果。
raft的选举用例固定种子(如NewSim(5, 20261112)),读者重跑得到完全相同的--- PASS; - 可操控:
SetPartition能精确指定谁和谁断连,SetPropagation能精确指定传播延迟。真实网络里很难干净地复现一个分区,仿真里一行代码就能做到。
同时要诚实说明 lab 不仿真什么:真实的网络延迟分布、磁盘 fsync 的慢路径、进程崩溃的操作系统语义、GC 停顿——这些「生产里的脏乱差」不在 lab 范围内。本书用 lab 验证的是机制的不变量(quorum 阈值、选举限制、一致性可见性窗口),而不是复刻生产事故的统计分布;生产层面的参数取舍,正文会用真实组件的默认值与事故场景来补充。
读者前置要求
本书自含理论,但不自含语言与平台基础。建议具备以下前置:
- Go 基础:能读 Go 代码、会跑
go test即可,不需要是 Go 专家。lab 的代码刻意保持小而直,每份文件不超过几百行。 - 操作系统与网络基础:理解进程、socket、TCP/UDP、文件
fsync的基本概念。不需要深入内核。 - K8s 基础概念:Pod、Deployment、Service、Node 这四样,哪怕只在
kubectl里操作过也算数。本书不假设你运维过生产集群。
分布式理论零基础可以进:每一节都会自含地解释「为什么会有这个问题、目标与约束是什么」,不要求你先读过其他教材。
把前置要求落成一次三分钟自测:
| 问题 | 自测点 | 如果不会 |
|---|---|---|
go test ./consistency 在本机跑得动吗? | Go 工具链就绪 | 先装 Go 1.26 或更新版本 |
| 分得清 Pod 与 Deployment 吗? | K8s 基本对象 | 先用 kubectl 跑一个最小 demo |
| 知道 socket 通信与共享内存的区别吗? | 通信模型 | 补操作系统与网络基础 |
| 能说清「共识」是什么吗? | 分布式理论 | 没关系,第 4 章会自含讲解 |
这本书的设计是:前三项满足即可进场,第四项边读边补。
学习路径:概念 → 机理 → 验证 → 生产对照
每节建议按四步循环推进,四步缺一不可:
| 步骤 | 做什么 | 示例(第 2.1 节 CAP) |
|---|---|---|
| 概念 | 弄清这一节解决什么问题、目标与约束 | 分区时「线性一致」与「可用」二选一 |
| 机理 | 追数据流与状态机:协议怎么运作 | 线性一致的读必须见最新写;最终一致有滞后窗口 |
| 验证 | 跑 lab、改参数、确认断言 | TestCAPPartitionTradeoff 断言写被拒 / 两侧分裂 |
| 生产对照 | 回到 K8s 真实组件,定位实现位置 | etcd 多数派策略、apiserver informer 缓存 |
其中「生产对照」是本书的收尾动作:每个 lab 验证过的机制,最后都要指回它在 etcd、apiserver、controller-runtime 或 kube-scheduler 里的真实实现。这样一轮读下来,你对一个机制的理解是「概念 + 代码 + 行为」三层叠起来的,而不是只有定义。
把四步走一遍,用一个具体对象串起来。以「K8s 为何用 resourceVersion 排序」为例:
- 概念:没有全局时钟,墙钟不能给跨节点事件排序;
- 机理:etcd 每次写生成一个递增 revision,对象带 resourceVersion,watch 按 revision 推进;
- 验证:第 3 章 lab 用向量时钟判定两个并发事件,第 2 章 lab 用一致性模型验证「写后立即读」与「滞后窗口」;
- 生产对照:回到 apiserver 的 watch 实现,看它如何把 resourceVersion 变成事件游标。
读完每卷你能做什么
每卷结束时的能力清单,既是学习目标也是验收标准:
| 卷 | 读完后你应该能 |
|---|---|
| 一 | 手绘 etcd 的写路径:leader 广播 → 多数确认 → 应用 mvcc;解释为什么 3 副本写要 2 个确认 |
| 二 | 讲清 list-watch 与 informer 缓存的关系;写出一个最小调谐循环的伪代码 |
| 三 | 解释调度器 Filter/Score 的先后与资源模型的量化口径 |
| 四 | 说出现有集群的一致性承诺在哪一层结束,边界为什么在那里 |
每张清单都能用对应 lab 的 45 个用例做抽查:随机挑一个机制,看你能不能不看正文说出它对应的 TestXxx 和断言。
三种读法与跳读路径
不一定从头读到尾,按你的目标挑一条路径:
- 顺序读:适合想建立完整体系的人。四卷从内核到边界推进,每节的四步循环保证你读完一卷就有完整心智模型。
- 从 lab 出发:适合想先动手的人。先跑
k8s-etcd-lab全量,再回到正文对照概念;lab 用例注释里的章节号就是跳转索引。 - 从生产场景出发:适合运维背景读者。先看每节末尾的「生产对照」段落,从你熟悉的故障现象逆推到机理,再回头补 lab。
三条路径共用同一份「挑战 × 机制 × 用例」索引(第 1.2 节末尾的速查表),无论从哪条路进来都能落到同一张地图上。
本节 lab
本节不跑新用例,只读 lab 的说明书。先打开 private/labs/k8s-etcd-lab/README.md,确认三件事:
- 模块划分:
consistency(第 2 章一致性模型:线性 / 顺序 / 最终一致 + CAP 分区)、clock(第 3 章时钟与顺序:Lamport、向量时钟、HLC)、raft(第 4–5 章共识与选举:集群结构、选举协议、选举限制、pre-vote)。README 还预告了后续批次:store/mvcc、watcher、lease。 - 运行方式:
go build ./... && go test ./...。 - 当前状态:三包 13 个用例全绿——
consistency3 个、clock3 个、raft7 个。
在本地复现全量状态:
cd private/labs/k8s-etcd-lab
go test ./...
模块名为 k8s-etcd-lab,go.mod 声明 go 1.26,工具链更新通常仍然兼容。期望输出是三包全部 ok。
从第 2 章起,每一节的 lab 都会在这三个包里找到自己对应的用例;卷末再回头看这 13 个用例,你会看到它们如何生长成覆盖本卷全部机制的 45 个用例。下一节就从第 2 章开始,先用 consistency 包的仿真器把 CAP 定理说精确。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。