封面与导览

分布式系统最容易写成两本错的书。

第一本错在只讲名词：CAP、BASE、最终一致、服务网格、云原生、可观测性，每一页都有新词，合上书却画不出一条请求的路径，也解释不了一次重复扣款。第二本错在只讲协议：Paxos 的两个阶段、Raft 的五个状态、2PC 的投票与提交都写对了，但读者不知道这些协议在业务代码里对应哪一行，也不知道超时该设 200 ms 还是 2 s。

这本书想写第三本：从一次具体的工具调用出发，沿着请求、复制、事务、消息、缓存和观测一路走，每到一个概念都问三件事——它解决什么失败、代价是什么、怎么观测。 协议是骨架，失败是血肉，观测是证据。

这本书的位置

它不是《Linux 系统与内核》的续集，也不是微服务名词表。它假设你已经知道 TCP 三次握手、socket、epoll、HTTP、DNS、TLS 的基本工作方式；这些内容在 Linux 书第 4 篇 已经讲过，本书只引用、不重写。容器与 Kubernetes 的基础同理，见 Linux 书第 5 篇。

本书只写数据面：请求怎么发、失败怎么判、状态怎么复制、事务怎么提交、消息怎么投递、缓存怎么失效、锁怎么过期、指标怎么解释、容量怎么估。控制面（调度、编排、服务发现、配置下发）只在必要时出现，而且从不展开成产品手册。

                  ┌──────────────────────────────────────────────┐
                  │  一次工具调用的数据面（本书主线）              │
                  └──────────────────────────────────────────────┘
   客户端            接入层              服务层                 状态层
  ┌────────┐      ┌────────┐        ┌────────────┐        ┌──────────────┐
  │ 重试   │─────▶│ 限流   │───────▶│ RPC/事务   │───────▶│ 复制日志     │
  │ 超时   │      │ 鉴权   │        │ 幂等键     │        │ 共识/选主    │
  │ 幂等键 │      │ 路由   │        │ 背压       │        │ MVCC/队列    │
  └────────┘      └────────┘        └────────────┘        └──────────────┘
       │                │                  │                     │
       └────────────────┴──────────────────┴─────────────────────┘
                    观测：trace / metrics / logs / replay

读这张图要抓住一个事实：同一份「一次调用」会在六个地方留下状态——客户端的内存、接入层的连接、服务端的请求上下文、数据库的事务、复制日志的位置、观测系统的 span。一次重复副作用，往往是其中两个状态对不上：客户端认为失败了，服务端已经提交了；服务端认为只执行了一次，复制日志里却有两条。

全书地图

每一章都按同一个骨架写：先给一条真实请求或一次真实故障，再拆机制，再给边界与观测命令，最后落到「如果你来实现，必须回答哪些问题」。章末有 8–15 条陷阱清单和出口检查；陷阱不是「注意安全」这种空话，而是「把 Retry-After 当建议、把超时当失败、把 RPO=0 当默认」这类会直接导致事故的判断。

两个项目

纸上的协议必须落到进程上。第 12、13 章是两个可运行的项目，代码在 projects/：

• 项目一 · 幂等工具调用后端：HTTP + SQLite，带幂等键、请求指纹、租约、崩溃恢复、丢响应故障注入。你会亲手制造「服务端成功了，客户端超时了」，再用同一个键重试，证明副作用只发生一次。
• 项目二 · 小型复制 KV：三个 Python 进程，简化 Raft 选举与日志复制，支持线性一致读、租约读和陈旧读；用分区脚本把主节点隔离，观察旧主如何被 fencing 挡住。

两个项目都只用 Python 标准库，python3 -m unittest 可跑，故障注入脚本 bash -n 通过，且不依赖 Docker 或云账号。它们不是玩具：每个不变量都有对应的测试，每个测试都对应正文的一节。

不做什么

• 不重写 TCP/IP、socket、epoll、HTTP/DNS/TLS；这些在 Linux 书第 4 篇。
• 不重写容器、Kubernetes 基础与云原生编排；这些在 Linux 书第 5 篇。
• 不把 CAP 当口号。第 4 章会给出可判定的定义、反例和检查方法；只喊「三者选二」的段落不会出现。
• 不把分布式写成微服务名词表。每个名词必须能落到一条请求路径、一个状态字段或一条观测命令。
• 不复制母本原文、代码或图。所有图由本书自绘，所有代码为本书编写，公开案例只引用事实与链接。

下一站：如果你想知道这本书为什么值得单独写，读 为什么写这本书；如果你要先确认自己是否准备好了，做 入学诊断。

为什么写这本书

1 一个真实的小事故

一个内部工具平台提供「发券」能力：客户端调用 POST /tool/issue-coupon，服务端写数据库、调下游发券、返回券号。某天网络抖动，客户端在 3 秒时超时；客户端 SDK 的重试策略是「超时重试 3 次，指数退避」。3 次重试都超时，用户看到失败，点了第二次「发放」。最后用户收到 4 张券，财务对账时才发现。

复盘时三个团队各说各话：

• 客户端团队说：「超时就是失败，失败当然要重试。」
• 服务端团队说：「请求都处理了，是网络没把响应带回去。」
• 下游团队说：「我们只保证至少一次，重复调用要上游去重。」

三方都没有说错，但三方合起来造出了一个重复副作用。这本书的第一章就从这件事开始，因为它是分布式系统最典型的形状：不是「机器坏了」，而是「成功与失败的边界在网络上变得不可判定」。

2 为什么现有的书不够用

市面上的分布式教材大致分三类。

第一类是协议教材：Paxos、Raft、2PC、线性一致性，证明写得很漂亮，但读者学完不知道 etcdctl get 的 --consistency=s 和 --consistency=l 差别在哪，也不知道为什么 Kubernetes 的 apiserver 会在 etcd 选举时抖动。

第二类是系统教材：讲 HDFS、Spark、Kafka、Dynamo 的架构，图很多，但代码离业务太远；读者能画出三层架构，却写不出一个带幂等键的接口。

第三类是工程手册：重试、熔断、限流、可观测性，条目很全，但缺少「为什么」——为什么指数退避要加抖动？为什么重试预算比重试次数更重要？为什么线性一致读在 Raft 里要走一次心跳？

这本书试图把三者接起来：协议给出保证，系统给出实现，工程给出边界。 每讲一个协议，都要回答「它在哪个失败模型下成立」；每讲一个工程手段，都要回答「它把哪一类失败转换成了哪一类失败」。

3 与四本母本的关系

本书的母本定位是四本书的组合，而不是任何一本的替代：

这张表说明一件事：本书的“新”不在底层协议，而在底层协议之上的失败处理与状态管理。 读者如果对 TCP 还不熟，应该先去补 Linux 书第 4 篇；如果已经熟，本书可以从第 1 章直接开始。

4 三个贯穿全书的问题

4.1 这次调用到底成功了吗

在单机上，函数返回就是成功，抛异常就是失败。跨进程之后，出现第三种状态：调用方不知道。请求可能没到、可能到了没执行、可能执行了没提交、可能提交了响应丢了。本书把「未知」当作一等状态，而不是把它硬塞进成功或失败。

第 1 章定义请求状态机，第 2 章把未知拆成超时与重试，第 12 章用一个可运行的服务证明：未知状态下，唯一安全的做法是让重试携带同一个幂等键，而不是让客户端「再发一次新请求」。

4.2 读到的值是最新的吗

复制带来延迟，延迟带来旧值。旧值不一定是错误——取决于你向读者承诺了什么。第 3 章讲复制拓扑，第 4 章把「线性一致、顺序一致、因果一致、最终一致」变成可判定的历史条件，第 13 章用三节点 KV 让你亲手制造陈旧读。

这里最容易被口号带偏的是 CAP。本书不会写「CAP 三者选二」就结束，而是给出：分区发生时，究竟是放弃线性一致还是放弃可用；PACELC 在无分区时又要求你在延迟与一致之间选什么；以及一个系统在什么条件下才算「满足线性一致」。

4.3 出故障时看什么

没有观测的分布式系统只能靠猜。第 10 章把 trace、指标、日志、回放拆成四种证据，并说明每种证据的盲区：trace 会漏采样，指标会丢标签，日志会重复，回放会放大副作用。第 11 章把观测接到容量与演练上：不是「看板好看」，而是「用一条命令判断是过载、是重试风暴，还是下游变慢」。

5 这本书的写法

• 先失败，后机制：每一节尽量从一个可复现的失败或一条真实请求开始，再解释机制。没有失败场景的协议段落，会被压缩或删除。
• 给边界，不给口号：不说「最终一致就够了」，而说「在什么业务下、允许多长时间的旧值、用什么读修复兜底」。
• 可执行：命令能复制运行，代码能编译/运行，脚本 bash -n 通过；不能运行的片段明确标为伪代码。
• 不复制：所有图自绘，所有代码自写；公开案例只引用事实、时间线和链接，不搬运原文。
• 可检查：每章有出口检查，全书有覆盖矩阵和 check_book.py。写得好不好可以争论，覆盖没覆盖、锚点有没有断，是机械可查的。

6 写给谁

• 写过 HTTP 服务、用过数据库，但一遇到「超时重试」「主从切换」「缓存不一致」就靠经验的后端工程师；
• 正在把单体拆成服务、需要给团队定 RPC 与数据一致性规范的架构师；
• 要做容量规划、故障演练、on-call 的 SRE；
• 想从「会调 API」走到「能解释实现」的学生。

不要求你会写 Raft，但要求你能读 Python；不要求你部署过 Kubernetes，但要求你知道 Pod 是什么。如果这些都不熟，先读 Linux 书的对应篇章，再回来。

下一站：范围、取舍与不重复清单——先把本书不写什么划清楚，后面的每一章才不会变成其他书的复述。

范围、取舍与不重复清单

1 本书的问题边界

本书讨论数据面（data plane）：一次请求从离开客户端到落盘/返回之间，数据怎么走、状态怎么变、失败怎么处理。控制面（control plane）只在必要处出现，因为控制面的错误最终也会以数据面的形式暴露——例如 etcd 选举抖动会变成 apiserver 的 5xx，Kubernetes 的滚动发布会被误读成「服务变慢」。

2 不重复清单（硬约束）

以下内容已经在《Linux 系统与内核》中完整讲过。本书只交叉引用，不重写；如果某章需要用到，最多用一两句话提醒，并给出链接。

3 深度取舍

3.1 协议：讲可判定的部分

Paxos 与 Raft 都讲，但重点不同：

• Paxos 讲安全性从哪来：为什么 prepare 的多数派与 accept 的多数派相交，就能保证只有一个值被选中；为什么活锁不是安全性问题。
• Raft 讲工程实现：term、选举超时、日志匹配、提交规则、ReadIndex、成员变更。因为项目二会实现一个简化版，读者需要能对着代码检查不变量。

不展开：Byzantine 共识、区块链共识、Paxos Made Live 的全部工程细节、Raft 的每一条形式化证明。

3.2 一致性：给判定方法，不给口号

本书用「历史」（history）来定义一致性：一组操作、它们的调用/返回时间、读到的值。线性一致要求存在一个全序，使得每个操作在其调用与返回之间生效，且读到的值符合这个全序。第 4 章会给正例、反例和检查方法（Jepsen 风格的 :ok / :fail 历史）。

不展开：形式化验证工具（TLA+、Coq）的教程；只给一个 TLA+ 风格的伪代码例子，说明「不变量」怎么写。

3.3 事务：单机原理 + 分布式协议

单机部分讲 MVCC 的版本可见性与隔离级别，因为这是理解「快照读」「写偏斜」的基础；分布式部分讲 2PC、TCC、Saga、Outbox，重点是失败路径：协调者挂了怎么办、参与者超时怎么办、重试怎么不重复。

不展开：某个数据库的完整锁系统、buffer pool、B+ 树实现；这些属于存储引擎教材。

3.4 工程：以可观测和可演练为终点

第 9–11 章不是「运维常识合集」，而是把前面所有机制接到三个问题上：

• 锁过期后，怎么保证资源不被两个持有者同时修改？——fencing token。
• 出事时，怎么在 5 分钟内判断是过载、依赖慢、还是重试风暴？——RED/USE + trace + 队列指标。
• 容量怎么估、怎么压、怎么演练？——Little’s law、利用率曲线、故障注入剧本。

4 版本与事实政策

• 协议事实以公开规范/论文为准，例如 Raft 论文、RFC、S3 一致性文档；产品行为标版本。
• 公开事故只写可核对的时间、影响和官方复盘结论；不写「据说」「网传」。
• 代码以 Python 3.11+ 标准库为准；不依赖第三方包，保证 python3 -m unittest 在干净环境可跑。
• 图表全部自绘；SVG 的 id 全书唯一，状态机与时序图必须能对应到正文的某个不变量。

5 淘汰与迁移

以下内容曾经常见于分布式教材，但本书不展开，原因如下：

下一站：符号、单位与代码约定——统一记号，避免后面把「延迟」「超时」「deadline」混着用。

符号、单位与代码约定

1 时间与延迟

分布式系统里最常见的错误是把不同层次的「时间」混为一谈。本书统一用下面的记号：

规则一：D > T 只说明客户端不再等待，不说明服务端没执行。本书把前者叫「超时」，把后者叫「失败」；两者不是同义词。

规则二：所有 deadline 都用绝对时间在进程间传递，不用「剩余多少毫秒」。原因很简单：剩余时间在每一跳都会因为排队而变短，接收方无法判断发送方已经等了多久。

规则三：不要把墙上时钟（wall clock）用于计算超时或顺序。墙上时钟会被 NTP 调整，可能倒退；超时用单调时钟（time.monotonic() / CLOCK_MONOTONIC）。

2 失败模型

本书只用三种失败模型，出现更复杂的模型会明确标注：

默认模型是 C-R + N：节点会崩溃重启，网络会分区、会重复、会乱序，但节点不会伪造消息。凡是依赖「消息一定到达」「时钟一定同步」「节点不会同时暂停」的结论，都会在正文里标出假设。

3 请求与状态

unknown 是本书特别强调的状态：它表示「客户端不知道服务端是否执行」。在 UI 上它通常被折叠成「失败」，在协议上它必须被单独处理。

4 一致性与事务

注意：W + R > N 只保证「读到的集合与写入的集合相交」，不自动保证线性一致。第 4 章会说明还需要哪些条件（写必须是最新已提交、读必须等待修复、不能有脏读等）。本书不会把 quorum 相交当成线性一致的充分条件。

5 代码约定

• 语言：Python 3.11+，只用标准库（http.server、sqlite3、threading、urllib、unittest、json、hashlib、time）。
• 服务端口默认 127.0.0.1，避免暴露到公网；测试用临时端口。
• 每个代码块标注语言：python、bash、sql、json、text、http。
• 伪代码用 text，不要伪装成可运行代码。
• 错误处理不能省：捕获具体异常，记录 request_id，返回结构化错误。
• 脚本开头 set -euo pipefail；需要 root 的命令前标 sudo 并给清理命令。
• 不把长代码墙贴进正文：核心函数 20–80 行，完整文件放 projects/，正文给路径和行号。

6 锚点与交叉引用

本书的锚点采用统一命名：

sec-distributed.<part>.<chapter>.<section>     小节
def-distributed.<part>.<chapter>.<n>           定义
thm-distributed.<part>.<chapter>.<n>           定理/保证
ex-distributed.<part>.<chapter>.<n>            案例/练习
method-distributed.<part>.<chapter>.<n>        方法/清单
errata-distributed.<part>.<chapter>.<n>        误解/陷阱
note-distributed.<part>.<chapter>.<n>          边注

<part> 是篇号 1–5，<chapter> 是全书章号 1–13。例如第 5 章（第 2 篇）第 3 节的锚点是 sec-distributed.2.5.3。这样即使章节在篇内移动，锚点仍然可读；所有锚点由 tools/check_book.py 检查唯一性。

7 代码清单的读法

书中出现下面这种清单时，表示「这段代码在仓库里的位置」：

projects/idempotent-tool/server.py
  ├─ class CallStore        持久化与状态迁移
  ├─ class ToolRunner       工具执行与副作用
  └─ class Handler          HTTP 契约

路径相对于本书根目录 distributed/。运行命令默认也在该目录下执行。

下一站：实验环境——把端口、依赖和清理命令一次配好。

实验环境与复现方式

1 最低配置

两个项目不需要 Docker、Kubernetes、Redis、Kafka 或云账号。原因不是这些系统不重要，而是本书想让你先看清「重复、超时、分区」的最小机制；真实系统只是在同样的机制上加了更多优化。

2 目录

distributed/
├── book.toml
├── src/                     正文与图
├── projects/
│   ├── idempotent-tool/     项目一：幂等工具调用后端
│   └── replicated-kv/       项目二：三节点复制 KV
├── tools/                   mathbook / check_book / check_coverage / check_projects
├── coverage.md              覆盖矩阵（与 src/appendix/coverage.md 同源）
├── CHECK-distributed.md     交付自检报告
└── README.md

3 构建本书

cd distributed
mdbook build .
# 产物在 book/；打开 book/index.html

本地预览：

mdbook serve --open
# 默认 http://127.0.0.1:3000/

构建依赖：

pip3 install -r requirements.txt     # markdown-it-py，供 mathbook 预处理器使用
cargo install mdbook-katex --version 0.10.0

质检：

python3 tools/check_book.py          # 结构、锚点、链接、盒子、行数
python3 tools/check_coverage.py      # 覆盖矩阵 0 缺口
python3 tools/check_projects.py      # py_compile + bash -n

4 运行项目一

cd projects/idempotent-tool
python3 server.py --port 8081 --db /tmp/idem.db
# 另开一个终端
python3 client.py --base http://127.0.0.1:8081 --key demo-1 --tool charge --amount 100

预期：

{"call_id":"...","status":"succeeded","effect_id":"...","attempts":1}

同一把钥匙再发一次，返回同一个 call_id，attempts 不增加；换一把钥匙、同参数，得到新的 call_id——这两句话是项目一的核心验收。

完整测试：

python3 -m unittest -v test_server.py
bash fault_inject.sh --dry-run
bash fault_inject.sh --drop-response

5 运行项目二

cd projects/replicated-kv
./run_cluster.sh start          # 启动 3 个节点：7101/7102/7103
python3 kv_client.py status
python3 kv_client.py --key k --value v put
python3 kv_client.py --key k --consistency linearizable get

故障注入：

bash fault_inject.sh --dry-run
bash fault_inject.sh --partition 1          # 隔离节点 1，观察重新选主
bash fault_inject.sh --heal
bash fault_inject.sh --kill-leader

完整测试：

python3 -m unittest -v test_kv.py

6 端口与清理

端口冲突时，两个服务都支持 --port/--base-port；测试使用 --port 0 让内核分配临时端口。

7 非 root 与 root 的边界

• 项目一、项目二、python3 -m unittest 都不需要 root。
• fault_inject.sh 的 --partition 通过服务内置的 /admin/partition 接口实现，不需要 iptables；这样在 macOS 和 CI 里都能跑。
• 只有 tc netem 的丢包/延迟实验需要 root；脚本会先检查 id -u，不是 root 时打印替代命令并退出 0（--dry-run 永远 0）。
• 不要在生产机器上跑 tc/iptables 实验；用容器或虚拟机。

8 版本与可复现性

书中所有「实测输出」都来自以下环境之一：

macOS 15.6 / Apple Silicon / Python 3.13.13 / SQLite 3.50.x
Ubuntu 24.04 / x86-64 / Python 3.12.x / SQLite 3.45.x

端口、PID、时间戳、随机数会不同；结构化的字段名、状态迁移、错误码应当一致。如果你的输出在字段层面不同，先检查版本，再检查是否用了 --db 指向旧库。

下一站：三条阅读路线——按你的目标选择顺序，不必从第一页读到最后一页。

三条阅读路线

这本书有 13 章，但不需要按 1 到 13 顺序读完。下面三条路线对应三类目标；每条路线都标了「必须做」的练习，不做练习等于没读。

1 后端工程师：把一次调用写对

目标：能给团队定一份 RPC 契约，遇到超时、重试、重复、过载时知道先看什么。

时间：约 12–16 小时，其中项目一 4–6 小时。

2 SRE / 平台工程师：把故障看清楚

目标：能在 5 分钟内判断「过载、依赖慢、重试风暴、分区」中的哪一种，并能设计一次低风险演练。

时间：约 10–14 小时，其中观测改造 3–5 小时。

3 存储 / 基础设施工程师：把一致性讲清楚

目标：能判断一个系统声称的一致性是否成立，能读懂 Raft 实现的关键不变量。

时间：约 16–20 小时，其中项目二 6–8 小时。

4 章节依赖图

        1 请求/失败
         │
    ┌────┴────┐
    ▼         ▼
 2 RPC      3 复制 ──▶ 4 一致性 ──▶ 5 共识
    │         │                         │
    │         └──────────┬──────────────┘
    ▼                    ▼
 6 事务 ◀──────────── 7 队列/流
    │                    │
    └────────┬───────────┘
             ▼
        8 缓存/CDN
             │
    ┌────────┴────────┐
    ▼                 ▼
 9 锁/租约         10 观测
    │                 │
    └────────┬────────┘
             ▼
        11 容量/演练
             │
    ┌────────┴────────┐
    ▼                 ▼
 12 项目一         13 项目二

实线箭头表示「读后者之前最好先读前者」；虚线不存在——本书没有必须按顺序读的硬依赖，只有概念上的前后关系。第 10 章可以在读完第 2 章后直接读；第 12 章可以在读完第 2、6 章后直接做。

5 三条路线的共同底线

无论选哪条路线，下面五件事必须做，否则这本书对你只是「读过」：

1. 亲手制造一次超时但成功，并用幂等键重试；
2. 亲手制造一次重复投递，观察副作用是否翻倍；
3. 亲手制造一次分区/旧主，观察读到的值；
4. 用一条命令判断一次过载（不是看 CPU，而是看队列与延迟）；
5. 写一份故障演练剧本，包含假设、爆炸半径、回滚和观测点。

下一站：能力矩阵——把「读完」变成可自评的 24 项能力。

能力矩阵

1 怎么用这张表

24 项能力分四组：判断（能不能识别问题）、设计（能不能写出契约）、实现（能不能落代码）、验证（能不能证明它有效）。每项给一个可观察的达标线；达不到就回到对应章节，不要用「大概懂了」糊过去。

自评等级：

• 0 没听说过；
• 1 能复述定义；
• 2 能在给定场景下选对方案；
• 3 能写出实现并解释失败路径；
• 4 能设计验证实验并读出证据。

本书的目标不是让所有读者都到 4；第 2 篇到 3、第 5 篇到 3 是合理目标，负责 on-call 的读者应在第 9–11 章到 4。

2 判断

3 设计

4 实现

5 验证

6 三条路线的达标组合

下一站：入学诊断——12 道题，测一测你现在处于哪一档。

入学诊断

12 道题，覆盖本书的六个核心概念。不要查资料，15 分钟内做完；答案在最后，先记下你的选择。

1 题目

Q1 客户端设置 1 s 超时，1 s 后收到 timeout。服务端最可能处于什么状态？

A. 一定没收到请求　B. 一定执行成功　C. 可能没收到、可能执行中、可能已成功　D. 一定执行失败

Q2 一个客户端对每个请求重试 3 次，失败后上游再重试 3 次。最坏情况下游收到多少次请求？

A. 3　B. 4　C. 9　D. 16

Q3 三副本，W=2, R=2，是否一定满足线性一致？

A. 一定　B. 只在没有并发写时　C. 不一定，还要看读修复、写确认与时钟/排序规则　D. 只要 R+W>N 就一定

Q4 下面哪种历史违反线性一致？设写 x=1 在 t1 返回，读在 t2 开始且 t2 > t1。

A. 读返回 1　B. 读返回 0　C. 读超时　D. 读返回 1 但来自从库

Q5 Raft 中，leader 能把 commitIndex 推进到某个日志项的条件是：

A. 本地写入磁盘　B. 多数派复制了该项，且该项属于当前 term（或通过当前 term 的项间接提交）　C. 所有 follower 都复制了　D. 客户端收到 ACK

Q6 PostgreSQL 的 READ COMMITTED 能防止下列哪个异常？

A. 脏读　B. 不可重复读　C. 幻读　D. 写偏斜

Q7 Kafka 的「至少一次」语义下，重复最可能来自：

A. 生产者发送前　B. 消费者处理成功但 offset 提交失败/再平衡　C. broker 落盘　D. 分区数太多

Q8 缓存旁路（cache-aside）下，最危险的旧值路径是：

A. 缓存命中　B. 先更新数据库、后删除缓存，但删除失败　C. 缓存 TTL 太长　D. 缓存容量太小

Q9 SET lock:key value NX PX 30000 的锁，在下列哪种情况下可能被两个客户端同时持有？

A. Redis 重启　B. 客户端 GC 停顿超过 30 s，锁过期后被另一个客户端获取　C. 网络延迟 1 ms　D. 使用 Lua 解锁

Q10 一个服务的 p50 是 20 ms，p99 是 2 s。最应该先看什么？

A. 平均延迟　B. 慢请求的 trace 与下游分位　C. CPU 使用率　D. 日志条数

Q11 系统利用率从 60% 升到 85%，延迟通常会：

A. 线性上升 1.4 倍　B. 基本不变　C. 非线性上升，排队时间显著变长　D. 下降

Q12 故障演练中，「爆炸半径」指的是：

A. 故障注入脚本的行数　B. 一次演练可能影响的最大用户/数据/服务范围　C. 告警条数　D. 恢复时间

2 答案与解释

3 评分

下一站：准备好了就从 第 1 章 开始；想先看全书结构，回到 封面与导览。

1 从一次工具调用到分布式请求

一个内部工具平台提供「发券」能力。客户端调用 POST /tool/issue-coupon，服务端做三件事：在数据库里写一条发券记录、调用下游券系统、把券号返回给客户端。某天网络抖动，客户端在 3 秒时超时；SDK 的重试策略是「超时重试 3 次，指数退避」。三次重试都超时，用户看到「发放失败」，又点了一次。最后用户收到 4 张券。

这个事故里没有哪台机器真正宕机，也没有哪段代码写错。三方的行为单独看都合理：

• 客户端：「超时就是失败，失败当然要重试。」
• 服务端：「每个请求我都处理了，是网络没把响应带回去。」
• 下游：「我们只保证至少一次，重复调用要上游去重。」

把三句话放在一起，重复副作用就出现了。分布式系统的很多故障不是「组件坏了」，而是「组件对同一个事实的理解不一致」：客户端认为失败，服务端认为成功，下游认为被调用了两次。本章要做的，就是把这三种理解拆开，落到一条请求路径、一个状态机和一个契约上。

这一章是全书的地基。后面的 RPC、复制、一致性、事务、队列、缓存、锁、观测、容量，都会反复回到本章的三个问题：这次调用成功了吗？读到的值是最新的吗？出事时看什么？先把这三个问题的语言统一，后面才不会各说各话。

1.1 一次工具调用的十二个 hop

先看一条具体的路径。假设客户端在浏览器里点「发放」，请求最终到达工具服务的 /v1/tool-calls：

图上的五个方框只是粗粒度。把一次调用拆细，至少经过下面十二个 hop。每一个 hop 都有自己的队列、超时和失败模式；把它们列全，是为了知道「延迟到底花在哪」以及「失败到底发生在哪」。

这张表至少说明三件事。

第一，延迟不是一个数，而是一条分布。 同一段代码在不同负载下，hop 5 和 hop 7 可以从 0 ms 变成 500 ms。你在监控上看到的 p99，往往是某个 hop 的排队时间，而不是「服务处理慢」。

第二，失败不是一个点，而是一条链。 客户端看到的是 hop 11 的「响应没回来」，但根因可能在 hop 7 的线程池、hop 10 的锁等待，甚至 hop 4 的一次丢包。只看客户端错误码，等于只看最后一环。

第三，重试会改变路径，而不是回到原点。 第二次尝试可能命中另一个实例、另一个可用区、另一个连接；它可能绕过第一次已经完成的副作用，也可能在同一张表上再写一次。重试不是「再试一次」，而是「再产生一次请求」。

这个区分看起来只是命名，实际决定了接口设计。很多系统的请求体里没有 client_id/seq，服务端只能按「每次 HTTP 请求」计数；客户端一重试，服务端就多一条记录。没有逻辑请求 ID，就没有去重的锚点。

一个常见的反例是「用数据库自增 ID 当请求 ID」：自增 ID 是服务端生成的，第二次尝试会拿到新的 ID，服务端无法知道它和第一次是同一个意图。正确的做法是客户端在第一次发送前就生成键，并在所有重试中复用它。

{
  "client_id": "tool-console-7f3a",
  "seq": 1842,
  "idempotency_key": "tool-console-7f3a:1842",
  "tool": "issue_coupon",
  "args": {"user_id": "u-1024", "amount": 100},
  "deadline_ms": 3000
}

seq 是客户端本地的单调序号，用来防止「同一个键被不同请求复用」。服务端应当把 (client_id, seq) 和 idempotency_key 都存下来：前者用于审计，后者用于去重；两者不一致时，按冲突处理，而不是猜。

1.2 本地调用与远程调用的七个差异

本地函数调用和远程调用看起来都是「传参、执行、返回」，但至少有七个本质差异。理解这七个差异，比背会 gRPC 的四种调用方式更有用。

1.2.1 延迟：长尾不是异常，是常态

本地调用的 p99 可能是 p50 的 2 倍；跨网络的 p99 可能是 p50 的 20 倍。原因不神秘：一次远程调用要经过多跳队列，任何一跳的尾部都会叠加到总延迟上。第 1.4 节会把延迟拆开算；这里先记住一个结论：同步调用链越长，p99 越接近「最慢那一跳的 p99 之和」。

1.2.2 失败：从二元到三元

本地调用要么返回，要么抛异常；即使崩溃，调用方也通常能通过进程状态知道「没执行完」。远程调用多出第三种状态：请求可能已经到达并执行，但响应在回程丢失。调用方既不能当成功，也不能当失败。

很多 SDK 把这种状态映射成 TimeoutException，然后在上层被当成失败重试。这是本书反复强调的头号错误：超时是「本地不再等待」，不是「远端没有执行」。

1.2.3 内存：不能共享，只能复制

本地调用可以把一个大对象传进去，函数内部修改它，调用方立刻看到。远程调用必须把对象序列化成字节，接收方反序列化出一份副本；两边修改互不可见。这带来三个问题：

• 大对象传输成本高，可能触发序列化/反序列化的 CPU 尖峰；
• 结构变更需要版本兼容，旧客户端可能不认识新字段；
• 不能把「锁」放在调用方，必须把并发控制放到服务端或存储层。

1.2.4 数据：序列化不是免费的

JSON 可读但体积大；Protobuf 紧凑但有 schema 演进规则；Thrift、Avro、MessagePack 各有取舍。序列化层最容易被忽略的失败是兼容性：新增必填字段、修改枚举值、删除字段后复用编号，都会让旧客户端在新服务端上失败。第 2 章会把「契约」单独列一节。

1.2.5 并发：多实例让「顺序」消失

本地调用通常只有一个进程，锁和队列可以保证顺序。远程调用可能落到多个实例、多个副本，甚至多个地域。没有全局队列，就没有全局顺序；要么把顺序收敛到单个分区/单个 leader，要么让操作可交换（幂等、CRDT）。

1.2.6 边界：信任模型变了

本地调用默认「调用方和被调用方在同一个信任域」。远程调用跨进程、跨主机、跨租户，必须考虑鉴权、重放、注入、限流。一个典型的错误是「内网调用不加鉴权」：内网也会被横向移动，攻击者可以伪造请求。

1.2.7 时钟：时间戳不是顺序

两台机器的墙上时钟可能差几毫秒到几秒，NTP 调整还可能让时钟倒退。用 time.time() 给请求排序，在跨机器时不可靠；用单调时钟算超时，用逻辑时钟/版本号定序。第 4 章会讲线性一致为什么不能靠「谁的时间戳大」。

1.2.8 一个对照实验：把本地调用改成远程调用

把下面的函数从本地调用改成 HTTP 调用，观察失败语义怎么变：

# 本地版本：调用方能看到异常，也能确定函数是否返回
def issue_coupon_local(user_id: str) -> str:
    record = db.insert_coupon(user_id)   # 副作用
    return record.coupon_id

# 远程版本：调用方只能看到 HTTP 结果或超时
def issue_coupon_remote(user_id: str, key: str) -> str:
    resp = http.post("/v1/coupons", json={"user_id": user_id},
                     headers={"Idempotency-Key": key}, timeout=1.0)
    return resp.json()["coupon_id"]

本地版本里，如果 db.insert_coupon 成功但后续代码抛异常，调用方至少知道「异常发生在我可控的栈里」，可以查数据库。远程版本里，超时可能发生在服务端写库之前、之后、或者响应回程；调用方的栈里没有任何服务端状态。

这个对照实验说明：远程调用不是「加一个 HTTP 客户端」那么简单，它把错误处理从「异常捕获」变成了「状态收敛」。

1.3 请求状态机：unknown 为什么必须单独存在

把一次逻辑请求的状态画出来，会得到下面这张图：

图中最重要的是 unknown。它不是「失败」的同义词，也不是「成功」的模糊态，而是一个需要额外动作才能离开的状态：查询服务端、用同一个键重试、或者等待对账。

为什么不能把 unknown 折成 failed？因为两者的安全动作不同：

这张表是第 12 章项目一的全部设计基础。项目里的 calls 表会有 status、lease_until、attempts、effect_id 四个字段，分别对应「状态机」「租约」「尝试次数」「副作用幂等 ID」。

一个可运行的 Python 状态迁移检查器长这样：

from enum import Enum

class State(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    SUCCEEDED = "succeeded"
    FAILED = "failed"
    UNKNOWN = "unknown"

ALLOWED = {
    State.PENDING: {State.RUNNING, State.FAILED},
    State.RUNNING: {State.SUCCEEDED, State.FAILED, State.UNKNOWN},
    State.UNKNOWN: {State.SUCCEEDED, State.FAILED, State.RUNNING},
    State.SUCCEEDED: set(),
    State.FAILED: {State.RUNNING},   # 只允许同键重试
}

def transition(cur: State, nxt: State) -> State:
    if nxt not in ALLOWED[cur]:
        raise ValueError(f"illegal transition: {cur} -> {nxt}")
    return nxt

这段代码的关键不在 ALLOWED 表，而在 FAILED -> RUNNING 只允许同键重试。如果调用方换了一个新键，服务端会创建一条新记录，状态机无法阻止重复副作用；状态机只能约束「同一次逻辑请求」，不能约束「用户又点了一次」。后者需要业务层的去重键（例如「用户 + 券模板 + 活动 + 时间窗」），第 12 章会展开。

1.3.2 unknown 的三种收敛路径

unknown 不能一直悬着。工程上有三条收敛路径，各有代价：

客户端                服务端                 存储
  │  GET /calls/K1      │                     │
  ├────────────────────▶│ 查 calls by key     │
  │                     ├────────────────────▶│
  │  200 succeeded      │                     │
  │◀────────────────────┤                     │
  │                     │                     │
  │  POST /calls (K1)   │                     │
  ├────────────────────▶│ 命中幂等记录         │
  │  200 succeeded      │ 直接返回原结果        │
  │◀────────────────────┤                     │
  │                     │                     │
  │  等待/对账            │ 异步 worker 扫描      │
  │                     │ running 超租约 → 重试 │

三条路径可以组合：先查询，查不到再同键重试；异步任务则靠 worker 扫描租约过期的记录。关键是不要用「换新键重发」来收敛 unknown——那等于放弃身份。

1.4 延迟预算：p50 骗人，p99 决定体验

假设一个接口的延迟分布如下：

如果只看 p50，你会觉得「80 ms 很快」；但对一个每天 1 亿次调用的接口，p99 意味着每天有 100 万次请求超过 1.2 秒。用户感知的是他这一次的延迟，不是平均值。

更麻烦的是，p99 会被调用链放大。一个请求要串行调用 10 个服务，每个服务独立地有 1% 的概率超过 1 秒，那么至少一个服务超 1 秒的概率是：

$$P(\text{slow}) = 1 - (1 - 0.01)^{10} \approx 9.6$$

也就是说，单服务 p99 是 1 秒，端到端 p90 左右就可能超过 1 秒。这就是「长尾放大」（tail amplification）。第 2 章的对冲请求（hedged request）和第 11 章的容量规划都会回到这个公式。

1.4.1 把预算按 hop 切开

假设产品要求端到端 p99 ≤ 1 s。你不能给每个 hop 都设 1 s 超时——那样最坏情况会叠加成 12 s。正确做法是先留余量，再按 hop 分配：

这张表是预算，不是 SLA。每个 hop 的实际超时应比预算略小（例如 80%），这样上游还有时间做降级；如果每个 hop 都等到预算上限，端到端一定超。

1.4.2 deadline 不是 timeout

timeout 是「我愿意等多久」，deadline 是「这个请求最晚必须在什么时候完成」。两者在单跳里看起来一样，在多跳里差别巨大：

• 服务 A 收到请求时已经过了 200 ms，它给服务 B 的剩余预算应该 deadline - now，而不是重新给 1 s；
• 如果 A 给 B 重新 1 s，B 可能执行到第 1.1 s，A 早已超时返回，B 的副作用却发生了；
• 如果 A 把绝对 deadline 传给 B，B 会在剩余预算内尽快失败，减少无效执行。

Python 里的绝对 deadline：

import time

class Deadline:
    def __init__(self, budget_ms: int):
        self._end = time.monotonic() + budget_ms / 1000.0

    def remaining_ms(self) -> int:
        return max(0, int((self._end - time.monotonic()) * 1000))

    def expired(self) -> bool:
        return self.remaining_ms() == 0

跨进程传递时，不要传 remaining_ms，也不要用墙上时钟；传「剩余预算」会在每一跳被重新解释，传墙上时钟会受 NTP 影响。工程上的折中是：在 RPC header 里传 grpc-timeout（相对时间），由每一跳在接收时立刻换算成本地单调时钟的 deadline；或者传 x-request-deadline-ms 并在网关做一次校准。两者都要在契约里写清楚「谁负责换算」。

1.4.3 一个排队算例：为什么 70% 就开始抖

假设一个服务有 10 个工作线程，每个请求平均处理 10 ms，服务率 μ = 100 req/s，到达率 λ = 90 req/s。利用率：

$$\rho = \frac{\lambda}{\mu} = 0.9$$

用最简单的 M/M/1 近似（单队列、单服务台；多线程时用 M/M/c，趋势相同），平均停留时间：

$$W = \frac{1}{\mu - \lambda} = \frac{1}{100 - 90} = 0.1\ \text{s} = 100\ \text{ms}$$

也就是说，处理时间只有 10 ms，但排队让平均停留时间变成 100 ms。把利用率再提高：

这张表说明：容量不是「CPU 没满就能扛」，而是「排队时间是否还能接受」。当利用率到 90%，一次 10% 的流量突增就会把 ρ 推到 0.99，延迟放大 10 倍；如果重试再增加 10% 流量，系统直接进入正反馈。第 11 章会把这条曲线和重试风暴接起来。

1.5 部分失败：超时只是其中一种

分布式系统里的「失败」至少有七种。把它们混成一种，就会用错恢复手段。

本书默认不处理拜占庭失败（除了第 5 章提一句），因为大多数数据面系统的信任模型是「节点不会伪造消息」，但会崩溃、会暂停、会丢包。

1.5.1 失败检测器不完美

「节点挂了」这件事本身就不是可判定的。你只能根据心跳超时推测它挂了；但对方可能只是 GC 停顿、网络抖动、或者 CPU 被抢占。任何基于超时的失败检测都会产生假阳性：把慢节点判死，触发主从切换，然后旧主恢复，出现双主。

这就是为什么第 3 章要讲 fencing、第 9 章要讲租约、第 5 章要讲 quorum：不要把「检测到失败」当成「失败已确认」。检测只是触发动作的信号，动作本身必须满足安全性（不会因为误判而产生两个写者）。

1.5.2 失败的处理顺序

遇到一次失败，正确的处理顺序是：

1. 分类：是确定没执行、确定失败、还是 unknown？
2. 收敛：unknown 先查询/同键重试，不要换键；
3. 隔离：把故障实例从负载均衡里摘掉，避免重试继续打到它；
4. 降级：如果依赖不可用，返回缓存/默认值/排队，而不是无限重试；
5. 观测：记录 request_id、attempt、状态迁移，供事后对账。

这个顺序不能反。很多事故的根因不是「第一次失败」，而是「失败后立刻重试，重试把故障扩散到整个集群」。

请求失败
├─ 有明确错误码且语义为「未执行」 → failed → 可换实例重试（同键）
├─ 有明确错误码且语义为「已拒绝」 → failed → 不重试，返回用户
├─ 超时/连接断开/5xx 无体 → unknown → 查询状态；查不到则同键重试
└─ 重试预算耗尽 → 返回 503 + Retry-After，交给上游/用户

1.5.3 心跳检测：为什么「假阳性」不可避免

故障检测器通常用心跳实现：

import time

class HeartbeatDetector:
    def __init__(self, timeout_s: float = 3.0):
        self.timeout_s = timeout_s
        self.last_seen = {}          # node -> monotonic timestamp

    def observe(self, node: str) -> None:
        self.last_seen[node] = time.monotonic()

    def alive(self, node: str) -> bool:
        seen = self.last_seen.get(node)
        return seen is not None and time.monotonic() - seen < self.timeout_s

这段代码能用，但它有三个无法消除的误差来源：

• 网络延迟：心跳在队列里排了 3.1 s，节点本身活着，却被判死；
• GC/STW：进程暂停 2 s，心跳线程没运行，发送方看到的是「没心跳」；
• 调度：容器被 CPU 限流，心跳线程抢不到时间片。

所以任何基于超时的心跳都会产生假阳性（把活节点判死）和假阴性（把死节点判活，直到超时）。工程上不是追求「检测准确」，而是让「误判的后果可控」：

第 3 章的分区、第 5 章的选举、第 9 章的租约，都是围绕「误判之后怎么不产生两个写者」设计的。心跳只能触发怀疑，不能证明死亡；这是分布式系统里最贵的一课。

1.6 失败模式：超时后的三种真相

现在把镜头拉近到一次超时。客户端在 T = 1 s 返回 timeout，服务端可能处于三种状态：

第一种：请求没到。 报文在网络上丢了，或者连接根本没建立。服务端没有任何记录，客户端重试是安全的（但仍应复用同一个键，避免「第一次其实到了、只是响应丢了」的边界情况）。

第二种：执行了，响应丢了。 服务端完成了副作用，但在返回路径上连接被重置、代理超时、客户端进程被 kill。服务端有记录，客户端不知道。此时换新键重试会重复执行；同键重试会被去重。

第三种：执行并提交，响应丢了。 服务端不仅执行了，还把结果写进了数据库/下游。这是最危险的一种，因为「补偿」也可能重复。此时唯一安全的做法是：用同一个键查询/重试，让服务端返回已提交的结果。

三种真相在客户端看来完全一样：都是 timeout。这就是为什么「超时」不能作为重试的充分条件。重试可以发生，但必须带上能让服务端识别「这是同一个逻辑请求」的键。

1.6.1 服务端应该返回什么

面对不确定的执行结果，服务端有三种返回策略：

没有一种策略适合所有场景。发券、支付这类有副作用的操作，通常选「异步受理 + 可查询」；纯读操作可以同步等待；过载时快速失败并明确「未执行」。关键是返回体里要能区分「已执行」「未执行」「未知」，而不是把所有失败都塞进 500。

一个可用的响应契约：

{
  "call_id": "c-9f2a",
  "status": "unknown",
  "attempt": 2,
  "retry_after_ms": 500,
  "query_url": "/v1/tool-calls/c-9f2a"
}

status 是服务端对逻辑请求状态的判断，不是 HTTP 状态码的复述。HTTP 200 + status=unknown 是合法的：请求被受理了，但执行结果还没确定。客户端不应看到 200 就认为成功，也不应看到 unknown 就换键重发。

1.7 重试如何把一次调用变成两次副作用

重试的数学很简单，后果却不简单。假设一个客户端对每次请求最多重试 3 次，上游网关又对失败请求重试 3 次。最坏情况下，下游收到：

$$(1 + 3) \times (1 + 3) = 16$$

次请求。如果下游每次都会发一张券，用户就可能收到 16 张。重试是有成本的，而且成本按层数指数放大。

更隐蔽的是，重试不一定发生在「失败」之后。很多 SDK 的超时重试逻辑是：

def call_with_retry(fn, retries=3):
    for attempt in range(retries + 1):
        try:
            return fn()                 # 超时抛 TimeoutError
        except TimeoutError:
            if attempt == retries:
                raise
            time.sleep(2 ** attempt)    # 1s, 2s, 4s

这段代码把 TimeoutError 当成「确定失败」，但超时只说明本地不再等待。第二次 fn() 会重新生成请求 ID、重新走一遍完整路径；服务端看到的是一个新请求。

一个最朴素的修复是「重试时复用同一个请求 ID」：

def call_with_idempotency(fn, key: str, retries=3):
    for attempt in range(retries + 1):
        try:
            return fn(idempotency_key=key)   # 服务端按 key 去重
        except TimeoutError:
            if attempt == retries:
                raise
            time.sleep((2 ** attempt) * 0.1 + random.random() * 0.05)

注意这里加了抖动（jitter）。没有抖动，所有客户端会在同一时刻重试，形成「重试风暴」；第 2.3 节会给出完整的退避公式。

1.7.1 一个重复副作用的完整链路

把发券事故拆成时间线：

事故的根因不是某一个时刻，而是「重试键在中途变了」：t3 还在用 K1，t4 却换成了 K2。只要键不变，服务端就有机会把 t4 识别为同一个逻辑请求；键一变，任何去重表都无能为力。

1.7.2 为什么「最多重试 3 次」不是保护

「3 次」限制的是单个客户端的尝试次数，不是系统的总请求量。考虑 1 万个客户端同时超时：

• 每个客户端重试 3 次，瞬间多出 3 万个请求；
• 服务端本来就慢，多出的请求让它更慢；
• 更多客户端超时，触发更多重试；
• 最终形成正反馈，直到服务端完全不可用。

这就是重试风暴。防护手段不是「把 3 改成 1」，而是：

• 重试预算：重试请求量不得超过原始请求量的一定比例（例如 10%）；
• 退避 + 抖动：把重试摊开，避免同步；
• 熔断：下游错误率超过阈值时，直接失败一段时间，不再重试；
• 幂等：即使重试到达，也不产生额外副作用。

一个最小的重试预算实现：

import random, time

class RetryBudget:
    def __init__(self, ratio: float = 0.1, min_tokens: int = 10):
        self.ratio = ratio
        self.tokens = float(min_tokens)
        self.last = time.monotonic()

    def _refill(self, requests: int) -> None:
        now = time.monotonic()
        self.tokens = min(self.tokens + requests * self.ratio * (now - self.last), 1000)
        self.last = now

    def allow(self, requests: int = 1) -> bool:
        self._refill(requests)
        if self.tokens >= 1:
            self.tokens -= 1
            return True
        return False

    def backoff(self, attempt: int) -> float:
        return min(2 ** attempt * 0.1, 2.0) * (0.5 + random.random())

这里的 tokens 以「原始请求量 × ratio」补充，重试消耗 token；预算耗尽直接失败。第 2 章会把这段扩展成带 Retry-After 和服务端反馈的版本。

第 2 章和第 11 章会分别从协议和容量角度展开。

1.8 观测：用 curl -w 与 trace id 切开延迟

在讨论更多机制之前，先学会看一次请求。curl -w 可以把一次 HTTP 调用拆成多个阶段：

curl -sS -o /dev/null \
  -w 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} \
ttfb=%{time_starttransfer} total=%{time_total} code=%{http_code}\n' \
  http://127.0.0.1:8081/v1/tool-calls/c-9f2a

一次本机测试的输出：

dns=0.000021 connect=0.000312 tls=0.000000 ttfb=0.004812 total=0.004901 code=200

怎么读：

注意：time_connect 包含 time_namelookup，time_starttransfer 包含前面所有阶段。不要把它们相加。这个细节和 TCP 握手本身无关，属于 curl 的计时定义；TCP 状态机、握手细节见 Linux 书 4.5，本书不重写。

如果 TTFB 高、time_connect 正常，问题通常在服务端排队或下游；如果 time_connect 高，先查连接池、DNS、网络，而不是业务代码。

1.8.1 trace id：把客户端和服务端串起来

curl 只能看到客户端视角。要知道服务端把时间花在哪，需要 trace id。最小实现是在请求头里带一个 ID，并在每一层日志里打印：

TRACE_ID=$(python3 -c 'import uuid; print(uuid.uuid4().hex)')
curl -sS -H "X-Trace-Id: $TRACE_ID" \
  -H 'Idempotency-Key: demo-1' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"charge","args":{"amount":100}}' \
  http://127.0.0.1:8081/v1/tool-calls

服务端日志：

ts=2026-10-19T09:31:02.114Z trace=d7c1... span=root op=POST /v1/tool-calls status=202 dur=3ms
ts=2026-10-19T09:31:02.117Z trace=d7c1... span=db op=insert calls dur=1ms
ts=2026-10-19T09:31:02.121Z trace=d7c1... span=tool op=charge dur=180ms status=ok

这条日志说明：总耗时 3 ms 是假象，工具执行在异步线程里继续了 180 ms；202 返回的是「已受理」，不是「已完成」。只看访问日志的 dur，会把异步执行的服务看成「很快」。

1.8.2 一条命令判断「是不是重试」

如果你怀疑重复来自重试，先数请求，而不是猜：

# 按幂等键统计服务端收到的请求数（示例：从结构化日志里抽）
jq -r 'select(.event=="tool_call") | [.idempotency_key, .attempt] | @tsv' /tmp/tool.log \
  | sort | uniq -c | sort -rn | head

期望：

   3  K1  1
   1  K1  2
   1  K2  1

K1 有 3 次 attempt 1，说明客户端在并发重试（同一逻辑请求的多个物理尝试同时到达）；K2 是新键，说明客户端在中途换了键。两种情况的修复不同：前者要靠服务端并发去重，后者要靠客户端契约。

1.8.3 把 trace context 传下去

trace id 不能只打印在入口日志里，要跟着请求走。Python 可以用 contextvars 做一个最小实现：

import contextvars, uuid

_trace_id = contextvars.ContextVar("trace_id", default=None)

def new_trace_id() -> str:
    tid = uuid.uuid4().hex
    _trace_id.set(tid)
    return tid

def current_trace_id() -> str:
    tid = _trace_id.get()
    if tid is None:
        tid = new_trace_id()
    return tid

def headers_with_trace(extra: dict | None = None) -> dict:
    h = {"X-Trace-Id": current_trace_id()}
    if extra:
        h.update(extra)
    return h

服务端收到请求后，应该：

1. 优先复用 X-Trace-Id（调用方已经生成）；
2. 没有就生成一个；
3. 在每个下游调用、每条日志、每个异步任务里带上；
4. 在响应头里回传，方便客户端关联。

这不是完整的 OpenTelemetry，但足以把「客户端超时」和「服务端执行」串起来。第 10 章会讲完整的 trace/span/采样，以及为什么「有 trace id」不等于「有可观测性」。

1.9 真实案例：Knight Capital 的重复订单

2012 年 8 月 1 日，美国做市商 Knight Capital 在纽交所开盘后约 45 分钟内发出大量错误订单，造成约 4.4 亿美元损失，最终被另一家公司收购。SEC 在 2013 年对其处以 1200 万美元罚款，理由是违反了市场访问规则（Rule 15c3-5）。

公开复盘的关键事实：

• 当天部署了一段新代码，但 8 台服务器中只有 7 台更新成功；剩下 1 台仍运行旧版本。
• 旧版本里有一个早已废弃的订单执行路径（内部代号 “Power Peg”），被一个复用的配置开关重新激活。
• 这台旧服务器开始向市场发送大量重复/错误订单；其他服务器正常，因此监控没有立刻发现。
• 系统没有「按账户/按策略的订单幂等闸门」，也没有在发现异常后自动停止该策略的能力。

它不是「网络超时导致重试」的案例，而是重复副作用的另一个典型形状：同一段逻辑被旧代码路径反复执行，而没有一道「这个意图是否已经执行过」的闸门。把它放在第 1 章，是因为它和发券事故共享同一个根因：

执行动作没有身份，重复就无法被识别。

教训不是「部署要小心」这种空话，而是三条可执行的设计：

1. 每个有副作用的操作都要有幂等身份：订单 ID、发券键、支付 intent，至少在存储层有唯一约束。
2. 部署要能发现「版本不一致」：Knight 的 7/8 是典型的灰度不一致；健康检查不能只看端口，要看版本/能力。
3. 异常时要能自动停：按策略/账户的断路器，比人工发现快得多。

1.10 设计一张远程调用契约

把前面的讨论压缩成一张契约。每次新增一个远程调用，先回答下面 12 个问题；答不上来的，不要写代码。

1.10.1 一份可用的契约模板

{
  "request": {
    "idempotency_key": "string, client-generated, stable across retries",
    "client_id": "string",
    "seq": "int64, monotonically increasing per client",
    "deadline_ms": "int, remaining budget at send time",
    "tool": "string",
    "args": "object, canonicalized before fingerprinting"
  },
  "response": {
    "call_id": "string",
    "status": "pending|running|succeeded|failed|unknown",
    "attempt": "int",
    "result": "object|null",
    "error": {"code": "string", "retryable": "bool", "message": "string"},
    "retry_after_ms": "int|null",
    "query_url": "string"
  },
  "errors": {
    "409": "same key, different fingerprint",
    "429": "rate limited; honor Retry-After",
    "503": "overloaded or dependency unavailable; may be retryable"
  }
}

模板里有三个容易漏的字段：

• deadline_ms 是发送时的剩余预算，不是原始超时；接收方要立刻换算成本地 deadline。
• attempt 是物理尝试序号，用于观测和去重，不参与业务语义。
• error.retryable 是服务端对「这个错误能否重试」的判断；客户端不要自己猜。

1.10.2 指纹：同键不同参必须拒绝

幂等键只能保证「同一个键」被处理一次，不能保证「参数没变」。如果客户端用 K1 先发 amount=100，再发 amount=1000，服务端直接返回第一次的结果，用户会以为第二次也生效了。正确做法是：

1. 对请求参数做规范化（排序 key、去掉空白、统一数字格式）；
2. 计算 SHA-256 指纹；
3. 存 (idempotency_key, fingerprint)；
4. 同键不同指纹 → 409，并返回第一次的指纹摘要，便于排障。

import hashlib, json

def fingerprint(tool: str, args: dict) -> str:
    canonical = json.dumps(
        {"tool": tool, "args": args},
        sort_keys=True, separators=(",", ":"), ensure_ascii=False,
    )
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

规范化不是「可选优化」。{"a":1,"b":2} 和 {"b":2,"a":1} 在 JSON 语义上相同，但直接 json.dumps 会得到不同字符串；不排序就会把同一个请求误判为冲突。反过来，浮点数 1 和 1.0、Unicode 归一化、空值省略，也需要在契约里统一。

1.10.3 错误码分类：哪些能重试

错误码不是给人看的注释，是给客户端做决策的输入。至少要把下面几类分开：

最容易出错的是 500 和 504。500 可能是「写库成功后序列化响应失败」，此时副作用已经发生；504 可能是网关等不到上游响应，上游可能已提交。这两类不能简单标成可重试，必须先走 unknown 收敛。

反过来，400/401/403/404/422 重试一万次也不会成功，只会浪费连接和配额。把「不可重试」的错误也重试，是重试风暴的另一个来源。

1.10.4 契约演进：新增字段、删除字段、改语义

远程调用的契约一旦发布，就不能假设「所有客户端同时升级」。你必须按「旧客户端 + 新服务端」「新客户端 + 旧服务端」两种组合设计。

一个常见的坑是「新增必填字段」。服务端以为客户端会升级，但移动端可能有一年没更新的版本；这些请求全部 400，用户看到的是「服务不可用」。正确做法是：新增字段一律可选，服务端给默认值；确实需要强制时，用版本化接口（/v2/...），而不是在原接口上加必填。

1.10.5 契约的版本化

接口版本化有三种常见方式：

本书的项目一只用一个版本，不加版本号；这是教学简化，不是生产建议。生产环境至少要有一个「契约测试」：用旧版客户端请求新版服务端，断言不会 4xx/5xx；再用新版客户端请求旧版服务端，断言降级行为符合预期。

1.11 本书的边界与不重复清单

本书假设你已经具备以下基础；没有的话，先补 Linux 书对应篇章，再回来。

反过来，本书覆盖而母本不覆盖的内容，会在每章末尾的「母本对应」里标成「本书自编 + 论文/规范」。这不是为了显得原创，而是为了诚实：谢希仁、张彦飞和《Python 网络编程》不讲 Raft、MVCC、幂等表；这些必须靠论文、规范和自己写代码。

1.11.1 本书的章节依赖

1 请求/失败 ──▶ 2 RPC ──▶ 12 项目一
     │              │
     ▼              ▼
3 复制 ──▶ 4 一致性 ──▶ 5 共识 ──▶ 13 项目二
     │              │
     ▼              ▼
6 事务 ◀──── 7 队列/流 ────▶ 8 缓存/CDN
     │
     ▼
9 锁/租约 ──▶ 10 观测 ──▶ 11 容量/演练

这张图不是「必须先读左再读右」的硬约束，而是概念依赖：不知道 unknown，就很难理解为什么 Raft 的客户端要去重；不知道 quorum，就很难理解为什么缓存一致性不能只靠 TTL。

1.11.2 三条阅读路线

不同的读者可以从这一章走向不同的方向：

无论走哪条，第 1 章的三个概念都要带走：逻辑请求与物理尝试的区分、unknown 状态、超时不是失败。这三件事在后面每一章都会以不同形式出现。

1.12 本章陷阱清单

1.13 本章出口检查

母本对应

下一站：知道了「一次调用可能未知」，下一步要把它变成可执行的协议。进入 2 RPC：超时、重试、幂等、背压，看 deadline 怎么传、重试怎么限、幂等怎么做、背压怎么建。

2 RPC：超时、重试、幂等、背压

上一章留下三个词：unknown、逻辑请求、物理尝试。它们描述的是「一次调用可能失败得不明不白」。这一章要把这三个词变成可执行的协议：调用方在什么时刻放弃、放弃后做什么、服务端如何识别重复、系统在过载时如何拒绝。

很多团队以为用了 gRPC 或 Thrift 就自动获得了这些能力。事实相反：RPC 框架只负责「把参数变成字节、把字节变成响应」，它不负责「这次调用到底算不算成功」。超时、重试、幂等、背压这四件事，框架最多提供钩子，语义必须由使用方定义。定义错了，框架会把错误放大得更快——它让重试变得太容易，让连接复用得太深，让一次用户点击在 200 ms 内变成 16 个请求。

这一章的顺序按「一次调用的生命周期」排：先看 stub 做了什么（2.1），再看到达服务端之前的时间预算怎么传（2.2），然后看失败后怎么重试（2.3）以及重试凭什么安全（2.4）。2.5 把超时和重试接成一条正反馈时间线；2.6、2.7 讨论系统被压垮时，队列和限流如何把压力挡在门外。2.8 给出客户端与服务端各自的观测面，2.9 用 S3 2017-02-28 说明重试如何改变恢复曲线，2.10 用一笔支付说明「两个键」为什么会留下两条扣款记录。最后三节是契约检查表、陷阱清单和出口检查。

2.1 RPC 到底做了什么：stub、IDL、序列化、连接复用

先看一行代码：

resp = payment_stub.Charge(ChargeRequest(order_id="o-8812", amount_cents=1999),
                           timeout=1.0, metadata=(("idempotency-key", "pay-o-8812"),))

这行代码在服务端对应一个普通函数 def Charge(req, ctx)。中间隔着的东西，比大多数调用方想象的要多。把它们列清楚，才能知道哪些失败该由谁负责。

这张表和第 1 章的十二个 hop 是同一件事的两种切法：第 1 章按「网络位置」切，这张表按「软件层次」切。切法不同，用途也不同——前者用来定位延迟，后者用来定位责任。

2.1.1 stub 不是魔法，它只是把五件事藏起来了

生成代码里的 PaymentStub 通常做五件事，且只做五件事：

1. 类型检查：把 ChargeRequest 编译成一个有字段、有默认值的类；
2. 序列化：调用 IDL 运行时把对象编码成字节；
3. 元数据拼装：把 deadline、trace context、认证 token、幂等键塞进 header；
4. 连接管理：从 channel 里取连接、做负载均衡、处理重连；
5. 错误映射：把 wire 上的状态码映射成语言里的异常类型。

它明确不做的事同样重要：

• 不保证「最多执行一次」；它连「执行了几次」都不知道；
• 不保证顺序；多路复用下，响应到达顺序与请求发送顺序无关；
• 不保证取消能传到服务端；cancel() 通常只是本地停止等待；
• 不替你决定业务幂等键；metadata 里的键是调用方自己放的；
• 不替你选超时预算；timeout=1.0 是你写的，不是框架推荐的。

2.1.2 IDL 定义的是成功路径，不是失败路径

一个典型的 proto 定义：

syntax = "proto3";

message ChargeRequest {
  string order_id = 1;
  int64 amount_cents = 2;
  string currency = 3;
  reserved 4, 5;            // 曾经是 card_number / cvv，永远不要复用
  reserved "card_number";
}

message ChargeResponse {
  string charge_id = 1;
  string status = 2;        // succeeded | failed | unknown
  int64 amount_cents = 3;
}

service Payment {
  rpc Charge(ChargeRequest) returns (ChargeResponse);
}

这段 IDL 能表达「参数长什么样」，不能表达：

• 这个方法是幂等的还是非幂等的；
• 超时后调用方应该重试还是查询；
• 哪些错误码可以重试；
• 服务端过载时返回什么；
• 同一个幂等键配不同参数该怎么处理。

这些语义要么写在注释里（然后被忽略），要么写进契约文档和错误码表（2.11），要么由中间件强制（例如服务端校验 idempotency-key 必须存在）。IDL 是类型契约，不是行为契约；把行为契约寄托在 .proto 注释上，是团队协作里最常见的隐形债务。

字段编号还有一条硬规则：删除字段时用 reserved 占住编号和名字。否则下一个同事把编号 4 复用成 user_id，旧客户端发来的 card_number 会被解码成 user_id，产生极难排查的串字段。这条规则与 RPC 的失败语义无关，却经常在「重试 + 旧客户端」的场景里引爆。

2.1.3 序列化的成本：体积、CPU、兼容性

同一份 ChargeRequest（order_id、金额、币种、两个嵌套对象）在不同编码下的量级：

体积差 2–3 倍，在 1 KB 以下的小请求上通常不是瓶颈；真正贵的是大对象和深嵌套。一个 2 MB 的响应在客户端反序列化时可能占用 10 MB 内存和几十毫秒 CPU，而这发生在「 deadline 只剩 50 ms」的时候。压缩也有阈值：小于 1 KB 的包压缩后可能更大，还多一次 CPU。

兼容性比体积更常出事。三条规则足够挡住 90% 的事故：

1. 新字段一律可选，服务端给默认值；不要新增 required；
2. 枚举保留一个 UNSPECIFIED = 0，客户端遇到未知值不要抛异常；
3. 删除字段先标 deprecated，观察一个发布周期，再用 reserved 删除。

2.1.4 连接复用：省下的是握手，付出的是耦合

短连接的成本可以算出来。假设同城 RTT 为 0.5 ms、跨地域 RTT 为 40 ms：

TCP 握手与 TLS 握手的细节见 Linux 书 4.5，本书不重画状态机。这里只需要一个结论：在跨地域调用上，短连接会把每次调用的固定成本抬高两个数量级。1000 QPS 的服务如果每次新建连接，就是每秒 1000 次握手；连接池把这块成本摊薄到接近零。

但复用不是免费的，它把三个问题引入了调用路径：

• 队头阻塞：HTTP/1.1 一条连接同时只能有一个在途请求；HTTP/2 用 stream 解决了应用层队头，但 TCP 层的丢包仍会阻塞同连接的所有 stream。QUIC 把 stream 独立化，代价是 UDP 上的拥塞控制与中间设备兼容性。
• 流控与并发上限：HTTP/2 有 SETTINGS_MAX_CONCURRENT_STREAMS，常见默认值是 100。超过上限的请求会在客户端排队，表现为「服务端 CPU 不高，但客户端 p99 很高」。这个队列不在你的业务指标里，却真实存在。
• 生命周期耦合：服务端重启、缩容、证书轮换都会发 GOAWAY。GOAWAY 里带 last_stream_id：编号大于它的 stream 没被处理，可以安全重试；小于等于它的可能已经执行，不能盲目重试。很多「透明重试」的实现只对未处理的 stream 生效，原因就在这里。

连接池大小本身也是一道并发限制：池 50 条、每条 1 个在途请求，等价于并发上限 50；下游延迟从 20 ms 涨到 200 ms，池子的吞吐上限就从 2500 QPS 掉到 250 QPS。

2.1.5 分帧：长度前缀与它的两个坑

RPC 在字节流上要解决「一条消息到哪里结束」。最常见的是长度前缀帧：

import struct

MAX_FRAME = 4 * 1024 * 1024

def encode_frame(payload: bytes) -> bytes:
    if len(payload) > MAX_FRAME:      # 先校验长度，再分配内存
        raise ValueError(f"frame too large: {len(payload)}")
    return struct.pack(">I", len(payload)) + payload

# decode 端按 4 字节长度前缀循环切分；不足一帧时保留残余，等下一次 recv

两个坑：

1. 先校验再分配。如果实现写成 buf[4:4+n] 再判断长度，一个伪造的 4 GB 长度前缀就能让进程 OOM。校验必须发生在分配之前。
2. 半包与粘包是常态。一次 recv 可能只拿到半个长度前缀，也可能拿到两条完整消息加半条；解码端必须能处理任意切分。这不是 TCP 的缺陷，而是字节流的定义；细节见 Linux 书 4.4。

帧格式还决定了「错误如何表达」。gRPC 把状态码放在 HTTP/2 的 trailers 里；如果连接在 trailers 之前断开，客户端只知道「流断了」，不知道服务端是否执行。这正是第 1 章 unknown 的物理来源。

2.2 超时不是重试的触发器：deadline 传播

下面这条时间线在很多系统里都出现过：

t(ms)  actor     event
   0   client    send, budget=1000
  30   gateway   recv, remaining=970
  30   gateway   forward, timeout=1000   // BUG: resets the budget
  80   svc-A     recv, assumes 1000ms
 120   svc-A     query
1000   client    timeout -> unknown
3200   svc-A     commit done, side effect already happened

客户端在 1 s 时已经放弃，服务端在 3.2 s 才提交。客户端如果重试，就会产生第二次副作用；如果客户端不重试，用户看到失败但钱已经扣了。两种结果都不可接受。根因不是「超时设得太短」，而是网关把剩余预算重置成了一个新的 1 s。

2.2.1 绝对 deadline 与剩余预算

timeout 是「我愿意等多久」，deadline 是「这个请求最晚必须在什么时刻完成」。单跳里两者等价，多跳里差别巨大：

单调时钟只在同一台机器内有意义，所以跨进程不能传「绝对时刻」。工程上的标准做法是传剩余预算，接收方在收到的那一刻用本地单调时钟换算成自己的绝对 deadline：

接收方 deadline = 本地 monotonic_now + 收到的剩余预算

这个换算必须发生在「收到请求的第一时间」，不能等到业务代码里再算。中间经历的反序列化、排队、鉴权都要从预算里扣掉。

gRPC 的 grpc-timeout 就是这种相对预算，格式是「正整数 + 单位」，单位取 H/M/S/m/u/n，数值最多 8 位。发送方取「当前剩余预算」，接收方解码后立刻换算。它不传绝对时间戳，因此不受两端墙上时钟偏差影响。

2.2.2 每跳该留多少余量

预算不能平均分，也不能每跳都留固定 100 ms。余量至少覆盖三件事：

1. 回程网络时间：响应从服务端回到调用方的时间，通常约 1 个 RTT；
2. 调用方的处理时间：反序列化、写日志、唤醒等待者；
3. 抖动：p99 与中位数的差，而不是中位数本身。

一个可用的公式：

$$d_{\text{child}} = d_{\text{parent}} - t_{\text{queue}} - t_{\text{decode}} - \text{margin}$$

其中 $margin = 2 \times RTT_{p99} + 5\text{ms}$。同城 RTT 0.5 ms 时 margin 约 6 ms；跨地域 RTT 40 ms 时 margin 约 85 ms。如果算出来小于 0，正确动作是立刻失败，而不是给一个最小值继续调用——预算已经不够完成一次有意义的往返，继续调用只会制造一个注定被放弃的副作用。

这个定理看起来是废话，但它的推论经常被忽略：deadline 不是「每次尝试的超时」，而是「所有尝试共享的总预算」。第一次尝试花了 800 ms，第二次尝试就只剩 200 ms；如果重试策略还按「每次 1 s」设置，第二次尝试必然在服务端继续执行，而客户端早已放弃。

2.2.3 一个可用的 Deadline 实现

import math
import time

_UNIT_MS = {"H": 3_600_000, "M": 60_000, "S": 1_000,
            "m": 1, "u": 0.001, "n": 0.000001}


class Deadline:
    """绝对截止时间。内部只用单调时钟，不碰墙上时钟。"""

    __slots__ = ("_end",)

    def __init__(self, end_mono: float):
        self._end = end_mono

    @classmethod
    def budget(cls, ms: int) -> "Deadline":
        return cls(time.monotonic() + ms / 1000.0)

    def remaining_ms(self) -> int:
        return max(0, math.ceil((self._end - time.monotonic()) * 1000))

    def child(self, margin_ms: int) -> "Deadline":
        # margin_ms 应包含排队、解码与回程；子 deadline 绝不能晚于父 deadline
        return Deadline(self._end - margin_ms / 1000.0)

    def expired(self) -> bool:
        return self.remaining_ms() <= 0


def encode_grpc_timeout(ms: int) -> str:
    ms = max(1, ms)
    for unit in ("m", "S", "M", "H"):        # 选能放进 8 位数字的最细单位
        value = math.ceil(ms / _UNIT_MS[unit])
        if value <= 99_999_999:
            return f"{value}{unit}"
    return "99999999H"


def decode_grpc_timeout(value: str) -> Deadline:
    if len(value) < 2 or value[-1] not in _UNIT_MS:
        raise ValueError(f"bad grpc-timeout: {value!r}")
    return Deadline.budget(math.ceil(int(value[:-1]) * _UNIT_MS[value[-1]]))

三个细节值得单独说：

• 用 math.ceil 而不是 int：剩余 0.4 ms 时 int 会得到 0，编码成 0m 是非法的；ceil 得到 1 ms，虽然仍然会立刻超时，但至少是一个合法值。
• child() 只减不加。如果 margin_ms 大于剩余预算，子 deadline 落在过去，expired() 立刻为真，调用方快速失败——这是期望行为。
• remaining_ms() 返回 0 表示「已过期」，不要用它区分「刚好 0」和「负数」；两者都该失败。

2.2.4 超时之后：取消是提示，不是回滚

客户端超时后通常会发 RST_STREAM 或 Cancel。服务端收到取消，应该怎么做？

关键点：取消只能减少无效工作，不能撤销已经发生的副作用。服务端在提交前检查一次 deadline 是好习惯，但检查与提交之间仍有窗口；数据库提交后进程崩溃，取消也来不及。所以「超时后是否重复」最终仍要靠幂等键（2.4）解决，而不是靠取消。

2.3 重试策略：指数退避、抖动、预算、对冲

重试的前提不是「失败了」，而是「失败了，且再试一次有可能成功，且再试一次的副作用可控」。这三个条件缺一不可。把不满足条件的错误也重试，是重试风暴的另一个源头。

2.3.1 哪些错误可以重试

HTTP 状态码的映射在 1.10.3 已经给过，这里只强调一条：DEADLINE_EXCEEDED 是最容易被误判为可重试的错误。它的语义是「我没等到结果」，不是「服务端没执行」。只有在请求带幂等键、且剩余预算足够时才重试；否则应该进入 unknown 收敛。

2.3.2 指数退避与三种抖动

设第 $i$ 次重试（$i$ 从 0 开始）的基准等待为

$$t_i = \min(\text{cap},\ \text{base} \times 2^i)$$

无抖动时，所有失败客户端会在同一时刻重试，形成同步脉冲。三种常见抖动：

Full jitter 的公式就是一行：

import random


def full_jitter(attempt: int, base: float = 0.05, cap: float = 2.0) -> float:
    """attempt 从 0 开始；返回值单位是秒。"""
    ceiling = min(cap, base * (2 ** attempt))
    return random.uniform(0, ceiling)

取 base=50ms、cap=2s，前七次重试的等待范围：

Full jitter 有一个副作用：它有概率抽到接近 0 的等待，等于「立即重试」。在服务端已经过载时，这会增加瞬时压力。缓解办法是给一个最小等待（例如 max(10ms, ...)），或者用 equal jitter。没有一种抖动对所有场景最优；关键是不要用无抖动。

2.3.3 重试预算：限制放大倍数，而不是次数

「最多重试 3 次」限制的是单个客户端，不是系统总量。1 万个客户端各重试 3 次，就是 3 万个额外请求。重试预算（retry budget）限制的是重试请求占原始请求的比例：

class RetryBudget:
    """每个原始请求存入 ratio 个 token，每次重试消耗 1 个。

    稳态下重试比例不超过 ratio；burst 允许冷启动时先借一些 token。
    """

    def __init__(self, ratio: float = 0.1, burst: int = 20):
        self.ratio = ratio
        self.burst = float(burst)
        self.tokens = float(burst)

    def on_request(self) -> None:
        self.tokens = min(self.burst, self.tokens + self.ratio)

    def allow_retry(self) -> bool:
        if self.tokens >= 1.0:
            self.tokens -= 1.0
            return True
        return False

参数怎么定：

Envoy 的 retry_budget 用 budget_percent（默认 20%）和 min_retry_concurrency（默认 3）实现同一思路：预算按「活跃请求数 × 百分比」计算，低于最小值时至少允许 3 个并发重试。这说明预算不是「每秒固定次数」，而是与当前流量成比例。

重试预算要和熔断配合。预算只限制「重试多少」，不阻止「原始请求继续打进来」；如果下游已经不可用，正确动作是熔断一段时间，让原始请求也快速失败，而不是让预算把重试压到 0 后继续用原始流量压垮它。

2.3.4 对冲请求：用额外负载换尾延迟

对冲（hedged request）不是「失败后重试」，而是「还没失败就再发一份」：请求发出后等 $p95$，如果还没返回，就向另一个实例再发一份，谁先返回用谁，另一份取消。

对冲的代价可以算：如果阈值取 p95，约 5% 的请求会被对冲，总请求量增加 5%；如果阈值取 p50，一半请求翻倍，成本立刻不可接受。更隐蔽的是，p95 会随负载漂移：下游变慢时，p95 阈值也应该变，否则对冲比例会从 5% 涨到 50%。

对冲只适合没有副作用或副作用可去重的请求。对支付、下单这类写操作，第二份请求即使被取消，也可能在服务端已经执行；取消不是回滚。要用对冲，必须先有 2.4 的幂等键。

2.3.5 把重试、deadline、预算接在一起

import time


class RetryPolicy:
    def __init__(self, max_attempts=3, base=0.05, cap=2.0, budget=None):
        self.max_attempts = max_attempts
        self.base = base
        self.cap = cap
        self.budget = budget or RetryBudget()

    def execute(self, call, deadline):
        """call(attempt, deadline) 抛出的异常需带 retryable 属性。"""
        self.budget.on_request()          # 每个逻辑请求只充值一次
        for attempt in range(self.max_attempts):
            try:
                return call(attempt, deadline)
            except RpcError as exc:
                if not exc.retryable or attempt + 1 == self.max_attempts:
                    raise
                if not self.budget.allow_retry():
                    raise RetryBudgetExhausted() from exc
                delay = full_jitter(attempt, self.base, self.cap)
                # 重试不能延长 deadline：睡完再加一次最小调用时间仍不够，就放弃
                if deadline.remaining_ms() <= delay * 1000 + 20:
                    raise
                time.sleep(delay)
        raise AssertionError("unreachable")

这段代码有三个约束，缺一不可：

1. 重试共享同一个 deadline，call 每次拿到的是同一个对象，不能新建；
2. 睡之前检查剩余预算，否则会在 deadline 之后才发出注定失败的请求；
3. 预算耗尽直接抛，不要「再试最后一次」。

RetryBudgetExhausted 应该映射成 503 + Retry-After，而不是 500。500 会让上游以为「服务端有 bug，可能值得重试」，503 才表达「现在别来」。

2.4 幂等：键、指纹、去重表、状态机

重试要安全，必须让服务端能识别「这是同一个逻辑请求」。识别靠两样东西：键（identity）和指纹（content）。键回答「是不是同一个意图」，指纹回答「参数有没有变」。

2.4.1 键的粒度：一个用户意图，一个键

键必须满足四个条件：

1. 客户端生成：服务端自增 ID 在第二次请求时会变，无法作为身份；
2. 在首次发送前生成并持久化：不能放在 retry 循环里，也不能只放内存；
3. 在所有重试中复用：包括自动重试、手动重试、跨进程恢复后的重试；
4. 粒度等于业务意图：太粗会把两个合法请求误判为重复，太细挡不住重复。

常见的错误生成方式：

推荐 client_id:seq（客户端本地单调序号）或 UUIDv7/ULID。前者便于审计和排序，后者不需要中心协调。无论哪种，都要把键写进业务记录，而不是只放在日志里。

2.4.2 指纹：同键不同参必须拒绝

键只保证「同一个键只处理一次」。如果客户端用 K1 先发 amount=100，再发 amount=1000，服务端直接返回第一次的结果，用户会以为第二次也生效了。正确做法是对参数做规范化后计算指纹，存 (key, fingerprint)：

import hashlib
import json
from decimal import Decimal


def _default(obj):
    if isinstance(obj, Decimal):
        return format(obj, "f")        # 1.0 -> "1.0"，但金额应统一为分
    raise TypeError(f"non-canonical type: {type(obj)!r}")


def canonical_json(args: dict) -> str:
    return json.dumps(args, sort_keys=True, separators=(",", ":"),
                      ensure_ascii=False, default=_default)


def fingerprint(method: str, args: dict) -> str:
    payload = method + "\n" + canonical_json(args)
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

规范化要处理的边界：

同键不同指纹时返回 409，并在响应里带上第一次指纹的前 8 位，方便排障。不要「以新参数覆盖旧结果」，也不要「返回旧结果但假装成功」——前者破坏幂等，后者制造静默错误。

2.4.3 去重表：唯一约束是最后一道闸门

应用层的「先查再插」在并发下一定会漏：两个请求同时查到「不存在」，然后都插入。唯一约束必须由存储层保证：

CREATE TABLE idempotency_key (
  scope         TEXT    NOT NULL,          -- 租户/接口，避免不同业务撞键
  key           TEXT    NOT NULL,
  fingerprint   TEXT    NOT NULL,
  status        TEXT    NOT NULL CHECK (status IN ('running','succeeded','failed')),
  lease_until   INTEGER NOT NULL,          -- 毫秒时间戳，防执行者崩溃后永久 running
  http_status   INTEGER,
  response_body TEXT,
  created_at    INTEGER NOT NULL,
  expires_at    INTEGER NOT NULL,
  PRIMARY KEY (scope, key)
);

CREATE INDEX idx_idem_expires ON idempotency_key (expires_at);

状态机只有三个状态，比第 1 章的请求状态机更窄，因为去重表只关心「结果是否可复用」：

        claim (INSERT)
              │
              ▼
        ┌──────────┐   handler ok   ┌───────────┐
        │ running  │ ─────────────▶ │ succeeded │
        └──────────┘                └───────────┘
              │ handler error
              ▼
        ┌──────────┐
        │ failed   │
        └──────────┘
              │ same key + retryable, lease expired
              └──────────────▶ running

succeeded 是终态：同键重试直接返回原响应，不再进入 running；只有 failed 或租约过期的 running 可以被重新 claim。

一个可用的 claim 流程（SQLite，isolation_level=None 即自动提交）：

def claim(db, scope: str, key: str, fp: str, ttl_ms: int, lease_ms: int = 5000):
    """返回 (state, payload)。state ∈ claimed/replay/conflict/in_progress。"""
    now = int(time.time() * 1000)
    cur = db.execute(
        "INSERT INTO idempotency_key"
        "(scope,key,fingerprint,status,lease_until,created_at,expires_at) "
        "VALUES (?,?,?,'running',?,?,?) "
        "ON CONFLICT(scope,key) DO NOTHING",
        (scope, key, fp, now + lease_ms, now, now + ttl_ms))
    if cur.rowcount == 1:
        return "claimed", None

    row = db.execute(
        "SELECT fingerprint,status,lease_until,http_status,response_body "
        "FROM idempotency_key WHERE scope=? AND key=?", (scope, key)).fetchone()
    fp0, status, lease, code, body = row
    if fp0 != fp:
        return "conflict", fp0[:8]
    if status == "succeeded":
        return "replay", (code, body)
    if status == "running" and lease > now:
        return "in_progress", max(1, lease - now)
    # 租约过期或上次失败：条件更新，只有一个请求能接管
    cur = db.execute(
        "UPDATE idempotency_key SET status='running', lease_until=? "
        "WHERE scope=? AND key=? "
        "AND (status='failed' OR (status='running' AND lease_until<=?))",
        (now + lease_ms, scope, key, now))
    return ("claimed", None) if cur.rowcount == 1 else ("in_progress", lease_ms)

这段代码的关键是最后那条条件 UPDATE：两个请求同时发现租约过期时，只有一个能把 lease_until 改到未来，另一个的 rowcount 是 0。如果没有这个条件，两个执行者会同时跑 handler，去重表形同虚设。

lease_until 还解决「执行者崩溃后记录永远 running」的问题。租约过期后允许同键接管，但接管者必须假设「前任可能已经执行了下游副作用」；所以下游调用也必须带幂等键，不能只靠这张表。

2.4.4 TTL 与回收

去重记录不能永久保留（存储成本），也不能太早删除（重试还没结束）。TTL 至少覆盖：

$$T_{\text{ttl}} \ge T_{\text{client retry window}} + T_{\text{async callback}} + \text{margin}$$

经验值：同步接口 24 小时，支付/退款 7 天，异步任务 30 天。回收任务必须跳过 running 且租约未过期的记录；删除 succeeded 记录前，要先确认没有客户端还在用这个键重试。

到这里，重试的「安全底座」齐了：deadline 控制总预算，退避和预算控制放大，幂等键和去重表控制重复。接下来把这三者放进一条失败时间线，看它们如何一起失效。

2.5 失败模式：超时 + 重试风暴

重试风暴不是「流量太大」，而是「系统用重试把一次变慢变成了持续过载」。它的形状固定：某个依赖变慢 → 超时率上升 → 客户端重试 → 总请求量上升 → 队列变长 → 延迟进一步上升 → 超时率更高。每一轮都在给正反馈加柴。

2.5.1 一条具体的时间线

假设一个服务有 500 个工作线程，正常时每次请求占用线程 100 ms（其中 60 ms 等下游），那么它的吞吐上限是：

$$\mu = \frac{500}{0.1\ \text{s}} = 5000\ \text{req/s}$$

平时流量 2000 QPS，利用率 40%，很健康。某个下游开始抖动，平均处理时间从 100 ms 涨到 600 ms，p99 到 1.5 s。吞吐上限立刻变成：

$$\mu' = \frac{500}{0.6\ \text{s}} \approx 833\ \text{req/s}$$

注意这里 CPU 可能只用了 20%：线程都在等下游，不在算。容量不是 CPU 决定的，是「并发数 ÷ 延迟」决定的。

客户端超时设 1 s，重试 2 次，没有预算。下面三轮的数字是示意，但数量级符合真实系统：

关键在第三列和第五列：原始流量一直是 2000，没有涨；涨的是重试。系统并没有被更多用户访问，它是被自己对失败的补偿压垮的。

更糟的是，重试请求比原始请求更「贵」：它往往带着更短的剩余 deadline，服务端如果按 FIFO 排队，会在快到期时才执行，然后超时，再触发下一轮重试。一个注定超时的请求，越晚被处理，浪费越大。

2.5.2 正反馈的数学形状

把「总负载」记为 $A$，原始负载 $A_0$，重试比例 $r$，超时率是负载的函数 $p(A)$，则下一轮的负载为：

$$A_{n+1} = A_0 \left(1 + r \cdot p(A_n)\right)$$

不动点存在不等于稳定。在不动点附近线性化，稳定条件是：

$$\left| r \cdot A_0 \cdot p'(A^*) \right| < 1$$

$p'(A)$ 是「负载每增加一点，超时率上升多少」。当系统接近饱和时，$p'$ 会急剧变大，这个乘积很容易超过 1；此时任何小的扰动都会把系统推出不动点，进入发散。这就是为什么 70% 利用率时一次小抖动可能没事，90% 时同样的抖动会直接雪崩（第 1 章的排队算例给过这条曲线）。

2.5.3 同步重试：连接在睡觉，线程也在睡觉

很多 SDK 的重试是同步的：sleep 期间仍握着连接和线程。假设连接池 50 条、每个请求重试 2 次、每次退避 1 s，单个客户端实例的吞吐上限约为 $50 / (1 + 2) \approx 16$ req/s。不是因为服务端只能处理 16 个，而是因为客户端把连接的时间花在「握着连接睡觉」。异步重试（把请求放回队列、释放连接、到点再取）能把这段时间还给你，但会增加实现复杂度和乱序风险。

一个折中是「重试不占连接，但占一个轻量 timer」：连接归还池子，退避结束后重新取连接、重新解析后端。这要求请求对象可重放（幂等键已持久化），也要求重试时不要复用可能已被污染的连接。

2.5.4 止损顺序：先关放大器，再谈扩容

事故现场的常见错误是「先扩容」。扩容慢（分钟级），而且如果瓶颈是下游或队列，扩容只会把更多请求送进同一个瓶颈。正确的顺序：

第 1 步经常被跳过，因为「重试是客户端的行为，服务端改不了」。但大多数公司同时拥有客户端和服务端；即使只有服务端，也可以通过 Retry-After、GOAWAY、关闭 keep-alive 来迫使客户端退避。重试策略是系统级配置，不是某个 SDK 的私有选项。

第 11 章会把这条时间线扩展成容量规划与故障演练；本节只需要记住一个判据：当重试 QPS 与原始 QPS 的比值超过 20%，且错误率还在上升时，系统已经进入风暴，不要再加任何重试。

2.6 背压：并发上限、队列与 Little’s law

背压（backpressure）是「让上游知道下游满了，并主动减速」。它和限流的区别是：限流按配额拒绝，背压按当前处理能力拒绝；限流保护的是「别人」，背压保护的是「自己」。

2.6.1 Little’s law：并发、吞吐、延迟只能三选二

Little’s law 说：稳定系统里，平均在途请求数等于到达率乘以平均停留时间：

$$L = \lambda W$$

换一种写法，如果你把并发上限固定为 $C$，那么吞吐和延迟的关系是：

$$\lambda_{\max} = \frac{C}{W}$$

这张表解释了一个常见困惑：「CPU 只有 30%，为什么 QPS 上不去？」因为线程都在等下游，$W$ 变大了，$C/W$ 就小了。并发上限是吞吐的天花板，延迟是天花板的高度。

反过来，用 Little’s law 定并发上限：

$$C = \lambda_{\text{target}} \times W_{p99} \times 1.2$$

目标 1000 QPS、p99 延迟 250 ms，则 $C \approx 300$。注意用 p99 而不是 p50：p50 只覆盖一半请求，按它算出来的并发会在高峰期排队。

2.6.2 队列该有多长

队列的作用是吸收短时突发，不是吸收持续过载。持续过载时，队列只会把「快速失败」变成「慢速失败」，还额外占用内存和 deadline。

一个可用的估算：

$$Q \ge (\lambda_{\text{peak}} - \mu) \times T_{\text{burst}}$$

峰值 1200 QPS、服务能力 1000 QPS、突发持续 2 s，则至少需要 400 个槽位。超过这个长度的队列，在突发结束后仍然需要 2 s 才能排空；如果突发持续 10 s，队列需要 2000 个槽位，此时更合理的动作是限流，而不是加队列。

队列还有三个隐性成本：

• 内存：每个排队请求持有请求体、上下文、deadline 对象；10 万个排队请求可能吃掉几 GB。
• 过期工作：排队时 deadline 已经过了的请求，出队后应该直接丢弃，而不是继续执行。
• 公平性：FIFO 会让一个慢客户端的大请求堵住后面所有小请求；按优先级/租户分队列更稳。

2.6.3 一个带 deadline 的并发闸门

import threading


class Overloaded(Exception):
    pass


class Gate:
    """有界并发 + 有界等待。等待时间不得超过调用方剩余预算。"""

    def __init__(self, limit: int):
        self._sem = threading.BoundedSemaphore(limit)
        self._lock = threading.Lock()
        self.inflight = 0
        self.rejected = 0

    def enter(self, max_wait_s: float) -> None:
        if not self._sem.acquire(timeout=max(0.0, max_wait_s)):
            with self._lock:
                self.rejected += 1
            raise Overloaded("concurrency limit")
        with self._lock:
            self.inflight += 1

    def leave(self) -> None:
        with self._lock:
            self.inflight -= 1
        self._sem.release()

调用方传入的 max_wait_s 不是固定值，而是「剩余预算减去一次最小处理时间」。如果剩余预算只有 30 ms，而处理至少需要 50 ms，max_wait_s 为负，enter 立即失败——这是正确的：不要让一个注定超时的请求进入队列。

拒绝时返回什么，决定了上游会不会立刻再打回来：

2.7 限流与过载：令牌桶、429/503、Retry-After

限流回答「你能用多少」，背压回答「我现在还能处理多少」。两者经常一起出现，但语义不同：限流是配额（quota），背压是容量（capacity）。配额可以买，容量不能。

2.7.1 令牌桶：允许突发，限制均值

令牌桶有两个参数：速率 $r$（每秒补充多少 token）和桶容量 $B$（最多攒多少）。请求消耗 token，token 不够就拒绝或排队。

import time


class TokenBucket:
    def __init__(self, rate_per_s: float, burst: int):
        self.rate = float(rate_per_s)
        self.burst = float(burst)
        self.tokens = float(burst)
        self.updated = time.monotonic()

    def _refill(self) -> None:
        now = time.monotonic()
        self.tokens = min(self.burst, self.tokens + (now - self.updated) * self.rate)
        self.updated = now

    def allow(self, cost: float = 1.0) -> bool:
        self._refill()
        if self.tokens >= cost:
            self.tokens -= cost
            return True
        return False

    def retry_after_ms(self, cost: float = 1.0) -> int:
        self._refill()
        missing = max(0.0, cost - self.tokens)
        return int(missing / self.rate * 1000) + 1

参数选择：

• rate 等于长期允许的均值，例如每租户 100 req/s；
• burst 决定能吸收多长的突发。burst=200 意味着空闲 2 s 后可以一次性打 200 个；
• burst 不是越大越好：它把「瞬时并发」放大，下游必须能接住这个瞬时值。

常见限流算法对比：

固定窗口有一个经典边界问题：限制「每分钟 100 次」，客户端在 12:00:59 打 100 次、12:01:00 再打 100 次，两秒内实际通过了 200 次。对下游来说，这和没有限流差不多。

分布式令牌桶要把「读-算-写」做成原子操作，通常用 Redis Lua：脚本里读 tokens 和 ts，按 now-ts 补充，判断并扣减，最后一次写回。分两次 GET/SET 会在并发下超发。

2.7.2 429 与 503：谁该退避，退多久

Retry-After 的值可以是秒数（Retry-After: 3）或 HTTP 日期（Retry-After: Wed, 21 Oct 2026 07:28:00 GMT）。服务端给秒数更简单，但要注意：

1. 加抖动：如果 1 万个客户端都收到 Retry-After: 3，它们会在第 3 秒同时回来。客户端应该在 [0.8, 1.2] × Retry-After 内随机化。
2. 不要给太小：Retry-After: 0 等于「立刻重试」，会加剧过载；至少给一个估计的恢复时间。
3. 不要给太大：超过客户端 deadline 的 Retry-After 等于让客户端放弃；如果确实要这么久，应该返回 503 并让客户端走异步查询。

服务端如何区分「自己过载」和「依赖失败」：

这张表决定返回 429 还是 503：如果是自己过载，返回 503 并限流；如果是租户超额，返回 429；如果是依赖失败，返回 503，但要在响应体里说明是依赖不可用（可选，避免泄露内部拓扑），并考虑降级读缓存。

限流还会和重试相互作用：客户端收到 429 后如果立即重试，等于把限流器当成了随机数生成器。429 的语义是「现在别来」，不是「换个连接再来」；重试必须遵守 Retry-After，并且消耗重试预算。

2.8 观测：客户端和服务端各看什么

RPC 的观测难点在于：同一个逻辑请求在客户端和服务端会产生不同数量的记录。客户端看到 1 次逻辑调用、3 次物理尝试；服务端看到 3 条请求日志，其中 2 条命中去重表。如果不把 attempt 和 idempotency_key 带进指标，两边永远对不上账。

2.8.1 两边各自的黄金指标

客户端和服务端都要打 method、attempt、outcome 三个标签。标签基数是成本：method 有限，attempt 最多 5 个值，outcome 建议收敛到 5 类（ok / retryable / fatal / timeout / rejected）。不要把 idempotency_key 或 user_id 放进指标标签，基数会爆炸；它们属于日志和 trace。

2.8.2 一条命令：看连接复用与总耗时

for i in 1 2 3 4 5; do
  curl -sS -o /dev/null \
    -w "i=$i code=%{http_code} total=%{time_total} ttfb=%{time_starttransfer} connects=%{num_connects}\n" \
    -H "Idempotency-Key: obs-pay-$i" \
    -H 'Content-Type: application/json' \
    -d '{"order_id":"o-8812","amount_cents":1999}' \
    http://127.0.0.1:8081/v1/payments
done

一次本机测试的输出：

i=1 code=201 total=0.018213 ttfb=0.017904 connects=1
i=2 code=201 total=0.006911 ttfb=0.006102 connects=0
i=3 code=201 total=0.005442 ttfb=0.004910 connects=0

怎么读：

num_connects 是 curl 的字段，表示本次传输新建了几条连接；0 表示完全复用。它和 time_connect 不同：time_connect 只在新建连接时非零，复用连接时接近 0，容易让人误以为「网络很快」。

2.8.3 PromQL：重试比例与按 attempt 的 p99

重试比例必须用「重试次数 / 原始请求数」，不是「重试次数 / 总尝试次数」——后者在重试风暴时反而下降，因为分母被重试撑大了：

sum(rate(rpc_client_retries_total{service="payment"}[5m]))
/
sum(rate(rpc_client_requests_total{service="payment"}[5m]))

输出：

0.184

18.4% 已经超过 10% 的警戒线。再看按 attempt 分组的 p99：

histogram_quantile(0.99,
  sum by (le, attempt) (
    rate(rpc_client_attempt_duration_seconds_bucket{service="payment"}[5m])
  )
)

输出：

{attempt="1"} 0.212
{attempt="2"} 1.024
{attempt="3"} 1.481

读法：第 1 次尝试 p99 是 212 ms，第 2 次是 1.02 s，第 3 次是 1.48 s。重试没有变快，反而一次比一次慢，说明重试打到了已经过载的实例或更深的队列；此时继续重试只会延长故障。正常系统里，第 2、3 次尝试的 p99 应该接近第 1 次（甚至更低，因为换到了健康实例）。

2.8.4 日志：把同一个逻辑请求串起来

一条可用的尝试日志：

{"ts":"2026-10-19T09:41:02.114Z","event":"rpc_attempt","method":"Payment/Charge",
 "idempotency_key":"pay-o-8812","attempt":2,"outcome":"DEADLINE_EXCEEDED",
 "deadline_remaining_ms":18,"peer":"10.2.7.11:8443","trace_id":"d7c1e2..."}

四个字段不能省：idempotency_key（把多次尝试归并）、attempt（区分第几次）、deadline_remaining_ms（判断是不是「发出去就注定超时」）、peer（判断是不是总打到同一个坏实例）。

用 jq 按逻辑请求聚合：

jq -r 'select(.event=="rpc_attempt") | [.idempotency_key,.attempt,.outcome] | @tsv' /tmp/payment.log \
  | sort | uniq -c | sort -rn | head

输出：

  12  pay-o-8812  1  DEADLINE_EXCEEDED
   3  pay-o-8812  2  DEADLINE_EXCEEDED
   1  pay-o-8812  3  OK

这个键一共留下 16 条尝试记录，其中 12 条是 attempt=1：说明 12 个并发请求共用了同一个键，客户端在并发重试或去重逻辑失效。如果同一个 order_id 出现两个不同的 idempotency_key，那就是 2.10 的重复扣款前兆。

2.9 真实案例：S3 2017-02-28 的重启与重试

2017 年 2 月 28 日，AWS 位于北弗吉尼亚（us-east-1）的 S3 发生了一次持续约 4 小时的服务中断。AWS 官方的复盘写得克制，但事实链很清楚：

公开复盘的关键句是：一条输入错误的命令导致大量 S3 子系统被移除；重启后缓存重建、请求重试放大；影响约 4 小时。官方链接：Summary of the Amazon S3 Service Disruption。

2.9.1 为什么把它放进 RPC 一章

这场事故的根因是运维工具的参数校验与爆炸半径，不是 RPC。但它对本章有两个直接教训：

第一，重试决定了恢复的斜率。 故障期间，客户端看到的是超时和 5xx，SDK 按默认策略重试。重试没有造成最初的故障，却让恢复期的请求量高于正常水平；而恢复期的服务端恰恰最脆弱——缓存是冷的，索引在重建，能处理的并发远低于稳态。故障前的容量规划不能直接用于故障恢复期。

第二，恢复期需要主动的背压，而不是被动等待。 如果服务端在恢复期继续按稳态接收请求，队列会被填满，冷缓存下的每次未命中都要回源，回源又加重索引负担。正确动作是：入口限流到「当前能处理的量」，返回 503 + Retry-After，并临时关闭客户端的自动重试。AWS 在恢复期间采取了一系列限制性动作，本质都是「把流量降到系统能恢复的水平」。

把这两点翻译成本章的机制：

2.10 重试导致重复副作用：支付请求的两个键

现在看一个比发券更贵的例子。用户在一次结算里只点了一次「支付」，最后却被扣了两笔。系统里没有崩溃，数据库也没有丢数据；问题出在两个键上：请求键（request key）与效果键（effect key）。

2.10.1 时间线

第二天对账时，财务发现同一个 order_id 下有两笔金额相同的扣款，psp_charge_id 不同，intent_id 也不同。

2.10.2 根因不是「重试」，是键的生命周期错了

这段重试代码是常见的写法：

def pay(order_id: str, amount_cents: int) -> dict:
    for attempt in range(3):
        key = str(uuid.uuid4())          # BUG：每次尝试都生成新键
        try:
            return client.charge(order_id, amount_cents,
                                 metadata={"idempotency-key": key})
        except TimeoutError:
            continue
    raise PaymentFailed(order_id)

键在循环内部生成，意味着每次物理尝试都是一个新的逻辑请求。服务端的去重表按 (scope, key) 建唯一约束，K1 和 K2 是两个不同的键，两条记录都合法。去重表没有失效，它只是从未收到同一个键。

修复的第一步是把键的生命周期提到「支付意图」上，并持久化：

def pay(intent: PaymentIntent) -> dict:
    # intent.request_key 在创建支付意图时生成并写库，重试只读不写
    for attempt in range(3):
        try:
            return client.charge(
                intent.order_id, intent.amount_cents,
                metadata={"idempotency-key": intent.request_key,
                          "attempt": str(attempt)})
        except TimeoutError:
            continue
    raise PaymentFailed(intent.intent_id)

但这还不够。因为「请求键」只保护支付服务这一层；如果支付服务自己重试、或者消息队列重投，PSP 仍可能收到两次扣款。所以还需要效果键（effect key）：把业务意图的 ID 作为下游的幂等键。

三个键的粒度不同，缺一层就有一类重复能穿过去：

• 只有请求键：支付服务重试下游时会重复扣款；
• 只有效果键：客户端换键重试会创建两条 intent，虽然 PSP 只扣一次，但账目上多一条；
• 只有业务键：同一订单的合法多次支付（例如补款）无法表达。

2.10.3 数据库约束：最后一道闸门

CREATE TABLE payment_intent (
  intent_id     TEXT PRIMARY KEY,
  merchant_id   TEXT    NOT NULL,
  order_id      TEXT    NOT NULL,
  amount_cents  INTEGER NOT NULL,
  request_key   TEXT    NOT NULL,
  fingerprint   TEXT    NOT NULL,
  effect_key    TEXT    NOT NULL,
  status        TEXT    NOT NULL CHECK (status IN ('running','succeeded','failed')),
  psp_charge_id TEXT,
  created_at    INTEGER NOT NULL,
  UNIQUE (merchant_id, order_id),
  UNIQUE (merchant_id, request_key)
);

CREATE UNIQUE INDEX idx_effect_key ON payment_intent (merchant_id, effect_key);

UNIQUE (merchant_id, order_id) 挡住「同一订单创建两个 intent」；UNIQUE (merchant_id, request_key) 挡住「同键并发插入」；effect_key 的唯一索引保证一个意图只能对应一个效果。三层约束里，业务键最容易被忽略，因为它看起来「不属于 RPC」；但重复扣款的最终表现，往往就是业务表里多了一条合法记录。

2.10.4 对账与修复

事故已经发生后的处理顺序：

1. 按 order_id 聚合：找出同一订单下 status='succeeded' 且金额相同的多条 intent；
2. 核对 PSP：用 psp_charge_id 拉取收单方流水，确认是否真的多扣；
3. 退款：用独立的 refund_id 作为退款幂等键，不要用原 charge_id 直接重试退款；
4. 修数据：保留两条 intent 作为审计记录，把其中一条标记为 duplicate，不要物理删除；
5. 补约束：上线 UNIQUE (merchant_id, order_id) 前，先清理历史重复，否则建索引会失败。

修复后的回归测试要覆盖三个场景：同一请求键重试（应返回原结果）、同一订单换键重试（应 409 或返回原 intent）、PSP 超时后重试（PSP 侧应只扣一次）。第三个场景必须用 PSP 的沙箱验证，不能只测自己的服务。

这两个键的区分，是本章最重要的工程结论之一：请求键解决「同一次调用被重发」，效果键解决「同一个副作用被执行两次」。前者属于 RPC 层，后者属于业务/存储层；只在 RPC 层做幂等，挡不住业务层的重放。

2.11 一份 RPC 契约检查表

新增一个 RPC 接口时，把下面 15 个问题答完再写代码。答不上来的，不是「以后再补」，而是「现在就没想清楚」。

配套的默认参数（可按业务调整，但不能没有）：

这张表不能替代设计评审，但它能挡住最常见的五类事故：键在循环里生成、deadline 每跳重置、重试无预算、同键不同参静默覆盖、过载时返回 500。

2.12 本章陷阱清单

2.13 本章出口检查

母本对应

下一站：知道了「一次调用怎么超时、怎么重试、怎么去重」，下一步要回答「同一份数据放在多个副本上，谁来写、谁来读、延迟多久」。进入 3 复制：主从、多主、无主，看复制日志、故障切换与读己之写。

3 复制：主从、多主、无主

凌晨 02:13，一张 orders 表所在机架断电。主库和一台副本在同一个机架，另一台副本在 30 公里外的机房。监控上复制一直正常，只是远端副本的 replay lag 常年有 8 秒。恢复后财务发现：8 秒内大约 1.6 万笔已经返回「下单成功」的订单不见了。

复制因子是 3，但没有一份副本在正确的故障域里。这个事故里也没有哪台机器「写错」：主库按异步复制返回了成功，副本按自己的节奏重放，监控按「复制线程活着」判定健康。三个正确的局部行为，拼出了一次数据丢失。

上一章把一次远程调用拆成了逻辑请求、物理尝试和 unknown 状态。那时我们默认「服务端的数据只有一份」。这一章要把这一份数据变成多份，并回答由此产生的三个新问题：

1. 多份副本之间，谁先写、谁后写、谁说了算？
2. 主库挂了，谁接替？接替的一瞬间，哪些已经告诉用户「成功」的写可能消失？
3. 用户写完立刻去读，读到的是自己的写，还是另一个副本上的旧值？

复制是后面所有章节的地基。一致性模型（第 4 章）讨论「读到的值算不算新」，共识（第 5 章）讨论「多个副本如何对同一个顺序达成一致」，事务（第 6 章）讨论「多个 key 的复制如何保持原子」，队列（第 7 章）讨论「日志保留与重放」，锁（第 9 章）讨论「租约与 fencing」。这些话题的源头，都是本章的三件事：日志、quorum、故障切换。

本章路线：先讲复制的三个目标和 RPO/RTO（3.1），再讲单主复制的三种同步模式（3.2）与复制日志/状态机（3.3），然后进入故障切换和分裂脑（3.4）；接着换拓扑，讲多主复制的冲突来源（3.5）与三种冲突解决手段（3.6），再讲无主复制的 quorum 与修复机制（3.7）；有了这些，才能讨论复制延迟和读己之写（3.8），以及分区下双主的完整失败链（3.9）。最后用三条真实命令看 lag（3.10）、复盘 GitHub 2018-10-21（3.11）、拆解「新主重放旧命令」的重复副作用（3.12）。

3.1 复制的三个目标：耐久、读扩展、地理就近

「复制」最容易被理解成「多存一份」。但多存一份本身没有价值：如果三份副本在同一个机架、同一个交换机、同一个电源域，一次机架掉电就能全带走。复制真正要解决的是三个不同的问题，而它们对拓扑的要求并不一样。

这三个目标经常互相拉扯。为了耐久，你让主库等远端副本的 fsync，写延迟从 1 ms 变成 60 ms；为了读扩展，你把读流量放到 lag 5 秒的从库，用户开始看到旧数据；为了地理就近，你在两个洲都开主库，冲突解决立刻变成业务问题。拓扑不是「先进程度」的排序，而是这三种取舍的不同组合。

3.1.1 RPO 与 RTO：把「高可用」拆成两个可测的数

「高可用」是一个太粗的词。运维和业务真正能对齐的是两个数：

• RPO（Recovery Point Objective）：故障发生时，最多可以丢多少数据。用时间表示就是「最多回退到多久之前」，用写量表示就是「最多丢多少条已确认写」。
• RTO（Recovery Time Objective）：从故障发生到服务恢复，最多允许多久。

这张表里最容易误读的是「RPO = 0」。它的准确含义是：对那些已经向客户端返回成功的写，在承诺的故障模型内不丢。它不覆盖三种情况：

• 写还在主库内存/WAL 缓冲里，没 fsync，也没复制；
• 主库返回成功，但 ack 条件只包含「副本收到」，不包含「副本落盘」；
• 故障模型之外的相关性故障，例如三副本同机架、同交换机、同一次固件升级。

把这些边界写进契约，比在事故后争论「不是三副本吗」有用得多。

3.1.2 复制不是备份

这是运维里最常见、也最贵的一句话混淆。复制和备份都会「多一份数据」，但它们防的是不同的故障。

一个 DELETE FROM orders 的误操作，会在几秒内被复制到所有副本；备份则保留误操作之前的那个时间点。反过来，备份的 RTO 通常是小时级，不能拿它当高可用。复制保证「机器坏了还有一份」，备份保证「数据错了还能回到过去」；两者不能互相替代。

3.1.3 同步与异步的延迟代价

同步复制和异步复制的区别，不是「可靠/不可靠」，而是「主库在什么时候向客户端返回成功」。

同步复制的写延迟可以近似写成：

$$T_{\text{sync}} \approx T_{\text{local commit}} + \max_{i \in A}(RTT_i) + T_{\text{remote fsync}}$$

其中 $A$ 是必须确认的副本集合。跨地域 RTT 的物理下限由光速和路由决定：同城两个可用区可能 1–3 ms，跨 1000 公里可能 20–40 ms，跨洲可能 150–250 ms。同步复制不是加一点开销，而是把最远那个副本的 RTT 加到每一次写的关键路径上。

异步复制则是：

$$T_{\text{async}} \approx T_{\text{local commit}}, \qquad RPO \approx lag$$

主库本地提交后就返回，副本在后台追。写延迟接近本地盘，但故障时最多丢一个 lag 窗口的数据。按 2000 写/秒、lag 8 秒计算，风险窗口里大约有 1.6 万条写；如果每条订单平均 300 元，就是约 480 万元的暴露面。这个乘法应该在设计阶段算，而不是在事故后算。

这张表埋下了本章后面的冲突：RPO = 0 不是「打开同步」就自动得到的，它还需要「提升的副本拥有所有已提交写」。提升一个落后的异步副本，前面同步过的写照样会丢；3.4 和 3.11 会反复回到这一点。

3.2 单主复制：同步、异步、半同步

单主复制（single-leader，也叫主从复制）是最常见、也最容易讲清楚的拓扑：所有写先到 leader，leader 把操作写成日志，按顺序发给 follower；follower 重放日志，得到与 leader 相同的状态。读可以走 leader，也可以走 follower（要接受 lag）。

一次写从客户端到「可见」，至少经过下面几步：

1. 客户端把写请求发给 leader；
2. leader 在本地 WAL/binlog 里追加一条记录，拿到 LSN/GTID/offset；
3. leader 把日志流式发给 follower；
4. follower 写入自己的 WAL/relay log，按配置选择是否 fsync；
5. follower 回 ack；
6. leader 根据同步策略判断「提交点」是否到达，推进 commit index；
7. leader 把日志 apply 到状态机，向客户端返回成功；
8. follower 继续 apply；apply 完成后，这条写才在 follower 的读路径上可见。

第 6 步和第 8 步是两件事。很多「读不到刚写的值」不是复制没到，而是提交了但还没 apply，或者读的那台副本 apply 得慢。

leader   WAL:      [1][2][3][4][5]
commit index:            ^ 3
replica1 applied:  [1][2][3]
replica2 applied:  [1][2]

客户端写第 4 条：leader 已 append，但 commit index 仍停在 3；
如果此时读 replica2，只能看到 1、2；读 replica1，也只能看到 1、2、3。

3.2.1 三种同步模式：等谁、等到什么程度

「同步」和「异步」之间不是二选一，工程上有许多中间形态。真正需要写清楚的是两个维度：等几个副本、等到副本做到哪一步。

「等到哪一步」比「等几个」更容易被忽略。以 PostgreSQL 的 synchronous_commit 为例：

• remote_write：备库把 WAL 写进操作系统缓冲就 ack，没有 fsync；备库掉电可能丢；
• on：主库本地 fsync 后返回，备库只写不 fsync；
• remote_apply：备库 apply 完成才 ack，读备库能立刻看到（代价最大）。

MySQL 的半同步也有类似的区别：after_sync 在 binlog 同步到备库后才提交，after_commit 先在主库提交、再等备库 ack；后者的提交点更早，若 ack 不代表落盘，或切换提升了另一个副本，已返回的写仍可能丢。同一个词「半同步」，在两种实现里可能对应不同的 RPO。

3.2.2 半同步的 quorum 变体

「半同步」常被实现成「至少一个副本确认」。这个策略简单，但有两个隐患：

1. 固定副本依赖：如果指定的那个副本挂了，主库要么阻塞，要么降级为异步；降级的那一刻，RPO 从 0 变成了 lag。
2. 不保证提升安全：如果自动切换提升了一个没有被同步确认过的副本，之前「已确认」的写仍然可能丢。

更稳妥的写法是 quorum：等 k 个副本确认，且规定新 leader 必须来自「拥有全部已提交日志」的副本集合。k 的选择决定了写延迟和可用性：

等待多个副本会把长尾放大。假设每个副本有 1% 的概率让一次写超过 50 ms，且彼此独立，那么全同步等 3 个副本时，至少一个慢的概率是：

$$P(\text{slow}) = 1 - (1 - 0.01)^3 \approx 2.97$$

也就是说，单副本 p99 是 50 ms，三副本全同步的 p99 可能已经超过 50 ms 一个数量级。同步复制的尾延迟不是平均值，而是「最慢那个副本」的分布。这解释了为什么很多系统宁愿选 k=2 而不是 k=3：多等一个副本，换来的故障容忍度可能不值那一段尾延迟。

3.2.3 提交与可见性：两个常见事故

第一个事故是「读从库读不到刚写的值」：写已提交，但从库 apply 还没到，不是丢数据而是可见性滞后（3.8 用会话保证解决）。第二个事故是「主库返回成功，切换后数据没了」：ack 点在 after_commit，自动切换又提升了另一个落后副本，客户端看到的成功在新主上并不存在。RPO = 0 需要三个条件同时成立：ack 覆盖持久化、提升只选拥有全部提交日志的副本、旧主被 fence 住；缺一个，成功就可能是假的。

3.3 复制日志与状态机

复制系统真正复制的通常不是「表」，而是一串有序的操作。leader 把操作追加到日志，follower 按同样的顺序重放，得到同样的状态。这个模型叫状态机复制（state machine replication，SMR）。

它成立的前提是：相同的初始状态 + 相同的命令序列 + 确定性的执行 = 相同的最终状态。三个条件缺一不可。初始状态不一致，重放会分叉；顺序不一致，结果不同；命令不确定，各副本算出的值不同。

3.3.1 日志里有什么

index 和 term 的组合很重要。只看 index 无法判断「这个位置的记录是不是当前 leader 写的」；在 Raft 里，follower 会用 prevLogIndex/prevLogTerm 检查前缀是否匹配，不匹配就截断重来。MySQL 的 GTID 用另一套标识：每个事务有一个全局唯一 ID，切换后通过 Executed_Gtid_Set 判断哪些事务已经执行过。

日志位置不能跨系统直接比较。PostgreSQL 的 LSN 是字节偏移，MySQL 的 binlog position 是文件内偏移，Kafka 的 offset 是分区内条数；它们都叫「位置」，但单位和语义不同。观测时可以用 pg_wal_lsn_diff() 把字节差换算成可读的字节数，但不要拿 LSN 和 offset 比大小。

3.3.2 确定性：复制日志最容易被打破的假设

语句级复制（statement-based replication）直接把 SQL 文本发给副本重放。只要 SQL 里出现下面这些，副本就可能算出不同的结果：

行级复制（row-based）把「哪一行从什么改成什么」写进日志，避开了大部分不确定性，但仍有非确定性：触发器、外键级联、ON UPDATE CURRENT_TIMESTAMP 都可能在副本上产生不同结果。确定性不是「大多数时候一样」，而是「所有副本必须一样」；一次不一样，校验和就对不上。

3.3.3 日志分叉：未提交的后缀

考虑三个副本，leader A 的日志比 follower C 多两条未提交记录：

index:        1   2   3   4   5   6   7
leader A:     a   b   c   d   e
follower B:   a   b   c   d
follower C:   a   b   c   x   y      ← 上一任 leader 留下的未提交后缀
commit:                ^ 3

如果 C 在此时被提升，x、y 要不要保留？答案取决于协议：

• 在 Raft 里，只有日志至少和多数派一样新的候选人才可能当选；C 的日志虽然长，但 term 旧，通常不会赢。新 leader 会用新记录覆盖 C 的 x、y。
• 在异步主从里，如果运维强行提升 C，x、y 可能被当成「最新数据」保留下来，而 A 的 d、e 可能丢失；两边从此分叉。

关键不是「谁的日志更长」，而是「哪些记录已经提交」。未提交的后缀可以被截断，已提交的前缀不能丢。状态机如果在提交前就 apply 了 x、y，截断时还必须回滚状态；很多系统干脆规定「apply 只能发生在 commit 之后」，用延迟换安全。

3.3.4 快照：日志不能无限长

日志会无限增长，重放也越来越慢。快照（snapshot）把「某个 index 处的完整状态」物化下来，日志就可以截断到该 index 之前。新副本加入时，先安装快照，再从 base_index + 1 开始追日志。

快照有三个工程细节：一致性（必须对应确定的 index/term，不能拍到一半）、校验（带 checksum，避免损坏状态扩散）、截断边界（安装后 last_applied = base_index，更早的未提交记录必须丢弃）。

3.3.5 一个确定性的 apply 骨架

下面这段代码不是完整的复制协议，而是状态机 apply 的最小约束：按 index 顺序、每个 index 只 apply 一次、按 op_id 去重、发现空洞就报错。

class StateMachine:
    def __init__(self):
        self.last_applied = 0
        self.state = {}
        self.seen_ops = {}          # op_id -> fingerprint

    def apply(self, index, term, op):
        if index <= self.last_applied:
            return "already-applied"
        if index != self.last_applied + 1:
            raise ValueError(f"gap: want {self.last_applied + 1}, got {index}")

        op_id = op["op_id"]
        fp = op["fingerprint"]
        if op_id in self.seen_ops:
            if self.seen_ops[op_id] != fp:
                raise ValueError(f"same op_id, different payload: {op_id}")
            self.last_applied = index   # 同一条命令换了位置，仍然只执行一次
            return "duplicate-op"

        self.state[op["key"]] = op["value"]
        self.seen_ops[op_id] = fp
        self.last_applied = index
        return "applied"

这段代码里有两个容易忽略的点：

• op_id 去重和 index 去重是两件事。同一个 op_id 可能因为重试或日志重放出现在不同 index；只按 index 去重挡不住它。
• 发现 gap 时不能「先跳过，等补上再说」。状态机一旦在空洞上继续 apply，后续所有结果都可能错；正确做法是停下、拉快照、或从 leader 重新同步。

3.4 故障切换：选主、分裂脑、fencing

复制解决了「多一份」，但没有解决「主库挂了怎么办」。故障切换（failover）是把写权限从旧 leader 转移到新 leader 的过程。它看起来只是「选一个副本提升」，实际包含六个阶段，每个阶段都有自己的失败模式。

RTO 不是「选举耗时」，而是这六段之和。很多团队演练时只测了「新主多久能选出来」，真实故障时却花了几小时在对账上。3.11 的 GitHub 案例就是典型：选举本身很快，恢复服务却用了 24 小时 11 分钟。

3.4.1 一次 failover 的时间线

t0   A 是 leader（term 7），B、C 是 follower；客户端写都走 A
     A ──append/ack──▶ B, C

t1   网络分区：A 与 B、C 互相不可达（但都活着）
     [A]  ┊ 分区 ┊  [B, C]

t2   A 的租约还没到期，仍认为自己可写；B、C 选举超时，开始投票
     A: "我还是 leader"          B、C: "A 可能死了"

t3   B 拿到多数票，成为 leader（term 8），开始接受写
     A（term 7）仍在服务一部分客户端

t4   两个客户端分别写同一个 key：
     client X → A: stock = 9
     client Y → B: stock = 8
     两边都可能返回成功

t5   分区恢复。A 的 term 7 写入被 B 拒绝；A 必须自停或被 fence
     若没有 fencing，A 会继续接受写，形成双主

t6   对账：找出只在 A 上存在的写、只在 B 上存在的写
     选择保留哪一侧，或人工合并；旧主重建为 follower

这张图里有两个「都活着」：A 活着，B、C 也活着。分区不是「一边死了」，而是「两边都认为自己是对的」。故障检测器只能根据超时猜，猜错就会制造两个 leader。

3.4.2 分裂脑：两个 leader 都接受写

分裂脑（split brain）是指系统同时存在两个（或更多）自认为有写权限的 leader。它的直接后果不是「服务不可用」，而是「服务太可用」：两边都接受写，都返回成功，直到恢复时才发现两份历史对不上。

最危险的不是「值冲突」，而是「业务不变量冲突」。两个 leader 都把库存从 1 改成 0，值上看起来收敛了，但两个订单都成立，实际卖了 2 件。LWW 能合并值，不能合并「已经发生的副作用」。

3.4.3 fencing：把旧 leader 挡在资源外

解决分裂脑不能只靠「旧主自觉」。旧主可能 GC 停顿、网络隔离、时钟错乱，它「不知道自己已经过期」。可靠的做法是在资源端加一道闸：每次提升 leader 时分配一个单调递增的 epoch/term，资源端记录见过的最大 epoch，拒绝更小的 epoch。

提升 B 时：epoch = 8
B 写存储：  if epoch >= stored_epoch: accept; stored_epoch = 8
A 恢复后：  epoch = 7
A 写存储：  7 < 8 -> reject

这就是 fencing token 的核心：不是阻止旧 leader 发请求，而是让它的请求在资源端无效。token 必须由单调计数器分配，资源端记录见过的最大值并拒绝更小的 token；相等只应发生在同一个 leader 的重试上。如果两个 leader 拿到同一个 token，说明分配器已经失效，fencing 无法区分它们。

常见的 fencing 手段：

租约和 fencing 经常一起用：租约让旧主「大多数时候自觉停」，fencing 让它在「不自觉」时也写不进去。只靠租约是不够的，因为租约依赖本地时钟；进程停顿超过租约时间，醒来后可能继续写。第 9 章会把租约、GC 停顿和 fencing 展开成完整的锁协议。

3.4.4 节点角色状态机

FOLLOWER ──election timeout──▶ CANDIDATE ──majority──▶ LEADER
    ▲                              │                     │
    └──── 更高 term / 发现 leader ──┘                     │
    └──────────── 更高 term / 租约到期 ──────────────────┘

最容易被忽略的是 LEADER → STOPPED 这条边。很多实现只让 leader 退回 follower，然后期待它「不再接受写」；但如果客户端还连着它，或者它还有本地缓存，就可能继续服务。「退回 follower」是状态变更，「停止服务」是行为变更，两者之间需要显式的 fence 或撤权。

3.5 多主复制：冲突从哪来

单主复制的写路径只有一条，所以「顺序」天然存在。多主复制（multi-leader）让多个节点都能接受写，写延迟可以做到本地，但代价是：两个写可能在没有因果关系的情况下同时发生。这就是冲突。

多主不是为了「更高级」，它有明确的使用场景：

「应用双写」经常被误认为多主复制，其实不是。多主复制至少有一条复制日志，写操作会被传播、排序、检测冲突；应用双写是两个独立的写请求，没有共享日志，也没有原子性。

3.5.1 冲突的六个来源

最后一类「读冲突」值得单独说。写冲突是「两个写并发」，读冲突是「一次读看到了多个并发版本，或者从不同 leader 读到了不同值」。有些系统（如 Dynamo 系）会把多个版本作为 siblings 一起返回，让客户端合并；有些系统在服务端用 LWW 选一个，读冲突被隐藏，但可能选错。读冲突通常是写冲突没有被解决的症状，而不是另一类独立问题。

3.5.2 一个库存例子：LWW 解决不了不变量

假设两个地域各有一个 leader，库存初始为 1：

从「值」的角度，两个写都是 0，LWW 合并后还是 0，看起来完美收敛；从「业务」的角度，两笔订单都成立，不变量已经破了。冲突解决只能选一个值，不能撤销一个已经发生的副作用。

要避免这种问题，要么把库存变成「预留/扣减」的协调操作（quorum 或单主），要么用 escrow：把库存拆成多个地域的额度，跨额度调拨需要协调。CRDT 的 PN-Counter 能正确累加，但同样不能阻止「减到负数」；不变量需要额外的协调或约束。

3.5.3 冲突检测：早检测还是晚检测

没有一种策略适合所有场景。支付/库存这类强不变量，应该在写时检测（条件更新、唯一约束、quorum）；协作编辑/购物车这类可合并状态，可以读时检测 + CRDT；分析/日志这类可重放数据，事后对账即可。

3.6 冲突解决：LWW、版本向量、CRDT

检测到冲突之后，必须选一个解决方案。工程上常见三种：LWW（最后写入者获胜）、版本向量（检测并发，交给业务合并）、CRDT（用可交换的数据结构自动合并）。它们不是「谁更先进」，而是「谁愿意付出多少元数据与协调成本」。

3.6.1 LWW：最简单，也最容易静默丢数据

LWW（last-write-wins）给每个写附加一个时间戳，合并时选时间戳最大的；时间戳相同则用节点 ID 等确定性规则打破平局。

它的问题不是「实现难」，而是「时间戳不是因果」：

B 的写发生在 A 之后，但它的时间戳更小；LWW 选 x = 1，B 的写被静默丢弃。没有报错，没有冲突提示，只有对账时才发现「用户明明改了，怎么还是旧值」。

LWW 还有几个变体问题：

• 时间戳由谁生成：应用服务器、数据库、客户端？客户端时钟最不可信；应用服务器也可能 NTP 回拨。
• 删除与更新：删除通常用 tombstone（带时间戳的删除标记）。如果 tombstone 被过早回收，旧更新可能「复活」已删除的数据。
• 相同时间戳：必须有一个确定性的 tie-break，否则不同副本可能选不同值，收敛失败。
• 时钟回拨：NTP 把时钟往回调，后来的写可能带更小的时间戳；单调时钟只能保证同一台机器内不倒退，不能跨机器比较。

3.6.2 版本向量：先判断「是不是并发」

版本向量（version vector）给每个副本一个计数器。副本本地写时把自己的计数加一；收到别人的版本时逐分量取最大。两个版本向量之间只有三种关系：

• a 支配 b（a 的所有分量 ≥ b，且至少一个 >）：b 是旧版本；
• b 支配 a：a 是旧版本；
• 互不支配：两个写并发，需要业务合并。

from collections import Counter

def happens_before(a, b):
    """a 的因果历史是否严格早于 b。"""
    keys = set(a) | set(b)
    return a != b and all(a.get(k, 0) <= b.get(k, 0) for k in keys)

def concurrent(a, b):
    return not happens_before(a, b) and not happens_before(b, a)

def merge(a, b):
    out = Counter(a)
    for node, n in b.items():
        out[node] = max(out[node], n)
    return out

a = Counter({"A": 2, "B": 1})
b = Counter({"A": 1, "B": 2})
print(concurrent(a, b))      # True：两个写并发
print(dict(merge(a, b)))     # {'A': 2, 'B': 2}：合并后的因果历史

c = Counter({"A": 2, "B": 2})
print(happens_before(b, c))  # True：c 见过 b 的写

这段代码只解决「检测」，不解决「合并」。当 concurrent(a, b) 为真时，系统必须做一个业务决定：保留两个值（siblings）、按 LWW 选一个、按字段合并、还是拒绝并要求客户端重试。

版本向量也有成本：

版本向量不是用来排序的，而是用来判断「能不能排序」。如果两个版本并发，任何「谁大谁赢」的规则都是在替业务做决定；LWW 只是其中一种决定方式。

3.6.3 CRDT：用可交换的结构消灭冲突

CRDT（conflict-free replicated data type）把「合并」设计成数学运算，使副本无论以什么顺序、收到多少次更新，最终都收敛到同一个值。它依赖三个性质：

• 交换律：a ⊔ b = b ⊔ a；
• 结合律：(a ⊔ b) ⊔ c = a ⊔ (b ⊔ c)；
• 幂等律：a ⊔ a = a。

满足这三条，合并就是一个 join-semilattice；副本不需要协调，只要最终把所有更新都传播到，就会收敛。常见的 CRDT：

以 G-Counter 为例：A、B 两个副本，初始都是 0；分区期间 A 加 3 次、B 加 1 次；合并时逐副本取 max，得到 A=3, B=1，总值 4，两个增量都没丢。PN-Counter 则在每个副本上维护 P（加）和 N（减）两个向量，合并后 sum(P) − sum(N)，减法也不会丢。

但 CRDT 只保证「收敛到某个值」，不保证「这个值满足业务不变量」。PN-Counter 可以减到负数；OR-Set 可以让购物车里同时出现「已删除」和「并发添加」的商品。CRDT 解决的是「副本最终一致」，不是「业务规则永远成立」。库存不能为负、余额不能透支这类不变量，仍然需要协调（quorum、单主、escrow）或约束。

3.6.4 三种方案怎么选

选择顺序通常是：先问「冲突能不能在写路径上避免」（单主、quorum、条件更新）；不能避免，再问「业务能不能合并」（版本向量 + 合并函数）；最后才问「能不能用 CRDT 自动合并」。LWW 元数据最小但会静默丢写，版本向量把冲突暴露给业务，CRDT 自动收敛但元数据和语义成本最高。不要因为 CRDT 听起来先进，就把需要强不变量的业务塞进去。

3.7 无主复制：quorum、读修复、hinted handoff、Merkle

单主和多主都有「谁是主」的问题。无主复制（leaderless）干脆取消主：客户端（或协调者）把写发给 N 个副本中的若干个，只要收到 W 个确认就算成功；读的时候联系 R 个副本，取版本最新的值。Dynamo 系系统（Cassandra、Riak、Voldemort）是代表。

3.7.1 quorum 的数学：相交是必要条件

设每个 key 有 N 个副本，写需要 W 个确认，读需要 R 个响应。如果

$$R + W > N$$

那么任意一个写集合与任意一个读集合必然相交。证明用鸽巢原理：两个集合都是 N 的子集，大小之和超过 N，不可能不相交。

相交只说明「至少一个副本见过这次写」，不说明「读一定能拿到它」。这是本章最容易被跳过的一步，也是面试和事故里最常见的误解。

3.7.2 R + W > N 的八个边界

下面八条，每一条都能单独让 R + W > N 失效。把它们当成检查表，而不是理论注脚。

第 6 条尤其反直觉：一个写只到达 A，还没凑够 W，coordinator 就崩溃了；但 A 上的值已经能被读到。读集合 {A, C} 取最大版本，会把这条「从未完成」的写返回给客户端；之后 A 被修复回旧值，客户端之前读到的值又消失了。读到未提交的写，比读到旧值更糟：它破坏了「读到的值不会倒退」的直觉。

3.7.3 一个 3 副本 quorum 模拟器

下面的模拟器只用 Python 标准库，故意把「读路径」「持久化」「sloppy quorum」拆成可切换的开关，用来复现上面三条边界。它不是生产实现，而是一个可以跑的思维实验。

"""3 副本 quorum 模拟器（Python 标准库）。

结论：R + W > N 只保证读集合与写集合相交；
相交的副本是否被读到、是否落盘、是否在 home set 内，都还要单独保证。
"""
from dataclasses import dataclass, field


@dataclass
class Node:
    name: str
    up: bool = True
    fsync: bool = True
    store: dict = field(default_factory=dict)    # 已落盘：key -> (version, value)
    pending: dict = field(default_factory=dict)  # 仅内存：key -> (version, value)

    def put(self, key: str, version: int, value: str) -> None:
        if self.fsync:
            self.store[key] = (version, value)
        else:
            self.pending[key] = (version, value)

    def get(self, key: str):
        return self.pending.get(key) or self.store.get(key)

    def crash(self) -> None:
        self.up = False
        self.pending.clear()        # 未落盘的写在崩溃后消失

    def restart(self) -> None:
        self.up = True


class Cluster:
    def __init__(self, names=("A", "B", "C")) -> None:
        self.names = names
        self.nodes = {n: Node(n) for n in names}
        self.version = 0

    def write(self, key, value, w, down=(), sloppy=False,
              ack_before_fsync=False):
        self.version += 1
        ver = self.version
        targets = [n for n in self.names
                   if self.nodes[n].up and n not in down]
        picked = targets[:w]
        if sloppy and len(picked) < w:       # 用 hint 节点凑够 W
            for i in range(w - len(picked)):
                extra = f"H{i + 1}"
                self.nodes.setdefault(extra, Node(extra))
                picked.append(extra)
        acks = []
        for n in picked:
            node = self.nodes[n]
            node.put(key, ver, value)
            if node.fsync or ack_before_fsync:
                acks.append(n)
        return ver, acks

    def read(self, key, r, nodes=None, pick="max"):
        names = nodes or [n for n in self.names if self.nodes[n].up][:r]
        got = []
        for n in names:
            node = self.nodes[n]
            if node.up and node.get(key) is not None:
                got.append((n, node.get(key)))
        if not got:
            return None, got
        if pick == "max":
            return max(got, key=lambda x: x[1][0])[1], got
        return got[0][1], got


def seed(cluster):
    cluster.version = 1
    for n in cluster.names:
        cluster.nodes[n].put("balance", 1, "v1")


def show(label, val, got):
    ver = val[0] if val else None
    value = val[1] if val else None
    print(f"{label:24s} version={ver} value={value} from={[n for n, _ in got]}")


print("== A. 相交不等于读到最新：读路径必须比较版本 ==")
c = Cluster(); seed(c)
_, acks = c.write("balance", "v2", w=2)
print("write acked:", acks)
show("read max (A,C)", *c.read("balance", 2, nodes=("A", "C"), pick="max"))
show("read first (C,A)", *c.read("balance", 2, nodes=("C", "A"), pick="first"))

print("\n== B. ack 早于 fsync：写已确认，崩溃后仍丢 ==")
c = Cluster(); seed(c)
c.nodes["B"].fsync = False
_, acks = c.write("balance", "v2", w=2, ack_before_fsync=True)
print("write acked:", acks)
c.nodes["B"].crash(); c.nodes["B"].restart()
show("read after crash", *c.read("balance", 2, nodes=("B", "C")))

print("\n== C. sloppy quorum：hint 节点不在 home set，读集合不相交 ==")
c = Cluster(); seed(c)
c.nodes["B"].up = False; c.nodes["C"].up = False
_, acks = c.write("balance", "v2", w=2, sloppy=True)
print("write acked:", acks)
c.nodes["B"].restart(); c.nodes["C"].restart()
show("read home (B,C)", *c.read("balance", 2, nodes=("B", "C")))
show("read with hint", *c.read("balance", 2, nodes=("A", "H1")))

运行结果：

== A. 相交不等于读到最新：读路径必须比较版本 ==
write acked: ['A', 'B']
read max (A,C)           version=2 value=v2 from=['A', 'C']
read first (C,A)         version=1 value=v1 from=['C', 'A']

== B. ack 早于 fsync：写已确认，崩溃后仍丢 ==
write acked: ['A', 'B']
read after crash         version=1 value=v1 from=['B', 'C']

== C. sloppy quorum：hint 节点不在 home set，读集合不相交 ==
write acked: ['A', 'H1']
read home (B,C)          version=1 value=v1 from=['B', 'C']
read with hint           version=2 value=v2 from=['A', 'H1']

把三段输出对应回边界表：

这三段都没有违反 R + W > N。失效的是「读会等满 R 个并比较版本」「ack 代表持久化」「读写使用同一个 home set」这三个隐含假设。quorum 的数学只覆盖集合关系，覆盖不了实现细节。

3.7.4 为什么 quorum 不是线性一致

线性一致要求：存在一个全序，读能看到在它开始之前已经完成的写，并且读到的值不会倒退。R + W > N 最多保证「至少一个副本知道这次写」，它缺三样东西：

1. 全序：无主复制没有 leader/term，两个并发写没有天然顺序；用 LWW 时间戳排序，会引入 3.6.1 的时钟问题。
2. 实时序：读可能看到未完成的写，之后该写消失；也可能在写完成前读到它，之后又读不到。线性一致不允许这种「读到的值倒退」。
3. 提交语义：W 个 ack 不等于 W 个已提交的版本；如果 ack 在 fsync 之前，或写只到达一个副本就被读出来，都不满足「已完成」的定义。

在单写者、版本单调、读满 R 个并按版本取最大、ack 前 fsync、无 sloppy quorum、无成员变更这些假设同时成立时，quorum 读写可以接近「regular register」的语义：读不会返回比最近完成写更旧的值（除非并发）。但它仍然不是线性一致，因为并发写没有全序，多 key 操作也没有原子性。想把 quorum 变成线性一致，最终还是要引入共识（第 5 章）。

3.7.5 读修复与反熵

读修复（read repair）是 quorum 读的配套动作：读的时候联系 R 个副本，发现某个副本版本落后，就把最新版本写回给它。同步修复在返回前写回，读延迟高但修复确定；异步修复返回后写回，读快但进程崩溃会丢，下一次读仍旧。读修复只覆盖「被读到」的 key；冷 key 的差异要靠反熵（anti-entropy）后台比对。读修复是热点的快速通道，反熵是冷数据的兜底。

读修复还有一个陷阱：它可能把「未完成的写」当成最新版本写回所有副本，把一个本来会失败的写「扶正」。如果系统不允许脏读，读路径必须先判断版本是否已提交（例如带 commit 标记），而不是只看版本号大小。

3.7.6 hinted handoff：用别人的盘暂时接住写

当 home set 里的副本不可达时，coordinator 把写临时放到一个 hint 节点，记录「这条写原本属于哪个副本」；等目标副本恢复再回放。hint 记录至少包含 target、key、version、value、expires_at，回放时按 version 幂等写入，目标已有更高版本就跳过。

它解决的是写可用性：副本挂了，写仍能凑够 W。代价是读一致性：hint 节点不在 home set，普通 R 个读可能碰不到它；回放前读到的还是旧值。hint 过期后只能靠反熵修复；如果 hint 节点也挂了，这条写可能彻底丢失。它适合「写不能失败、读可以旧」，不适合「读必须最新」。

3.7.7 Merkle 树：用哈希找到「哪一段不一样」

反熵逐 key 比对成本太高。Merkle 树把 key 范围切成桶，每个桶算哈希，再逐层向上算到根；先比根哈希，相同就认为整个范围一致，不同就递归比较子节点，只修复不同的桶。

root ──▶ h(0-7), h(8-15) ──▶ h(0-3), h(4-7), h(8-11), h(12-15)

比较成本从 O(全部 key) 降到 O(不同的桶 × log N)，网络只传哈希。修复时再拉取具体 key 的值。Merkle 树只能发现「哈希不同」，不能判断「哪个版本更新」；树的重建有 CPU/IO 成本；哈希要用 SHA-256/BLAKE2；tombstone 被提前回收时，两边可能「看起来一致」但语义上已经丢了删除。

3.7.8 无主复制的适用边界

无主复制把「选主」的成本换成了「冲突解决 + 修复」的成本。写可用性优先、冲突可合并、读可旧、能接受后台修复的场景适合它；余额、库存、权限、跨 key 原子事务不适合。如果你的业务不能定义合并函数，无主复制只会把冲突推迟到对账时爆发。

3.8 复制延迟与读己之写

用户改完头像，点击保存，页面跳转。请求被负载均衡打到一台只读副本，副本的 apply 还停在两秒前，用户看到旧头像，又点了一次保存。第二次请求打到主库，成功；用户刷新，终于看到新头像，但不知道第一次到底有没有生效。

这不是数据丢失，而是可见性滞后。写已经在主库提交，只是读的那台副本还没 apply 到那个位置。复制延迟（replication lag）描述的正是「主库的提交位置」与「副本的可见位置」之间的差距。

3.8.1 lag 是一个分布，不是常数

监控上常写「复制延迟 2 秒」，但真实 lag 是一条随时间波动的曲线：平时 50 ms，批量导入时 30 秒，DDL 时几分钟，网络抖动时甚至瞬间归零（因为主库也没写）。用平均值会掩盖长尾，用瞬时值会误报。

更准确的度量是位置差，而不是秒数：

• PostgreSQL：pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn)，单位是字节；
• MySQL：Read_Source_Log_Pos - Exec_Source_Log_Pos，以及 Retrieved_Gtid_Set 与 Executed_Gtid_Set 的差集；
• Kafka：ISR 是否包含全部副本，以及 follower 的 MaxLag。

秒数 lag 有一个天然缺陷：它通常用「主库当前时间 − 副本最后应用事务的时间」估算。主库没有新写时，副本看起来永远追平；主库写入突然停止，lag 会瞬间归零，但副本可能还差几 MB 的 WAL。用位置差，不要只用秒数。

3.8.2 读己之写：四种会话保证

分布式系统里，「读到自己刚写的内容」不是天然成立的。它属于会话保证（session guarantees）的一种，需要显式实现。

最常用的实现是「写返回一个位置 token，读副本等到自己的 replay 位置超过 token 再返回」：

import time

def read_after_write(replica, primary, key, write_lsn, timeout_s=0.5):
    """write_lsn 来自主库提交后的 pg_current_wal_lsn()。"""
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        if replica.replay_lsn() >= write_lsn:
            return replica.get(key)
        time.sleep(0.005)
    return primary.get(key)      # 超时回主库，保底但不放大延迟

这段代码有三个工程细节：

1. write_lsn 必须在主库提交之后取，不能取事务开始时的位置；
2. 副本比较的是 pg_last_wal_replay_lsn()，不是 pg_last_wal_receive_lsn()；收到 WAL 不等于 apply；
3. 超时后回主库，而不是一直等；否则一台慢副本会把整个会话拖死。

真实客户端不要把 LSN 当字符串比较；用 pg_wal_lsn_diff() 或驱动提供的 pg_lsn 类型，否则格式变化会让比较结果失真。

另一种做法是「会话粘性」：同一用户的读请求在一段时间内都路由到主库，或者都路由到同一台副本。它实现简单，但代价是读扩展失效（粘主库）或负载不均（粘副本）。RYW 不是免费的；它把一致性成本转嫁到了路由层。

3.8.3 从库读的风险：按业务分级

这张表不是「从库不安全」，而是「从库读要匹配业务对陈旧度的容忍度」。把余额读放到从库，等于把 RPO 的风险转成了读错误；把商品详情锁在主库，则是浪费读扩展能力。

3.8.4 lag 与 failover 的交叉点

复制延迟本身不是事故，延迟 + 故障切换才是。主库在 lag 5 秒时崩溃，提升从库就丢这 5 秒内已确认的写；提升更落后的副本，丢得更多。RPO 不是配置里的一个数，而是「故障发生时 lag 的分布」。所以 lag 监控不只用于「看副本健康」，还要用于「判断能不能切换」：自动切换前检查候选副本的 replay 位置是否覆盖所有已提交事务；不覆盖就等待追平或人工确认并明确 RPO。

3.9 失败模式：分区下的双主

网络分区（network partition）是最容易被误判的故障：两边机器都活着，CPU、磁盘、进程都正常，只是彼此收不到心跳。监控看到的是「A 说 B 失联」「B 说 A 失联」，而不是「某一台机器死了」。

如果系统在失联时仍然允许两边写，就会出现两个 leader。下面是一条典型的双主时间线。

t0   正常：A 是 leader（term 7），B、C 是 follower
     client ──▶ A ──replicate──▶ B, C

t1   分区：A 与 B、C 之间的链路中断（约 43 秒）
     [A]  ┊ 分区 ┊  [B, C]
     两边都活着，都认为对方失联

t2   A 的租约未到期，继续接受写；B、C 选举超时
     A: "我还能撑 10 秒"        B、C: "A 可能死了，准备选主"

t3   B 获得多数票，成为 leader（term 8）
     A 仍以 term 7 接受写；客户端连接池里还有指向 A 的连接

t4   两个写并发：
     client X ──▶ A: UPDATE stock SET qty = 9 WHERE id = 1
     client Y ──▶ B: UPDATE stock SET qty = 8 WHERE id = 1
     两个请求都可能返回成功

t5   分区恢复：A 的 term 7 写被 B 拒绝；A 必须自停或被 fence
     若没有 fencing，A 继续写，双主持续

t6   对账：找出只在 A 上存在的写、只在 B 上存在的写
     选择权威一侧；旧主重建为 follower；校验和比对

3.9.1 两个 leader 都接受写，会发生什么

最危险的是最后两行：值可以合并，副作用不能合并。库存从 1 变成 0，两个 leader 都写 0，LWW 合并后还是 0，看起来「收敛」了；但两个订单都已经创建，超卖不会因为值收敛而消失。

3.9.2 如何止损：先停写，再选权威，最后对账

双主止损的顺序不能反。很多二次事故是因为「先对账，发现两边都有理，继续写，越对越乱」。

1. 停止两边写入：把数据库设为只读，或撤销应用的写权限；不要只靠应用层开关，应用可能有多个写入路径。
2. fence 旧 leader：撤销凭证、隔离网络、STONITH，或让存储端拒绝低 epoch 的写；确保它即使恢复也不能写。
3. 确定权威一侧：按 term/epoch、已提交日志、quorum 选出的 leader 为准；不要按「哪边数据多」「哪边时间戳新」选。
4. 保留分叉证据：把两边的 binlog/WAL、差异行导出，供审计和修复；不要急着删除旧主的日志。
5. 按操作 ID 对账：用业务操作号、幂等键、唯一约束比对，而不是逐行 diff；逐行 diff 无法区分「丢失的写」和「合法的旧值」。
6. 重建旧主：以权威侧为源，重新做一份副本；不要直接把旧主加回集群继续复制，否则会把分叉带回。
7. 复盘触发条件：为什么旧主在失去 quorum 后还能写？租约、fencing、只读开关哪一个失效了？

3.9.3 分裂脑与「设计上的多主」

分裂脑不是「多主复制的一种」。多主复制至少承认冲突存在，并准备了检测和合并；分裂脑是单主系统在故障切换时意外多出一个写者，通常没有任何冲突处理。把两者混为一谈，会得出「多主本来就会冲突，所以双主没关系」的错误结论。

3.10 观测：复制 lag 的四个来源

看到「复制延迟 30 秒」，第一反应不应该是「加副本」或「重启复制线程」。lag 是一个结果，它至少可能来自四段不同的路径；每一段的修复方式完全不同。

Kafka 的 ISR 不直接对应这四段，它是「副本是否追得上 leader」的结果信号：follower 落后超过 replica.lag.time.max.ms 就会被踢出 ISR。看到 ISR 缩小，仍然要回到 broker 的磁盘、网络、fetch 线程去分段定位。

3.10.1 PostgreSQL：把 WAL 位置拆成四段

psql -c "
SELECT application_name, state, sync_state,
       pg_wal_lsn_diff(pg_current_wal_lsn(), sent_lsn)      AS send_backlog_bytes,
       pg_wal_lsn_diff(sent_lsn, write_lsn)                 AS network_bytes,
       pg_wal_lsn_diff(write_lsn, flush_lsn)                AS fsync_bytes,
       pg_wal_lsn_diff(flush_lsn, replay_lsn)               AS apply_bytes,
       pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn)    AS total_bytes,
       replay_lag
FROM pg_stat_replication
ORDER BY total_bytes DESC;"

示例输出：

 application_name |   state   | sync_state | send_backlog_bytes | network_bytes | fsync_bytes | apply_bytes | total_bytes | replay_lag
------------------+-----------+------------+--------------------+---------------+-------------+-------------+-------------+------------
 dc2-sync         | streaming | sync       |                  0 |             0 |           0 |       16384 |       16384 | 00:00:00.004
 dc3-async        | streaming | async      |               8192 |          4096 |           0 |     4194304 |     4202496 | 00:00:02.731

怎么读：

• send_backlog_bytes 大：主库还没把 WAL 发出去；查 WAL sender、写入突增、带宽。
• network_bytes 大：已发送但备库没收到/写入；查 RTT、丢包、备库接收进程。
• fsync_bytes 大：备库收到但没落盘；查磁盘 IO、fsync 延迟、文件系统。
• apply_bytes 大：已落盘但没重放；查 CPU、锁、长事务、DDL、恢复冲突。
• total_bytes 是客户端可见 lag 的上界；先定位占比最大的那一段。

replay_lag 为 NULL 不一定是异常：主库没有新 WAL 时，PostgreSQL 无法估算时间差。判断健康要看 total_bytes 是否持续增长，以及副本的 pg_last_wal_replay_lsn() 是否在推进。

3.10.2 MySQL：IO 线程、SQL 线程与 GTID 缺口

mysql -e "SHOW REPLICA STATUS\G" | egrep \
 'Replica_IO_Running|Replica_SQL_Running|Seconds_Behind_Source|Read_Source_Log_Pos|Exec_Source_Log_Pos|Relay_Log_Space|Last_SQL_Error|Retrieved_Gtid_Set|Executed_Gtid_Set'

示例输出：

             Replica_IO_Running: Yes
            Replica_SQL_Running: Yes
          Seconds_Behind_Source: 6
             Read_Source_Log_Pos: 194321117
                Exec_Source_Log_Pos: 190968541
                  Relay_Log_Space: 335544320
                  Last_SQL_Error:
              Retrieved_Gtid_Set: 3f1a9c2e-8b71-11ee-9d0a-0242ac120002:1-918223
               Executed_Gtid_Set: 3f1a9c2e-8b71-11ee-9d0a-0242ac120002:1-918198

怎么读：

• Replica_IO_Running: No：连不上主库或认证失败；查网络、账号、主库 binlog 保留。
• Replica_SQL_Running: No：重放报错，复制停了；看 Last_SQL_Error，常见是主键冲突/行不存在。
• Read_Source_Log_Pos - Exec_Source_Log_Pos 大：已收到但没执行；查 SQL 线程、锁、长事务、并行复制。
• Relay_Log_Space 增长：relay log 堆积；重放跟不上，优先查 apply。
• GTID 有缺口但 Seconds_Behind_Source 很小：秒数在骗人；用 Retrieved_Gtid_Set - Executed_Gtid_Set 判断。

Seconds_Behind_Source 的语义是「SQL 线程当前执行的事务时间戳与主库当前时间之差」，不是严格的 WAL 位置差；主库空闲、长事务、时钟偏斜都会让它失真。GTID 缺口比秒数可靠。

3.10.3 Kafka：ISR 是结果，不是分段

kafka-topics.sh --bootstrap-server localhost:9092 --describe --under-replicated-partitions

示例输出：

Topic: orders  Partition: 3  Leader: 2  Replicas: 2,1,3  Isr: 2,1

怎么读：命令有输出，说明存在副本不在 ISR；Isr 少一个，说明 follower 落后超过 replica.lag.time.max.ms；ISR 反复收缩/扩张，说明副本在阈值附近抖动，查 GC、网络、磁盘延迟。UnderReplicatedPartitions 持续大于 0 应告警。

kafka-consumer-groups.sh --describe 里的 LAG 是消费者 lag，不是副本复制 lag。消费者 lag 大说明业务消费慢；副本 ISR 小说明 broker 复制慢。两者修复方向完全不同，不要拿 consumer lag 去查副本。

3.10.4 正常与异常的分界

阈值只是起点，真正要告警的是「趋势」：lag 持续增长、副本位置不再推进、ISR 反复抖动。单次尖刺通常可以忽略，持续 5 分钟的偏移才值得叫人。

3.11 真实案例：GitHub 2018-10-21 分区与 MySQL 切换

2018 年 10 月 21 日，GitHub 经历了一次持续约 24 小时 11 分钟的服务降级。公开复盘给出的关键事实是：一次约 43 秒的网络分区触发了数据库集群的故障切换；为避免数据不一致，GitHub 暂停了部分写入并降级服务；恢复过程远长于分区本身。

3.11.1 失败链

t0   网络分区（约 43 秒）
     │
     ├─▶ 主库与副本失去连接；副本之间仍可能互通
     │
     ├─▶ 健康检查/Orchestrator 判定主库不可用
     │
     ├─▶ 提升一个副本为新主
     │      └─ 若提升点落后于原主的已提交位置，两份历史开始分叉
     │
     ├─▶ 旧主恢复：它可能还有未被复制的写
     │      └─ 若未 fence，旧主继续接受写 -> 双主风险
     │
     ├─▶ 暂停写入/只读降级，阻止分叉扩大
     │
     └─▶ 对账、修复、恢复复制，24h11m 后完全恢复

这条链里，43 秒的分区只是触发器；真正决定影响长度的是后面几步：提升哪个副本、旧主是否被 fence、分叉如何对账、写入暂停多久。RTO 的主体不是选举，而是恢复一致性。

3.11.2 五条可执行教训

3.12 重试导致重复副作用：新主重放旧命令

复制系统里的重复副作用，通常有两个形状：

• 客户端重试跨过了 failover：旧主执行了写，客户端超时重试；新主没有见过这条写（或没有见过去重记录），又执行一次。
• 新主重放旧主的日志：分区恢复后，为了合并历史，把旧主上的一段 binlog/WAL 应用到新主；如果命令是非幂等的（balance = balance - 100），就会再扣一次。

两者都指向同一个问题：副作用的身份没有跟着数据一起复制。前者是客户端重试造成的重复执行，后者是日志重复：同一条逻辑命令在旧主和新主各执行了一次。

3.12.1 一条重复扣款的时间线