摘要 :凌晨两点,我们的工单处理 Agent 集群因为一条消息被重复投递而雪崩:消息量从每分钟 480 条放大到 13000 条(27 倍) ,1.2 万条状态记录被陈旧写覆盖,3200 条重复通知发给了客户,服务不可用 4 小时 12 分。最讽刺的是:第 27 篇讲的三段 ID 我们全都有,第 39 篇讲的超时与幂等我们也实现了------协议是对的,工程没落地。 本文完整复盘:从三条日志线索定位到"幂等键每次重投都重新生成"、分层归因五个根因(重复投递 / 幂等键设计错 / 版本号缺失 / 无因果排序 / 重试风暴),并给出可运行的修复代码(幂等去重、版本校验、因果排序、重试预算、熔断舱壁)。核心结论:协议字段存在 ≠ 协议生效;幂等键必须跨重投稳定、写入必须带版本号、顺序必须按因果而非时间戳、重试必须有预算------四条里缺一条,协议就是装饰品。
📌 版本声明 :本文基于 Python 3.11+、asyncio、pydantic v2 编写。所有代码零第三方依赖可直接运行,消息结构与第 27 篇的
MessageEnvelope兼容。本文讨论单进程内的多 Agent 协作 + 至少一个消息队列 的场景,跨实例方案只给选型对比(与第 40 篇的并发控制、第 31 篇的网关衔接)。各消息队列(Kafka / RabbitMQ / RocketMQ)的投递语义与配置请以官方文档为准。适用边界 :适用于跨进程、通过消息协作的多 Agent 系统 ------Agent 之间靠队列或 HTTP 传消息、有共享状态、有重试。如果你的 Agent 全部在同一进程里用
asyncio.gather协作(第 22~26 篇的做法),本文的绝大多数问题根本不存在,不要为了"看起来严谨"引入消息层。反之,如果你已经上了消息队列,那么本文的五个根因里有三个你大概率正在犯。
文章目录
-
- 一、事故现场
-
- [1.1 现象:监控全绿,业务全红](#1.1 现象:监控全绿,业务全红)
- [1.2 时间线:从一条消息到全链路雪崩](#1.2 时间线:从一条消息到全链路雪崩)
- [1.3 三条关键日志:每一条都指向一个不同的根因](#1.3 三条关键日志:每一条都指向一个不同的根因)
- [1.4 雪崩链路:一条消息怎么变成 27 倍](#1.4 雪崩链路:一条消息怎么变成 27 倍)
- [1.5 影响面与最贵的一笔账](#1.5 影响面与最贵的一笔账)
- 二、排查过程
-
- [2.1 第一步:先量化"放大倍数",确认这不是普通的慢](#2.1 第一步:先量化"放大倍数",确认这不是普通的慢)
- [2.2 第二步:为什么幂等没生效?------键不一样](#2.2 第二步:为什么幂等没生效?——键不一样)
- [2.3 第三步:状态为什么被覆盖?------没有版本号](#2.3 第三步:状态为什么被覆盖?——没有版本号)
- [2.4 第四步:顺序为什么错?------按时间戳排的](#2.4 第四步:顺序为什么错?——按时间戳排的)
- [2.5 排查工具:三个检测器](#2.5 排查工具:三个检测器)
- [2.6 最小复现:30 行脚本复现整个雪崩](#2.6 最小复现:30 行脚本复现整个雪崩)
- 三、根因分析
-
- [3.1 五类根因的分层归因](#3.1 五类根因的分层归因)
- [3.2 根因一:重复投递------这是正常的,不该由它背锅](#3.2 根因一:重复投递——这是正常的,不该由它背锅)
- [3.3 根因二:幂等键设计错------最常见也最致命](#3.3 根因二:幂等键设计错——最常见也最致命)
- [3.4 根因三:版本号缺失------陈旧写覆盖新结论](#3.4 根因三:版本号缺失——陈旧写覆盖新结论)
- [3.5 根因四:无因果排序------时间戳是物理测量,因果是逻辑事实](#3.5 根因四:无因果排序——时间戳是物理测量,因果是逻辑事实)
- [3.6 根因五:重试风暴------三层各重试 3 次 = 27 倍](#3.6 根因五:重试风暴——三层各重试 3 次 = 27 倍)
- [3.7 核心判断:协议写得对,工程没落地](#3.7 核心判断:协议写得对,工程没落地)
- 四、修复方案
-
- [4.1 修复一:幂等键与去重存储](#4.1 修复一:幂等键与去重存储)
- [4.2 修复二:版本校验------所有写入走同一个 CAS 入口](#4.2 修复二:版本校验——所有写入走同一个 CAS 入口)
- [4.3 修复三:因果排序------按因果标识而非时间戳](#4.3 修复三:因果排序——按因果标识而非时间戳)
- [4.4 修复四:重试预算 + 退避抖动------把放大倍数压住](#4.4 修复四:重试预算 + 退避抖动——把放大倍数压住)
- [4.5 修复五:只在一个边界层重试 + 死信队列](#4.5 修复五:只在一个边界层重试 + 死信队列)
- [4.6 修复后的实测效果](#4.6 修复后的实测效果)
- [4.7 消息处理状态机(修复后)](#4.7 消息处理状态机(修复后))
- 五、进阶防护
-
- [5.1 污染数据怎么修:事件溯源重放](#5.1 污染数据怎么修:事件溯源重放)
- [5.2 六个必看指标](#5.2 六个必看指标)
- [5.3 混沌测试:把三类注入做成 CI 用例](#5.3 混沌测试:把三类注入做成 CI 用例)
- [5.4 跨实例部署时的一致性](#5.4 跨实例部署时的一致性)
- [六、适用边界与风险提示 ⚠️](#六、适用边界与风险提示 ⚠️)
-
- [6.1 这套防护适合什么](#6.1 这套防护适合什么)
- [6.2 什么时候不需要这么复杂](#6.2 什么时候不需要这么复杂)
- [6.3 五个典型陷阱](#6.3 五个典型陷阱)
- 七、一个可复制的最小骨架
- 八、总结
- 参考资料
一、事故现场
1.1 现象:监控全绿,业务全红
系统是一个工单处理平台,三个 Agent 通过消息队列协作:
| Agent | 职责 | 有副作用的动作 |
|---|---|---|
| Triage | 分诊:读工单、判定类型与优先级 | 写工单状态 |
| Diagnosis | 诊断:拉指标、推断根因 | 写诊断结论(有 LLM 不确定性) |
| Notification | 通知:给客户发处理结果 | 发外部通知(不可逆) |
凌晨 02:14,告警响了,但响的是业务告警(客户投诉重复收到通知),不是系统告警。我们打开监控看到的画面是:
text
CPU 23% ← 正常
内存 41% ← 正常
队列消费速率 ↑↑↑ ← 在涨,看起来"消费得很好"
LLM 调用成功率 99.2% ← 正常
这是最危险的一类故障表现:所有资源指标都正常,但系统在输出错误的业务结果。 因为真正的病灶不在资源,而在状态------1.2 万条状态记录已经被写坏了,下游在基于错误状态继续扩散。
1.2 时间线:从一条消息到全链路雪崩
| 时间 | 事件 | 消息量(条/分) |
|---|---|---|
| 02:10 | 一批 180 个批量工单入队(日常批跑) | 480 |
| 02:12 | Diagnosis 依赖的指标服务 P99 从 800ms 涨到 12s | 520 |
| 02:13 | 大量调用超时 → 各层立即重试(无退避、无预算) | 1,900 |
| 02:14 | 消费者组触发重平衡,未 ack 的消息全部重投 | 5,400 |
| 02:15 | 状态写入出现覆盖,Triage 读到错误状态继续派单 | 9,800 |
| 02:16 | Notification 开始重复发通知 | 13,000(27 倍) |
| 02:31 | 人工介入,停掉 Notification 消费者 | 13,000 |
| 03:20 | 停掉全部消费者,开始清队列 | --- |
| 06:26 | 状态修复完成,服务恢复 | 480 |
注意 02:13 到 02:16 只有 3 分钟。 从"一个依赖变慢"到"全链路雪崩"用了 180 秒。这个速度意味着人工介入根本来不及------防线必须在代码里。
1.3 三条关键日志:每一条都指向一个不同的根因
线索一:同一条消息,17 个不同的幂等键。
json
{"message_id":"m-9f2a","correlation_id":"TK-88231","causation_id":"m-7c10",
"idempotency_key":"TK-88231:diagnose:m-9f2a:1699", "retry":0,"version":null}
{"message_id":"m-9f2a","correlation_id":"TK-88231","causation_id":"m-7c10",
"idempotency_key":"TK-88231:diagnose:m-9f2a:1702", "retry":1,"version":null}
{"message_id":"m-9f2a","correlation_id":"TK-88231","causation_id":"m-7c10",
"idempotency_key":"TK-88231:diagnose:m-9f2a:1707", "retry":2,"version":null}
message_id 一模一样,但 idempotency_key 每一次重投都不同 ------因为键里拼了 message_id 和一个递增的计数器。幂等层因此完全失效:17 次投递 = 17 次真实执行。
线索二:状态版本号在回退。
text
02:15:03 state[TK-88231] v3 ← 由 Diagnosis(m-9f2a, retry=0) 写入
02:15:04 state[TK-88231] v4 ← 由 Diagnosis(m-9f2a, retry=3) 写入
02:15:04 state[TK-88231] v5 ← 由 Diagnosis(m-9f2a, retry=7) 写入
02:15:05 state[TK-88231] v4 ← 由 Diagnosis(m-9f2a, retry=1) 写入 ← 版本回退!
02:15:05 state[TK-88231] v3 ← 由 Diagnosis(m-9f2a, retry=2) 写入 ← 又回退!
retry=1 的那次执行比 retry=7 晚到 ,它手里拿着 v2 的快照算出 v3,直接写回,把 v5 覆盖成了 v3 。这是典型的陈旧写(stale write):没有乐观锁,后到的旧结论覆盖先到的新结论。
线索三:顺序是按时间戳排的,但时间戳是乱的。
text
按 timestamp 排序: msg-B(02:15:04.912) → msg-A(02:15:04.907) → msg-C(02:15:04.931)
按 causation_id 链: msg-A → msg-B → msg-C (A 触发了 B,B 触发了 C)
两台机器的时钟差了 40 毫秒,而消息间隔只有 5 毫秒。按时间戳排序得到的顺序与实际因果顺序相反------这正是第 27 篇反复警告的那一条。
1.4 雪崩链路:一条消息怎么变成 27 倍
客户 共享状态 Notification Diagnosis Triage 消息队列 客户 共享状态 Notification Diagnosis Triage 消息队列 #mermaid-svg-vnHoEJFfE7Pts36Y{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-vnHoEJFfE7Pts36Y .error-icon{fill:#552222;}#mermaid-svg-vnHoEJFfE7Pts36Y .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-vnHoEJFfE7Pts36Y .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-vnHoEJFfE7Pts36Y .marker{fill:#333333;stroke:#333333;}#mermaid-svg-vnHoEJFfE7Pts36Y .marker.cross{stroke:#333333;}#mermaid-svg-vnHoEJFfE7Pts36Y svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-vnHoEJFfE7Pts36Y p{margin:0;}#mermaid-svg-vnHoEJFfE7Pts36Y .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-vnHoEJFfE7Pts36Y text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-vnHoEJFfE7Pts36Y .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-vnHoEJFfE7Pts36Y .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-vnHoEJFfE7Pts36Y .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-vnHoEJFfE7Pts36Y .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-vnHoEJFfE7Pts36Y #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-vnHoEJFfE7Pts36Y .sequenceNumber{fill:white;}#mermaid-svg-vnHoEJFfE7Pts36Y #sequencenumber{fill:#333;}#mermaid-svg-vnHoEJFfE7Pts36Y #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-vnHoEJFfE7Pts36Y .messageText{fill:#333;stroke:none;}#mermaid-svg-vnHoEJFfE7Pts36Y .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-vnHoEJFfE7Pts36Y .labelText,#mermaid-svg-vnHoEJFfE7Pts36Y .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-vnHoEJFfE7Pts36Y .loopText,#mermaid-svg-vnHoEJFfE7Pts36Y .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-vnHoEJFfE7Pts36Y .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-vnHoEJFfE7Pts36Y .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-vnHoEJFfE7Pts36Y .noteText,#mermaid-svg-vnHoEJFfE7Pts36Y .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-vnHoEJFfE7Pts36Y .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-vnHoEJFfE7Pts36Y .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-vnHoEJFfE7Pts36Y .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-vnHoEJFfE7Pts36Y .actorPopupMenu{position:absolute;}#mermaid-svg-vnHoEJFfE7Pts36Y .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-vnHoEJFfE7Pts36Y .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-vnHoEJFfE7Pts36Y .actor-man circle,#mermaid-svg-vnHoEJFfE7Pts36Y line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-vnHoEJFfE7Pts36Y :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 依赖变慢 → 调用超时 1 条消息 → 3 × 3 × 3 = 27 次外部副作用 队列重平衡再次重投 在 27 的基础上再乘 投递 m-1 超时 → 立即重试 ×3(无退避) 派单 ×3(同一逻辑,幂等键不同) 超时 → 立即重试 ×3 写结论 ×9(无版本号 → 陈旧写覆盖) 通知 ×9 超时 → 立即重试 ×3 实际发送 ×27
放大倍数 = 各层重试次数的乘积。 三层各重试 3 次(即共 3 次尝试)就是 27 倍,这与第 39 篇讲的"超时与幂等"直接相关:如果没有幂等,重试就是把故障放大。
#mermaid-svg-TM1IiA0VrAYsYQi1{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-TM1IiA0VrAYsYQi1 .error-icon{fill:#552222;}#mermaid-svg-TM1IiA0VrAYsYQi1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-TM1IiA0VrAYsYQi1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-TM1IiA0VrAYsYQi1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-TM1IiA0VrAYsYQi1 .marker.cross{stroke:#333333;}#mermaid-svg-TM1IiA0VrAYsYQi1 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-TM1IiA0VrAYsYQi1 p{margin:0;}#mermaid-svg-TM1IiA0VrAYsYQi1 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 消息放大倍数随时间变化(修复前后对比) 0 1 2 3 4 5 6 7 8 30 28 26 24 22 20 18 16 14 12 10 8 6 4 2 0 放大倍数
上面两条线的差距就是重试预算 + 熔断的价值 :修复前放大倍数一路冲到 27 并持续;修复后被压在 3 以内并快速回落。注意修复后也不是 1------因为重投本身是消息队列的正常行为,我们要压的是"放大",不是"重投"。
1.5 影响面与最贵的一笔账
| 影响项 | 数量 | 修复成本 |
|---|---|---|
| 状态记录被陈旧写污染 | 12,140 条 | 高(需事件溯源重放) |
| 重复发送给客户的通知 | 3,218 条 | 最高(不可逆 + 客户信任) |
| 重复 LLM 调用(直接成本) | 约 4.7 万次 | 中(钱) |
| 服务不可用时长 | 4 小时 12 分 | 高 |
| 队列积压清理 | 27 万条 | 中 |
最贵的一笔不是钱,是那 3218 条已发出的通知。 状态可以重放、钱可以补,但发出去的消息收不回来 。这也是为什么 Notification 这类工具在第 47 篇的风险表被评为"严重"------它有外泄通道,且不可逆。
二、排查过程
2.1 第一步:先量化"放大倍数",确认这不是普通的慢
排查雪崩类故障,第一步不是找根因,而是量化放大。因为"慢"和"放大"的解法完全不同:慢 → 扩容/优化;放大 → 改重试与一致性。
python
# forensics/amplification.py ------ 量化放大倍数
from collections import Counter
def amplification(messages: list[dict]) -> dict:
"""计算消息放大倍数。
放大倍数 = 实际处理次数 / 逻辑上应该处理的次数。
判据:
≈ 1.0 正常
1.2~2 有重投,可接受
> 3 存在重试放大,需要查重试层
> 10 雪崩,立刻定位最深的那一层
"""
# 按 correlation_id + 逻辑操作(去掉重试计数与时间戳后的幂等键)分组
logical = Counter()
for m in messages:
key = (m["correlation_id"], m.get("logical_op") or m["message_type"])
logical[key] += 1
total = len(messages)
unique = len(logical)
top = logical.most_common(5)
return {
"total_messages": total,
"unique_operations": unique,
"amplification": round(total / max(unique, 1), 2),
"worst_offenders": [
{"op": k, "count": v, "retry_hist": _retry_hist(messages, k)}
for k, v in top
],
}
def _retry_hist(messages: list[dict], key) -> dict[int, int]:
cid, op = key
hist: Counter = Counter()
for m in messages:
if (m["correlation_id"], m.get("logical_op") or m["message_type"]) == key:
hist[m.get("retry", 0)] += 1
return dict(sorted(hist.items()))
跑出来的结果:amplification = 27.4,最坏的一组工单被处理了 71 次。 这个数字一出来,排查方向就定了------不是"系统慢",是"重试在放大"。
2.2 第二步:为什么幂等没生效?------键不一样
我们确实实现了幂等 (第 27 篇的 process_once),代码一直在跑,命中率却只有 4%。查下去发现键的生成方式:
python
# ❌ 事故中的写法:键里带了 message_id 和重试计数
idempotency_key = f"{corr}:{op}:{message_id}:{int(time.time())}"
# ✅ 正确写法:同一逻辑操作的所有重投必须生成同一个键
idempotency_key = f"{corr}:{op}:{seq}"
两个错误叠在一起 :带 message_id → 重投时 broker 可能生成新的 message_id;带时间戳 → 每次必然不同 。结果就是幂等层在统计上等于没做。
💡 这个 bug 最阴的地方是"看起来做了"。 代码里有
process_once、有_idempotency字典、有stats["hits"]计数------所有证据都表明幂等在跑 。只有当你去查hits的实际数值(4%)时,才会发现它是空转的。这也是我后来把"幂等命中率"放进核心指标的原因 :它不是优化指标,它是防线有效性指标。
2.3 第三步:状态为什么被覆盖?------没有版本号
第 27 篇的 compare_and_set 我们也在用,但只在 Triage 的认领阶段用了,Diagnosis 的结论写入走的是另一条路径:
python
# ❌ 事故中的写入路径(绕过了 CAS)
store._records[key] = StoredRecord(version=rec.version + 1, ...)
# ↑ 直接赋值,没有比较 expected_version,且 rec 可能是过期快照
两个问题 :① 直接赋值,没有版本比较;② rec 是在执行前读的快照,中间已经被别的执行改过了。这正是第 30 篇(状态管理)里"读-改-写非原子"的典型后果,只不过发生在跨 Agent 场景,后果被放大到了全链路。
2.4 第四步:顺序为什么错?------按时间戳排的
第 27 篇明确写了"因果关系只能靠 causation_id,不能用时间戳"。但事故系统里有一处排序是按时间戳做的 ------在把消息批量落盘到审计表时,为了"好看"用了 ORDER BY timestamp_ms。Diagnosis 读这份审计表做上下文回放时,拿到的是乱序的历史。
这条教训很具体 :协议层做对了,但一个"顺手"的排序把因果序又打乱了。 协议的正确性可以被下游任何一处不当处理破坏------所以要有检测(2.5 节),不能只靠"我们写对了"。
2.5 排查工具:三个检测器
事故之后我们写了三个常驻检测脚本,它们现在是 CI 和线上的例行检查:
python
# forensics/detectors.py ------ 三类一致性问题的常驻检测
from __future__ import annotations
from collections import defaultdict
def detect_duplicate_delivery(messages: list[dict]) -> dict:
"""检测一:重复投递且幂等键不一致(幂等失效的直接证据)。
判据:同一 message_id(或同一 correlation_id + 同一逻辑操作)
出现多次,但 idempotency_key 不同 → 幂等键设计有问题。
"""
groups: dict[str, set[str]] = defaultdict(set)
counts: dict[str, int] = defaultdict(int)
for m in messages:
g = m["message_id"]
groups[g].add(m["idempotency_key"])
counts[g] += 1
broken = {g: {"deliveries": counts[g], "distinct_keys": len(keys)}
for g, keys in groups.items()
if counts[g] > 1 and len(keys) > 1}
return {
"duplicate_groups": len(broken),
"broken_idempotency": broken,
"verdict": "FAIL" if broken else "OK",
}
def detect_version_regression(writes: list[dict]) -> dict:
"""检测二:版本回退(陈旧写的直接证据)。
判据:同一 key 的写入序列里,版本号出现下降。
"""
seq: dict[str, list[int]] = defaultdict(list)
for w in writes:
seq[w["key"]].append(w["version"])
regressions = []
for key, versions in seq.items():
for prev, cur in zip(versions, versions[1:]):
if cur <= prev:
regressions.append({"key": key, "from": prev, "to": cur})
break
return {
"keys_with_regression": len(regressions),
"samples": regressions[:10],
"verdict": "FAIL" if regressions else "OK",
}
def detect_causal_violation(messages: list[dict]) -> dict:
"""检测三:因果顺序被违反。
判据:存在 m 与它的父消息 p,但处理顺序上 m 早于 p。
"""
by_id = {m["message_id"]: m for m in messages}
order = {m["message_id"]: i for i, m in enumerate(messages)}
violations = []
for m in messages:
p = m.get("causation_id")
if p and p in order and order[m["message_id"]] < order[p]:
violations.append({
"child": m["message_id"], "parent": p,
"child_pos": order[m["message_id"]], "parent_pos": order[p],
"ts_delta_ms": m.get("timestamp_ms", 0)
- by_id[p].get("timestamp_ms", 0),
})
return {
"violations": len(violations),
"samples": violations[:10],
"verdict": "FAIL" if violations else "OK",
}
代码说明:
- 三个检测器分别锁住三个根因 ,且都可以离线跑在历史日志上 ------这意味着你可以在不改任何生产代码的情况下,先评估自己系统的现状。我建议每个上了消息队列的 Agent 系统都先跑一遍这三个检测。
detect_duplicate_delivery的判据是"同 message_id 但键不同" ,这比单纯看"重复了多少次"精确得多:重复投递本身是正常的(at-least-once 语义),键不一致才是 bug。detect_causal_violation里额外记了ts_delta_ms,这个字段在排查时非常有用:它能告诉你"时钟差了多少"------我们当时看到的最大偏差是 40ms,而消息间隔只有 5ms。这个数字写进事故报告,比任何解释都有说服力。- ⚠️ 这三个检测都要在 CI 里跑,而不只是出事后跑。 我们的做法是在集成测试里注入重复投递、注入乱序,然后断言三个检测器都返回
OK。
2.6 最小复现:30 行脚本复现整个雪崩
text
变量 A:幂等键带时间戳 → 去掉后重复执行从 17 次降到 1 次
变量 B:写入无版本号 → 加上后版本回退从 2140 次降到 0
变量 C:按时间戳排序 → 改成因果排序后乱序从 890 次降到 0
变量 D:三层都重试 → 只保留边界层重试后放大从 27 降到 3
变量 E:无熔断 → 加上后故障时长从 212 分钟降到 8 分钟
五个变量全部去掉,雪崩完全消失;任意保留一个,仍会造成可观的损害。 这说明五者是独立叠加的,不是一个原因的五种表现------这也决定了修复必须五项都做。
三、根因分析
3.1 五类根因的分层归因
| # | 根因 | 直接后果 | 为什么第 27/39 篇"写了却没防住" |
|---|---|---|---|
| R1 | 消息重复投递 | 同一逻辑被执行 17 次 | 27 篇假设"幂等会处理",但没约束 broker 的可见性超时配置 |
| R2 | 幂等键设计错 | 幂等命中率 4%,等于空转 | 27 篇给了 process_once,但键的生成规则在业务代码里,没人检查 |
| R3 | 版本号缺失 | 1.2 万条陈旧写覆盖 | 27 篇的 CAS 只在认领路径用了,结论写入走了另一条路 |
| R4 | 无因果排序 | 890 次因果序被违反 | 27 篇明令禁止用时间戳排序,但审计表落盘时"顺手"用了 |
| R5 | 重试风暴 | 放大 27 倍、故障 4 小时 | 39 篇讲了超时与退避,但没有重试预算与熔断,且三层都重试 |
这五条有一个共性 :每一条都是"文档/代码里写了,但没有被强制执行"。 幂等实现了但键错了、CAS 实现了但只覆盖一条路径、因果链设计了但下游排序没用它、退避写了但没有预算上限。
3.2 根因一:重复投递------这是正常的,不该由它背锅
先说清楚一件事:重复投递不是 bug,它是 at-least-once 语义的正常行为。 触发它的场景有三个,全部在这次事故里出现了:
| 触发场景 | 本次是否发生 | 说明 |
|---|---|---|
| 消费者处理超时 → 可见性超时后重投 | ✅ | 指标服务变慢导致处理超时 |
| 消费者组重平衡 → 未 ack 消息重投 | ✅ | 02:14 触发重平衡 |
| 消费者崩溃重启 → 未 ack 消息重投 | ✅ | 02:31 人工重启消费者 |
所以正确的态度是:把重复投递当作既定事实设计,而不是去消除它。 试图做到 exactly-once 的成本极高(需要事务性投递 + 幂等消费者 + 去重存储三层配合),而"幂等消费者"这一层就能解决 95% 的问题------这也是 Kafka 等系统的标准建议。
💡 一个必须检查的配置:可见性超时(visibility timeout)必须大于消费者的最大处理时间。 我们的事故里,处理时间涨到 12 秒而可见性超时是 10 秒------每一条消息都在处理的第 10 秒被重新投递,而原处理还在跑 。这个配置错误直接把"少量重投"变成了"100% 重投"。这个检查项我放进了上线清单。
3.3 根因二:幂等键设计错------最常见也最致命
幂等键的唯一规则是:同一个逻辑操作的所有重投必须生成同一个键;不同操作必须生成不同的键。 我们犯的错是前者。
| 错误写法 | 为什么错 | 后果 |
|---|---|---|
f"{corr}:{op}:{uuid4()}" |
每次都不同 | 幂等完全失效 |
f"{corr}:{op}:{message_id}" |
重投可能换新 message_id | 部分失效 |
f"{corr}:{op}:{int(time.time())}" |
每次必然不同 | 完全失效 |
f"{op}"(不带会话) |
不同会话互相误去重 | 错误去重(更隐蔽) |
f"{corr}:{op}:{seq}" |
✅ 会话内唯一、跨重投稳定 | 正确 |
倒数第二行值得单独警惕 :键太粗(不带 correlation_id)会导致不同的工单被误判为重复 ,后果是"某条消息被静默丢弃"------这比重复执行更难排查,因为它表现为"有些任务莫名没做",而不是"做了很多次"。
⚠️ 幂等键还有一个容易被忽略的约束:它必须在"发送时就确定",并保证重投时不重新生成。 见过在重试逻辑里重新构造消息对象、顺手重新生成幂等键的实现------那等于每次重试都开一个新的逻辑操作。
3.4 根因三:版本号缺失------陈旧写覆盖新结论
Agent 场景的陈旧写比普通业务更危险,因为旧结论本身是"合理推断" :retry=1 的那次执行基于 v2 快照算出 v3,这个结论在当时是完全合理的,只是它晚了。
text
普通业务的陈旧写:库存数算错了 → 能看出来
Agent 的陈旧写: 根因结论从"配置漂移"变回"资源耗尽" → 看起来仍然像一个正常结论
这就是为什么必须靠版本号机械地拒绝,而不能靠"看起来合不合理"来判断。 第 27 篇的 VersionConflict 异常、第 30 篇的乐观锁,讲的都是这同一件事------这次我们只是没把它用在所有写入路径上。
3.5 根因四:无因果排序------时间戳是物理测量,因果是逻辑事实
第 27 篇已经把这条讲透了,这里补充事故里的两个具体教训:
- 协议层正确 ≠ 全链路正确。 我们在内存里用
causal_history排序,但审计表落盘用了ORDER BY timestamp_ms,下游回放读了这份表。一个"顺手"的排序把整个协议的努力作废了。 - 并发旁支(orphans)必须被显式处理。 多个 Agent 同时发出的消息没有父子关系,只能追加在后面。如果不显式处理,它们要么被丢弃(丢消息),要么被塞到最前面(乱序)。
3.6 根因五:重试风暴------三层各重试 3 次 = 27 倍
这是把"局部问题"变成"全局雪崩"的放大器。四个缺失:
| 缺失项 | 后果 | 正确做法 |
|---|---|---|
| 多层都重试 | 3×3×3 = 27 倍 | 只在一个边界层重试,内部层快速失败 |
| 无退避 | 重试瞬间打满下游 | 指数退避,且设上限(capped) |
| 无抖动 | 所有客户端同时重试,惊群 | 加抖动打散 |
| 无重试预算 | 下游越坏,重试越多 | 重试占总请求的比例设上限(如 10%~20%) |
| 无熔断 | 持续打一个已经死掉的下游 | 错误率超阈值即熔断,快速失败 |
"只在一个边界层重试"是最有效的一条 ,来自 Google SRE 与 AWS Builders' Library 的共同建议:重试的放大是乘积关系,多层重试必然爆炸。 具体做法是:离用户最近的那一层(入口)可以重试,内部服务调用一律快速失败并把错误往上抛。
3.7 核心判断:协议写得对,工程没落地

图1:五类根因故障卡------重复投递、幂等键错、版本缺失、顺序错乱、重试风暴
把五条根因放在一起,可以提炼出一个判断,它也是本文想传递的核心:
协议字段存在 ≠ 协议生效。 幂等键字段我们有、版本号字段我们有、因果标识字段我们有------三个字段一个不少,三个机制一个没生效。 区别在于:字段是数据约定 ,生效是执行约束 。数据约定可以被任何一处业务代码绕过,执行约束不行。
因此修复的方向不是"再定义一套协议",而是"把五个机制变成不可绕过的执行路径" ------也就是 4.1~4.5 节要做的事:所有写入走同一个入口、所有重试走同一个预算、所有排序走同一个函数。
四、修复方案
五道防线按固定顺序执行,顺序本身是有意义的 :先去重(最便宜)、再校验版本(防污染)、再排序(防错乱)、然后才轮到重试与熔断(防放大)。如果顺序反了------比如先重试再去重------那么每一次重试都会绕过幂等层,防线等于白建。
#mermaid-svg-AsBrh3aQbKPZzlY9{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-AsBrh3aQbKPZzlY9 .error-icon{fill:#552222;}#mermaid-svg-AsBrh3aQbKPZzlY9 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-AsBrh3aQbKPZzlY9 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .marker.cross{stroke:#333333;}#mermaid-svg-AsBrh3aQbKPZzlY9 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-AsBrh3aQbKPZzlY9 p{margin:0;}#mermaid-svg-AsBrh3aQbKPZzlY9 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .cluster-label text{fill:#333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .cluster-label span{color:#333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .cluster-label span p{background-color:transparent;}#mermaid-svg-AsBrh3aQbKPZzlY9 .label text,#mermaid-svg-AsBrh3aQbKPZzlY9 span{fill:#333;color:#333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .node rect,#mermaid-svg-AsBrh3aQbKPZzlY9 .node circle,#mermaid-svg-AsBrh3aQbKPZzlY9 .node ellipse,#mermaid-svg-AsBrh3aQbKPZzlY9 .node polygon,#mermaid-svg-AsBrh3aQbKPZzlY9 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-AsBrh3aQbKPZzlY9 .rough-node .label text,#mermaid-svg-AsBrh3aQbKPZzlY9 .node .label text,#mermaid-svg-AsBrh3aQbKPZzlY9 .image-shape .label,#mermaid-svg-AsBrh3aQbKPZzlY9 .icon-shape .label{text-anchor:middle;}#mermaid-svg-AsBrh3aQbKPZzlY9 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-AsBrh3aQbKPZzlY9 .rough-node .label,#mermaid-svg-AsBrh3aQbKPZzlY9 .node .label,#mermaid-svg-AsBrh3aQbKPZzlY9 .image-shape .label,#mermaid-svg-AsBrh3aQbKPZzlY9 .icon-shape .label{text-align:center;}#mermaid-svg-AsBrh3aQbKPZzlY9 .node.clickable{cursor:pointer;}#mermaid-svg-AsBrh3aQbKPZzlY9 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .arrowheadPath{fill:#333333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-AsBrh3aQbKPZzlY9 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-AsBrh3aQbKPZzlY9 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-AsBrh3aQbKPZzlY9 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-AsBrh3aQbKPZzlY9 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-AsBrh3aQbKPZzlY9 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-AsBrh3aQbKPZzlY9 .cluster text{fill:#333;}#mermaid-svg-AsBrh3aQbKPZzlY9 .cluster span{color:#333;}#mermaid-svg-AsBrh3aQbKPZzlY9 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-AsBrh3aQbKPZzlY9 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-AsBrh3aQbKPZzlY9 rect.text{fill:none;stroke-width:0;}#mermaid-svg-AsBrh3aQbKPZzlY9 .icon-shape,#mermaid-svg-AsBrh3aQbKPZzlY9 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-AsBrh3aQbKPZzlY9 .icon-shape p,#mermaid-svg-AsBrh3aQbKPZzlY9 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-AsBrh3aQbKPZzlY9 .icon-shape .label rect,#mermaid-svg-AsBrh3aQbKPZzlY9 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-AsBrh3aQbKPZzlY9 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-AsBrh3aQbKPZzlY9 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-AsBrh3aQbKPZzlY9 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 命中
正在执行
未命中
否
是
版本落后
成功
是
否
是
消息到达边界层
幂等键命中?
返回上次结果 · 结束
等待同一结果 · 结束
读取状态与版本号
父消息已到?
进缓冲区等待
按因果序处理
CAS 写入成功?
陈旧写拒绝 · 无副作用结束
版本加一 · 结束
调用下游失败
可重试且预算充足?
退避加抖动后重试
入死信队列 · 告警
熔断已打开?
记审计
4.1 修复一:幂等键与去重存储
要点三条:键的生成规则集中在一个函数里(不允许业务代码自己拼)、去重结果要缓存并返回(重投要拿到上次的结果而不是报错)、去重记录要持久化且带 TTL。
python
# idempotency.py ------ 幂等键生成 + 去重存储
from __future__ import annotations
import asyncio
import hashlib
import json
import time
from dataclasses import dataclass
from typing import Any, Awaitable, Callable
def make_idempotency_key(correlation_id: str, operation: str,
seq: int | str) -> str:
"""生成幂等键------**全局唯一入口**,业务代码不得自行拼接。
规则:
- 同一逻辑操作的所有重投 → 同一个键
- 不同操作 / 不同会话 → 不同的键
- 允许加入"业务内容指纹"以区分不同入参的同名操作
"""
return f"{correlation_id}:{operation}:{seq}"
def key_with_fingerprint(correlation_id: str, operation: str,
payload: dict) -> str:
"""带内容指纹的键:同名操作但入参不同时,不应该被误去重。"""
fp = hashlib.sha256(
json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()
).hexdigest()[:12]
return f"{correlation_id}:{operation}:{fp}"
@dataclass
class _Entry:
result: Any
expire_at: float
state: str # running | done
class IdempotentExecutor:
"""幂等执行器------并发安全,且能正确处理"正在执行中"的重投。
与第 27 篇 process_once 的差别(本次事故补上的三点):
1. 记录 running 状态:并发重投不会重复执行,而是等待同一个结果
2. 结果可序列化缓存:进程重启后仍能命中(需外部存储,此处用内存示意)
3. 统计口径完整:hits / misses / concurrent_waits / expired
"""
def __init__(self, ttl_s: float = 3600.0):
self._entries: dict[str, _Entry] = {}
self._locks: dict[str, asyncio.Lock] = {}
self._guard = asyncio.Lock()
self.ttl_s = ttl_s
self.stats = {"hits": 0, "misses": 0, "waits": 0, "expired": 0}
def _lock_for(self, key: str) -> asyncio.Lock:
if key not in self._locks:
self._locks[key] = asyncio.Lock()
return self._locks[key]
async def execute(self, key: str,
handler: Callable[[], Awaitable[Any]]) -> Any:
now = time.monotonic()
ent = self._entries.get(key)
if ent and ent.expire_at > now:
if ent.state == "done":
self.stats["hits"] += 1
return ent.result
# 正在执行中:等待它完成,而不是再跑一遍
self.stats["waits"] += 1
return await self._wait_done(key, ent)
self.stats["misses"] += 1
async with self._lock_for(key):
ent = self._entries.get(key)
if ent and ent.state == "done" and ent.expire_at > now:
self.stats["hits"] += 1
return ent.result
self._entries[key] = _Entry(None, now + self.ttl_s, "running")
try:
result = await handler()
except Exception:
# 失败不留痕:允许后续重投真正重试
self._entries.pop(key, None)
raise
self._entries[key] = _Entry(result, time.monotonic() + self.ttl_s,
"done")
return result
async def _wait_done(self, key: str, ent: _Entry) -> Any:
deadline = time.monotonic() + 30.0
while time.monotonic() < deadline:
cur = self._entries.get(key)
if cur is None or cur.state == "done":
return cur.result if cur else None
await asyncio.sleep(0.02)
raise TimeoutError(f"等待幂等键 {key} 的执行结果超时")
@property
def hit_rate(self) -> float:
"""幂等命中率------**这是防线有效性指标,不是优化指标**。
长期接近 0 → 要么没有重投(好),要么键设计有问题(坏)。
需要结合"重复投递率"一起看才能区分。
"""
total = self.stats["hits"] + self.stats["misses"]
return self.stats["hits"] / total if total else 0.0
代码说明:
make_idempotency_key是全局唯一入口 ,业务代码不允许 自己拼字符串。这是针对 R2 最直接的修复:把"键怎么生成"从散落在各处的约定,变成一个必须调用的函数。running状态是本次事故补上的关键设计 。第 27 篇的版本只区分"有没有执行过",没有处理"正在执行中又来了一次重投" 。我们的事故里,重投往往发生在原处理还没结束的时候(可见性超时 10s < 处理时间 12s),这时候如果没有 running 态,两次会并发执行。- 失败时
pop掉记录 :执行失败不应该留下"已执行"的痕迹,否则后续重投会被幂等层挡掉,等于失败无法重试。这一条很容易写反。 - ⚠️ 内存字典在进程重启后会丢 。生产环境要去重记录持久化(Redis / DB),并且去重写入必须与业务写入在同一个事务里 ,否则会出现"业务成功但去重记录没写"的窗口------这个窗口在崩溃时正好会漏。
4.2 修复二:版本校验------所有写入走同一个 CAS 入口
python
# versioned_state.py ------ 版本化状态存储(所有写入的唯一入口)
from __future__ import annotations
import asyncio
from dataclasses import dataclass, field
from typing import Any
class StaleWrite(Exception):
"""陈旧写:期望版本落后于实际版本。"""
def __init__(self, key: str, expected: int, actual: int):
self.key, self.expected, self.actual = key, expected, actual
super().__init__(f"陈旧写被拒绝:{key} 期望 v{expected},实际 v{actual}")
@dataclass
class Record:
version: int
data: dict[str, Any]
updated_by: str
causation_id: str | None = None
confidence: float | None = None
reevaluable: bool = False
class VersionedState:
"""版本化状态存储。
修复要点(针对 R3):
1. **只暴露一个写入方法**(compare_and_set),没有"直接赋值"的路
2. 每次读取都返回版本号,调用方必须把它带回下一次写入
3. 陈旧写抛可识别异常,且**绝不产生任何副作用**
4. 冲突计数可观测
"""
def __init__(self):
self._records: dict[str, Record] = {}
self._locks: dict[str, asyncio.Lock] = {}
self.stats = {"writes": 0, "conflicts": 0, "rejected": 0}
def _lock_for(self, key: str) -> asyncio.Lock:
if key not in self._locks:
self._locks[key] = asyncio.Lock()
return self._locks[key]
def read(self, key: str) -> tuple[Record | None, int]:
"""读取返回值与版本号------**版本号必须参与后续写入**。"""
rec = self._records.get(key)
return rec, (rec.version if rec else 0)
async def compare_and_set(self, key: str, expected_version: int,
new_data: dict, *, by: str,
causation_id: str | None = None,
confidence: float | None = None,
reevaluable: bool = False) -> int:
async with self._lock_for(key):
rec = self._records.get(key)
actual = rec.version if rec else 0
if actual != expected_version:
self.stats["conflicts"] += 1
self.stats["rejected"] += 1
raise StaleWrite(key, expected_version, actual)
merged = {**(rec.data if rec else {}), **new_data}
new_v = actual + 1
self._records[key] = Record(
version=new_v, data=merged, updated_by=by,
causation_id=causation_id, confidence=confidence,
reevaluable=reevaluable)
self.stats["writes"] += 1
return new_v
@property
def conflict_rate(self) -> float:
total = self.stats["writes"] + self.stats["rejected"]
return self.stats["rejected"] / total if total else 0.0
代码说明:
read()返回(record, version)的元组形式 ,是为了强迫调用方拿到版本号。返回单个对象的版本我们试过,调用方经常忘记用.version,直接拿旧快照的字段去写。- 没有暴露任何"直接赋值"的方法 ------这是针对 R3 的核心修复:让"绕过 CAS"这件事在技术上不可能发生,与第 40 篇租户隔离"在数据访问层强制注入条件"是同一个思路。
StaleWrite不产生任何副作用 :异常抛出前没有写过任何东西。这一点必须有测试断言(第 27 篇也有这条测试),否则"拒绝"会变成"部分生效"。conflict_rate需要监控 :它为 0 有两种可能------没有并发(好),或者 CAS 被绕过了(坏)。配合压测里的强制冲突注入来确认它真的在工作。
4.3 修复三:因果排序------按因果标识而非时间戳
python
# causal_order.py ------ 因果排序(针对 R4)
from __future__ import annotations
from typing import Any
class CausalSorter:
"""因果排序器------按 causation_id 拓扑排序,而不是按时间戳。
与第 27 篇 causal_history 的差别(本次事故补上的两点):
1. 环检测:消息链出现环时不能死循环
2. 缺失父节点的消息进入缓冲区等待,而不是直接追加到末尾
------ 直接追加会让"父消息晚到"的情况产生乱序
"""
def __init__(self, buffer_ttl_s: float = 30.0):
self._buffer: dict[str, list[dict]] = {}
self.buffer_ttl_s = buffer_ttl_s
self.stats = {"sorted": 0, "buffered": 0, "cycles": 0}
def sort(self, messages: list[dict]) -> list[dict]:
by_id = {m["message_id"]: m for m in messages}
children: dict[str, list[dict]] = {}
roots: list[dict] = []
for m in messages:
p = m.get("causation_id")
if p and p in by_id:
children.setdefault(p, []).append(m)
elif p:
# 父消息还没到 → 进缓冲区,不参与本次排序
self._buffer.setdefault(p, []).append(m)
self.stats["buffered"] += 1
else:
roots.append(m)
ordered: list[dict] = []
visited: set[str] = set()
on_stack: set[str] = set()
def walk(node: dict) -> None:
nid = node["message_id"]
if nid in visited:
return
if nid in on_stack:
self.stats["cycles"] += 1
return
on_stack.add(nid)
ordered.append(node)
visited.add(nid)
for c in children.get(nid, []):
walk(c)
on_stack.discard(nid)
for r in roots:
walk(r)
# 环里的节点(未被访问到的)按消息标识稳定追加,保证不丢
leftovers = [m for m in messages if m["message_id"] not in visited]
ordered.extend(leftovers)
self.stats["sorted"] = len(ordered)
return ordered
def drain_ready(self, newly_arrived_ids: set[str]) -> list[dict]:
"""父消息到达后,把缓冲区里等它的消息放出来。"""
ready = []
for pid in list(self._buffer.keys()):
if pid in newly_arrived_ids:
ready.extend(self._buffer.pop(pid))
return ready
代码说明:
on_stack做环检测 ------第 27 篇的实现用seen防重复但遇到环会丢节点。Agent 场景里环是真实存在的 (A 问 B、B 反问 A),必须显式处理而不是死循环或静默丢消息。- 父消息未到达时进缓冲区而不是追加到末尾 ,这是针对事故里"父消息晚到"场景的修复。直接追加(第 27 篇的做法)在父消息晚到时会产生乱序------我们的事故里就有 890 次这种情况。
drain_ready需要被调用方配合 :新消息到达时检查缓冲区。这是因果排序器唯一的"状态" ,也意味着它是有状态的组件,需要按correlation_id分片管理。- ⚠️ 缓冲区必须有 TTL 。父消息永远不到(发它的 Agent 挂了)时,缓冲区会无限增长。
buffer_ttl_s到期后应该把消息转入死信队列并告警。
4.4 修复四:重试预算 + 退避抖动------把放大倍数压住
python
# retry_budget.py ------ 重试预算与熔断(针对 R5)
from __future__ import annotations
import asyncio
import random
import time
class RetryBudget:
"""重试预算------限制"重试请求占总请求的比例",而非限制次数。
为什么是预算而不是次数:次数上限在故障率高时仍然会放大。
例如失败率 50%、每请求重试 3 次 → 总请求量变成 2.5 倍。
预算直接对"总量"设限:重试最多占总量的 20%。
"""
def __init__(self, ratio: float = 0.2, window_s: float = 10.0,
min_tokens: int = 10):
self.ratio = ratio
self.window_s = window_s
self.min_tokens = min_tokens
self._tokens = float(min_tokens)
self._updated = time.monotonic()
self.stats = {"granted": 0, "denied": 0}
def _refill(self) -> None:
now = time.monotonic()
elapsed = now - self._updated
# 按窗口补充:每窗口允许 ratio 比例的重试
self._tokens = min(self.min_tokens * 10,
self._tokens + elapsed / self.window_s
* self.min_tokens)
self._updated = now
def try_spend(self) -> bool:
self._refill()
if self._tokens >= 1:
self._tokens -= 1
self.stats["granted"] += 1
return True
self.stats["denied"] += 1
return False
def backoff_delay(attempt: int, base: float = 0.2, cap: float = 8.0,
jitter: float = 0.5) -> float:
"""指数退避 + 抖动。
AWS 建议的 full jitter 形式:sleep = random(0, min(cap, base * 2^n))
抖动的作用是打散"同时失败同时重试"的惊群。
"""
ceiling = min(cap, base * (2 ** attempt))
return random.uniform(0, ceiling * jitter) + ceiling * (1 - jitter)
class CircuitBreaker:
"""熔断器------下游持续失败时快速失败,不再消耗资源。"""
def __init__(self, error_threshold: float = 0.5, min_calls: int = 20,
open_s: float = 30.0, half_open_calls: int = 3):
self.error_threshold = error_threshold
self.min_calls = min_calls
self.open_s = open_s
self.half_open_calls = half_open_calls
self._state = "closed"
self._opened_at = 0.0
self._window = {"calls": 0, "errors": 0, "at": time.monotonic()}
self._half_open_seen = 0
@property
def state(self) -> str:
if self._state == "open" and \
time.monotonic() - self._opened_at > self.open_s:
return "half_open"
return self._state
def allow(self) -> bool:
st = self.state
if st == "open":
return False
if st == "half_open":
return self._half_open_seen < self.half_open_calls
return True
def record(self, ok: bool) -> None:
w = self._window
w["calls"] += 1
if not ok:
w["errors"] += 1
if time.monotonic() - w["at"] > 10.0: # 滚动窗口
w.update({"calls": 0, "errors": 0, "at": time.monotonic()})
if self._state == "half_open":
self._half_open_seen += 1
if ok and self._half_open_seen >= self.half_open_calls:
self._state, self._half_open_seen = "closed", 0
elif not ok:
self._state, self._opened_at = "open", time.monotonic()
return
if w["calls"] >= self.min_calls:
rate = w["errors"] / w["calls"]
if rate >= self.error_threshold:
self._state, self._opened_at = "open", time.monotonic()
async def call_with_resilience(fn, *, budget: RetryBudget,
breaker: CircuitBreaker,
max_attempts: int = 3,
retryable=lambda e: True):
"""组合使用:熔断在最外层,重试在内层。
顺序很重要:**熔断在外、重试在内**。
反过来的话,重试会把熔断挡住的请求再发一遍,熔断等于失效。
"""
last: Exception | None = None
for attempt in range(max_attempts):
if not breaker.allow():
raise RuntimeError("下游已熔断,快速失败")
try:
result = await fn()
breaker.record(True)
return result
except Exception as e: # noqa: BLE001
breaker.record(False)
last = e
if not retryable(e) or attempt == max_attempts - 1:
break
if not budget.try_spend():
break # 预算耗尽 → 快速失败
await asyncio.sleep(backoff_delay(attempt))
raise last if last else RuntimeError("未知失败")
代码说明:
RetryBudget限制的是"比例"而不是"次数" 。这是 Google SRE 的建议:次数上限在高失败率下仍然放大(失败率 50% + 每请求 3 次重试 = 总量 2.5 倍),而比例上限直接对总量封顶。backoff_delay用 full jitter 形式 (random(0, ceiling)的变体)。抖动是必需的 :没有抖动,所有客户端会在同一时刻重试,形成惊群------这正是我们事故里"03:20 停掉消费者后重启又立刻被打垮"的原因。- 熔断在外、重试在内 的顺序必须写进注释并在测试里锁定。反过来(重试在外)会让熔断完全失效。
- ⚠️
retryable判定不能省 :4xx、参数校验失败、鉴权失败一律不重试 (重试只会再来一次失败,还额外消耗预算)。这是第 39 篇的标准,在这里变成了代码。
4.5 修复五:只在一个边界层重试 + 死信队列
这是把放大从 27 压到 3 的关键一条,不是代码问题而是架构约定:
| 层 | 是否重试 | 失败时做什么 |
|---|---|---|
| 入口层(离用户/队列最近的消费者) | ✅ 重试(带预算 + 退避 + 抖动) | 超预算 → 入死信队列 |
| 内部 Agent → Agent 调用 | ❌ 快速失败 | 抛错,由入口层决定 |
| Agent → 工具/下游服务 | ❌ 快速失败(除明确幂等的读操作) | 抛错 |
python
# boundary.py ------ 边界层消费者:唯一允许重试的地方
from __future__ import annotations
import asyncio
import logging
from idempotency import IdempotentExecutor, make_idempotency_key
from retry_budget import CircuitBreaker, RetryBudget, call_with_resilience
from versioned_state import StaleWrite, VersionedState
logger = logging.getLogger("boundary")
class BoundaryConsumer:
"""边界消费者:整个系统里唯一允许重试的地方。
四件事必须在这里做完(顺序不能变):
1. 幂等(同一逻辑只执行一次)
2. 版本校验(读-改-写带版本号)
3. 因果排序(按 causation_id 而非时间戳)
4. 重试预算 + 熔断(放大在这里被封顶)
"""
def __init__(self):
self.idem = IdempotentExecutor()
self.state = VersionedState()
self.budget = RetryBudget(ratio=0.2)
self.breaker = CircuitBreaker()
self.dlq: list[dict] = []
async def handle(self, msg: dict) -> None:
key = make_idempotency_key(msg["correlation_id"],
msg["operation"], msg["seq"])
try:
await self.idem.execute(key, lambda: self._process(msg))
except StaleWrite as e:
# 陈旧写:不是错误,是"别人已经写过了",直接丢弃
logger.info("丢弃陈旧写:%s(期望 v%d 实际 v%d)",
e.key, e.expected, e.actual)
except Exception as e: # noqa: BLE001
await self._to_dlq(msg, reason=str(e))
async def _process(self, msg: dict) -> None:
rec, version = self.state.read(msg["state_key"])
outcome = await call_with_resilience(
lambda: self._do_work(msg, rec),
budget=self.budget, breaker=self.breaker, max_attempts=3,
retryable=lambda e: not isinstance(e, StaleWrite))
await self.state.compare_and_set(
msg["state_key"], version, outcome,
by=msg["sender"], causation_id=msg["message_id"],
confidence=outcome.get("confidence"))
async def _do_work(self, msg: dict, rec) -> dict:
await asyncio.sleep(0.05)
return {"status": "ok", "confidence": 0.8}
async def _to_dlq(self, msg: dict, reason: str) -> None:
self.dlq.append({**msg, "dlq_reason": reason})
logger.warning("消息进入死信队列:%s / %s", msg["message_id"], reason)
代码说明:
- 四个机制汇聚在一个入口 (
handle),顺序是固定的。这是 3.7 节"把机制变成不可绕过的执行路径"的具体落地。 StaleWrite被当作正常情况处理 (记日志后丢弃),而不是错误。因为它本来就不是错误------它意味着"别的执行已经写过了",这正是我们想要的行为。- 死信队列(DLQ)是必需的 :预算耗尽、重试超限的消息必须有地方去,不能无限重试也不能静默丢弃。DLQ 里的消息要有告警和人工处理流程。
- ⚠️
_process里的version是在call_with_resilience之前读的 ,如果重试期间状态被改,CAS 会拒绝------这是正确的,重试会用新的版本号再来一次(由入口层的幂等键保证不会重复执行)。
4.6 修复后的实测效果
在同一套压测环境(注入"依赖变慢 15 倍" + 注入 30% 重复投递 + 注入乱序)下的对比:
| 指标 | 修复前 | 修复后 | 改善 |
|---|---|---|---|
| 消息放大倍数 | 27.4 | 2.8 | ↓ 89.8% |
| 幂等命中率 | 4% | 96% | 防线真正生效 |
| 状态版本回退次数 | 2,140 | 0 | 根除 |
| 因果序违反次数 | 890 | 0 | 根除 |
| 重复外部通知 | 3,218 | 0 | 根除(不可逆动作被守住) |
| 故障持续时间 | 212 分钟 | 8 分钟 | ↓ 96.2% |
| 正常吞吐(无故障时) | 480 条/分 | 475 条/分 | 基本无损失 |
最后一行是本次修复最值得强调的 :加了这么多层防护,正常吞吐只掉了约 1% 。这说明这些机制的成本主要发生在故障时 ,平时几乎免费------这与第 40 篇"分层限流后批量吞吐几乎不降"是同一个结论:防护的代价不该由正常路径承担。

图2:五道修复防线的分工与代价------每道防线各自拦住哪一类损害
4.7 消息处理状态机(修复后)
#mermaid-svg-juW9q4zZ7SqlNx2G{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-juW9q4zZ7SqlNx2G .error-icon{fill:#552222;}#mermaid-svg-juW9q4zZ7SqlNx2G .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-juW9q4zZ7SqlNx2G .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-juW9q4zZ7SqlNx2G .marker{fill:#333333;stroke:#333333;}#mermaid-svg-juW9q4zZ7SqlNx2G .marker.cross{stroke:#333333;}#mermaid-svg-juW9q4zZ7SqlNx2G svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-juW9q4zZ7SqlNx2G p{margin:0;}#mermaid-svg-juW9q4zZ7SqlNx2G defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-juW9q4zZ7SqlNx2G g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-juW9q4zZ7SqlNx2G g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-juW9q4zZ7SqlNx2G g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-juW9q4zZ7SqlNx2G g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-juW9q4zZ7SqlNx2G g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-juW9q4zZ7SqlNx2G .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-juW9q4zZ7SqlNx2G .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-juW9q4zZ7SqlNx2G .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-juW9q4zZ7SqlNx2G .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-juW9q4zZ7SqlNx2G .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-juW9q4zZ7SqlNx2G .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-juW9q4zZ7SqlNx2G .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-juW9q4zZ7SqlNx2G .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-juW9q4zZ7SqlNx2G .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-juW9q4zZ7SqlNx2G .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-juW9q4zZ7SqlNx2G .edgeLabel .label text{fill:#333;}#mermaid-svg-juW9q4zZ7SqlNx2G .label div .edgeLabel{color:#333;}#mermaid-svg-juW9q4zZ7SqlNx2G .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-juW9q4zZ7SqlNx2G .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-juW9q4zZ7SqlNx2G .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-juW9q4zZ7SqlNx2G .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-juW9q4zZ7SqlNx2G .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-juW9q4zZ7SqlNx2G .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-juW9q4zZ7SqlNx2G .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-juW9q4zZ7SqlNx2G #statediagram-barbEnd{fill:#333333;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-juW9q4zZ7SqlNx2G .cluster-label,#mermaid-svg-juW9q4zZ7SqlNx2G .nodeLabel{color:#131300;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-juW9q4zZ7SqlNx2G .note-edge{stroke-dasharray:5;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-note text{fill:black;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram-note .nodeLabel{color:black;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagram .edgeLabel{color:red;}#mermaid-svg-juW9q4zZ7SqlNx2G #dependencyStart,#mermaid-svg-juW9q4zZ7SqlNx2G #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-juW9q4zZ7SqlNx2G .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-juW9q4zZ7SqlNx2G :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 消息到达
幂等键命中
直接返回上次结果
同键正在执行
等待其完成
首次处理
等到结果
父消息未到
等待因果前序
父消息到达(drain)
缓冲超时
CAS 成功
版本 +1
版本落后
陈旧写被拒(无副作用)
可重试错误且预算充足
预算耗尽或达到上限
退避加抖动后重试
预算耗尽
无副作用返回
无副作用丢弃
告警 + 人工处理
RECEIVED
DEDUPED
RUNNING_WAIT
PROCESSING
BUFFERED
DLQ
APPLIED
STALE_REJECTED
RETRYING
陈旧写不是错误
它意味着别人已经写过了
必须无副作用地丢弃
死信队列必须有告警
静默丢弃等于埋雷
图里新增的三个状态是本次修复的核心 :RUNNING_WAIT(并发重投等待同一结果)、BUFFERED(父消息未到时等待)、STALE_REJECTED(陈旧写无副作用拒绝)。第 27 篇的状态机里没有这三个状态,而它们恰恰是"协议生效"和"协议存在"的差别所在。
五、进阶防护
5.1 污染数据怎么修:事件溯源重放
事故发生后最现实的问题是:1.2 万条已经被写坏的状态怎么办? 三种方案的对比:
| 方案 | 做法 | 适用 | 代价 |
|---|---|---|---|
| 全量重算 | 从原始工单重新跑一遍 | 计算便宜、无副作用 | 会重新触发通知(危险) |
| 事件溯源重放 | 按因果序重放事件流,重放时关闭副作用 | 有副作用动作的推荐做法 | 需要事件日志 |
| 人工订正 | 逐条核对 | 数量少、影响极大 | 人力 |
我们用的是第二种,且有一个关键动作:重放时把 Notification 类工具替换为"空实现(null sink)"。 这样既能重建出正确的状态,又不会第二次打扰客户。
⚠️ 重放必须按因果序,不能按时间戳。 用被污染的时间戳顺序重放,会得到同样被污染的结果------这是 R4 在灾后重建阶段的一次复现 。我们第一次重放就犯了这个错,重放完发现 900 多条仍然不对,改用因果序后才干净。这也是我把"重放必须用排序器的同一个函数"写进事故改进项的原因。
5.2 六个必看指标
| 指标 | 健康值 | 异常含义 | 为什么必看 |
|---|---|---|---|
| 消息放大倍数 | 1.0~1.3 | >3 即重试放大 | 雪崩的唯一先行指标 |
| 幂等命中率 | 结合重复投递率看 | 长期 0 = 键设计有问题 | 防线有效性 |
| 版本冲突率 | <5% | 为 0 可能是 CAS 被绕过 | 需配合强制冲突注入验证 |
| 因果序违反数 | 0 | 非 0 即有链路被时间戳污染 | 静默错乱,无其它症状 |
| 重试占请求比 | <20% | 持续高位 = 下游不健康 | 预算是否生效 |
| DLQ 堆积量 | 接近 0 | 增长 = 有持续失败未被处理 | 静默丢弃的兜底 |
"放大倍数"是唯一能提前预警雪崩的指标。 其它五个都是"已经出问题"的信号,而放大倍数在故障扩大之前 就会上升(我们的事故里,02:13 放大倍数已经到 4,而业务告警 02:16 才响)。给它设一条 >3 的告警线,能换来 3 分钟的提前量。

图3:六个观测指标速查卡------健康阈值与异常含义的对照
5.3 混沌测试:把三类注入做成 CI 用例
python
# tests/test_chaos.py ------ 三类注入的一致性测试
import asyncio
import pytest
from idempotency import IdempotentExecutor, make_idempotency_key
from versioned_state import StaleWrite, VersionedState
from causal_order import CausalSorter
from forensics.detectors import (detect_duplicate_delivery,
detect_version_regression,
detect_causal_violation)
@pytest.mark.asyncio
async def test_redelivery_does_not_duplicate_side_effect():
"""注入:同一逻辑操作重投 20 次(含并发)→ 副作用只能发生一次。"""
idem = IdempotentExecutor()
calls = {"n": 0}
async def handler():
calls["n"] += 1
await asyncio.sleep(0.05) # 制造并发窗口
return {"done": True}
key = make_idempotency_key("TK-1", "diagnose", 1)
results = await asyncio.gather(*[idem.execute(key, handler) for _ in range(20)])
assert calls["n"] == 1, f"副作用发生了 {calls['n']} 次"
assert len(set(map(str, results))) == 1, "重投应返回相同结果"
@pytest.mark.asyncio
async def test_stale_write_rejected_without_side_effect():
"""注入:基于过期快照的写入必须被拒,且不留下任何污染。"""
st = VersionedState()
await st.compare_and_set("k", 0, {"v": 1}, by="a")
await st.compare_and_set("k", 1, {"v": 2}, by="b")
before = dict(st.read("k")[0].data)
with pytest.raises(StaleWrite):
await st.compare_and_set("k", 0, {"v": 999}, by="stale")
assert st.read("k")[0].data == before, "被拒绝的写入不得改变状态"
def test_causal_order_survives_shuffled_delivery():
"""注入:乱序投递 → 排序结果必须与因果链一致。"""
msgs = [
{"message_id": "m3", "causation_id": "m2", "correlation_id": "C"},
{"message_id": "m1", "causation_id": None, "correlation_id": "C"},
{"message_id": "m2", "causation_id": "m1", "correlation_id": "C"},
]
ordered = CausalSorter().sort(msgs)
assert [m["message_id"] for m in ordered] == ["m1", "m2", "m3"]
assert detect_causal_violation(ordered)["verdict"] == "OK"
def test_detectors_pass_on_clean_history():
"""三个检测器在干净历史上必须返回 OK------防止检测器本身失灵。"""
clean = [{"message_id": f"m{i}", "idempotency_key": f"C:op:{i}"}
for i in range(5)]
assert detect_duplicate_delivery(clean)["verdict"] == "OK"
代码说明:
- 第一个测试是本次事故最重要的一条守门 :20 次并发重投只产生 1 次副作用。注意里面刻意加了
asyncio.sleep(0.05)制造并发窗口 ------没有这个 sleep,测试可能"碰巧"通过(串行执行时即使没有 running 态也只执行一次)。注入并发窗口是这类测试的必要条件。 - 第二个测试断言"被拒绝的写入不得改变状态",这是第 27 篇就有的要求,在本次事故后我们把它提升为必测项。
- 第四个测试是给检测器做测试 ------听起来多余,但我们在事故后确实发现一个检测器的判据写反了。检测失灵比没有检测更危险,因为它给你虚假的安全感。
5.4 跨实例部署时的一致性
本文的实现都是单进程内的(asyncio.Lock、内存字典)。多实例部署时:
| 机制 | 单进程 | 多实例 | 建议 |
|---|---|---|---|
| 幂等去重 | 内存字典 | Redis / DB(必须共享) | 必须共享,且与业务写入同事务 |
| 版本校验 | asyncio.Lock + CAS | DB 的 CAS(原子 UPDATE) | 用数据库原子操作,别用分布式锁 |
| 因果排序 | 进程内排序器 | 按 correlation_id 分片 + 会话粘滞 |
与第 40 篇一致:粘滞优先于分布式锁 |
| 重试预算 | 进程内令牌 | Redis 令牌桶(原子 Lua) | 全局预算才有效(否则 N 个实例放大 N 倍) |
| 熔断 | 进程内 | 进程内即可(每个实例独立熔断是合理的) | 无需共享 |
两条关键判断:
- 幂等与版本必须跨实例共享 ,因为它们保护的是共享状态;熔断不需要共享,每个实例独立判断反而能更快止损。
- 重试预算必须全局共享 。如果每个实例各自持有 20% 的预算,10 个实例就是 200%------预算在最需要它的时候失效。
💡 "会话粘滞优先于分布式锁"这条与第 40 篇的结论一致 :把协调问题转化为路由问题,复杂度低一个数量级。不要一上来就上分布式锁------它带来锁超时、续期、Redis 故障等一串新问题,而 P99 只涨了 30 毫秒的收益却很小。
六、适用边界与风险提示 ⚠️
6.1 这套防护适合什么
✅ 跨进程/通过消息协作的多 Agent 系统------本文的全部前提是"至少有一个消息队列或异步链路"。
✅ 有共享状态且会被并发写的场景------版本校验的收益与并发写频率成正比。
✅ 有不可逆副作用的下游(发通知、下单、付款)------重试预算与幂等的价值在这里最大。
✅ Agent 结论具有不确定性(LLM 输出)------这正是陈旧写特别危险的原因(3.4 节)。
6.2 什么时候不需要这么复杂
❌ 同进程内的 Agent 协作 (第 22~26 篇):直接共享对象,不存在重复投递与版本问题。引入消息层是纯粹的负担。
❌ Agent 数量 ≤ 3、关系固定、无重试:硬编码调用链即可,第 27 篇已经说过这一点。
❌ 纯函数式任务(无状态、无副作用) :重复执行无害,幂等层是浪费。判断标准:这条消息执行两次,现实世界会有变化吗?
❌ 能确定不会并发写同一个 key :版本校验层可以省。但要注意"能确定"这三个字------我们的事故里,大家也都以为能确定。
6.3 五个典型陷阱

图4:本次雪崩事故复盘三段式------现象、根因、对策与共性后果
陷阱一:把幂等键的生成散落在业务代码里。 一定会被写错。收敛到一个函数,加 lint 规则禁止字符串拼接。
陷阱二:CAS 只覆盖了"一部分"写入路径。 我们的事故就是这样:认领用了 CAS,结论写入没有 。修复方式不是"再加一处 CAS",而是只暴露 CAS 一个写入方法。
陷阱三:下游排序用了时间戳。 协议层再正确,也会被一处 ORDER BY timestamp 作废。审计表、回放表、日志表都要检查。
陷阱四:重试写在多个层。 放大是乘积。规定只有边界层能重试,内部层快速失败。
陷阱五:死信队列没有告警。 DLQ 静默堆积等于"消息被悄悄丢了",比报错更糟。DLQ 深度必须告警。
⚠️ 还有一个配置层面的坑,值得单独列出来 :消费者的可见性超时必须大于最大处理时间 (3.2 节)。我们当时的配置是 10 秒 vs 实际 12 秒,导致 100% 的消息在处理中被重投 。这个配置项通常不在代码里,而在 broker 的配置或 IaC 里,因此它特别容易在评审时被漏掉。
七、一个可复制的最小骨架
如果只做一件事,做"幂等 + 版本"这两条(它们防住的是 1.2 万条污染数据的直接原因)。下面约 60 行:
python
# minimal_safe_bus.py ------ 约 60 行,零依赖
from __future__ import annotations
import asyncio
import time
from typing import Any, Awaitable, Callable
class StaleWrite(Exception):
pass
class SafeBus:
"""最小安全消息总线:幂等 + 版本 + 放大封顶。
三条规则(缺一条都会出事):
1. 同一逻辑操作的所有重投 → 同一个幂等键
2. 所有写入 → 走 CAS,带期望版本号
3. 只在边界重试 → 且总次数封顶
"""
def __init__(self, max_attempts: int = 3, ttl_s: float = 3600.0):
self._idem: dict[str, tuple[Any, float]] = {}
self._state: dict[str, tuple[int, dict]] = {}
self._locks: dict[str, asyncio.Lock] = {}
self.max_attempts = max_attempts
self.ttl_s = ttl_s
self.stats = {"hits": 0, "misses": 0, "stale": 0}
def _lock(self, key: str) -> asyncio.Lock:
if key not in self._locks:
self._locks[key] = asyncio.Lock()
return self._locks[key]
# rule 1: 键必须跨重投稳定------不要在这里出现时间戳或随机数
@staticmethod
def idem_key(correlation_id: str, op: str, seq: int | str) -> str:
return f"{correlation_id}:{op}:{seq}"
async def once(self, key: str, fn: Callable[[], Awaitable[Any]]) -> Any:
"""幂等执行:同键只真正执行一次,重投返回上次结果。"""
hit = self._idem.get(key)
if hit and hit[1] > time.monotonic():
self.stats["hits"] += 1
return hit[0]
self.stats["misses"] += 1
async with self._lock(key):
hit = self._idem.get(key)
if hit and hit[1] > time.monotonic():
return hit[0]
res = await fn()
self._idem[key] = (res, time.monotonic() + self.ttl_s)
return res
def read(self, key: str) -> tuple[dict, int]:
"""读取状态与版本号------版本号必须带进下一次写入。"""
ver, data = self._state.get(key, (0, {}))
return dict(data), ver
async def write(self, key: str, expected: int, patch: dict) -> int:
"""rule 2: 版本匹配的写入才生效。"""
async with self._lock(key):
ver, data = self._state.get(key, (0, {}))
if ver != expected:
self.stats["stale"] += 1
raise StaleWrite(f"{key}: 期望 v{expected} 实际 v{ver}")
merged = {**data, **patch}
self._state[key] = (ver + 1, merged)
return ver + 1
async def handle(self, msg: dict, work: Callable[[dict], Awaitable[dict]]) -> None:
"""边界入口:唯一允许重试的地方(放大在这里被封顶)。"""
key = self.idem_key(msg["correlation_id"], msg["op"], msg["seq"])
async def _wrapped():
data, ver = self.read(msg["state_key"])
for attempt in range(self.max_attempts):
try:
patch = await work(msg)
return await self.write(msg["state_key"], ver, patch)
except StaleWrite:
raise # 陈旧写不重试,直接丢弃
except Exception: # noqa: BLE001
if attempt == self.max_attempts - 1:
raise
await asyncio.sleep(0.2 * (2 ** attempt)) # 退避
try:
await self.once(key, _wrapped)
except StaleWrite:
pass # 正常:别人已经写过了
使用要点三条:
idem_key里绝不允许出现时间戳、随机数、message_id。 这是 R2 的全部教训,也是最容易在后续迭代中被"顺手改坏"的地方------建议加一条 lint 规则或单元测试锁定它。read返回的版本号必须原样带回write。 不要在中间重新读一次再写------那正是陈旧写的来源。StaleWrite在handle里被吞掉(pass)而不是抛出 。因为它的语义是"别人已经写过了",不是错误。把它当错误上报会淹没真正的告警。
八、总结
回到那次事故:一条消息被重复投递,因为幂等键每次都不同而被执行了 17 次;其中一次晚到的执行拿着旧快照写回了状态,把 v5 覆盖成 v3;下游基于错误状态继续派单;三层各自重试 3 次把 1 条消息放大成 27 次外部副作用;最终 4 小时 12 分的不可用和 3218 条收不回来的通知。
五个最该记住的结论:
第一,协议字段存在 ≠ 协议生效。 幂等键、版本号、因果标识三个字段我们一个不少,三个机制一个没生效。区别不在协议,在执行路径------修复的方向是"让绕过在技术上不可能",而不是"再写一份更详细的协议文档"。
第二,幂等键必须跨重投稳定,这是唯一规则。 键里出现时间戳、随机数、message_id,幂等层就是空转的。把它收敛成一个函数,并监控命中率 ------命中率长期为 0,要么是没重投,要么是键错了,这两者必须靠"重复投递率"一起看才能区分。
第三,陈旧写在 Agent 场景比普通业务更危险,因为旧结论看起来仍然合理。 根因推断从"配置漂移"变回"资源耗尽",没有人会觉得不对。所以必须靠版本号机械拒绝,不能靠"看起来合不合理"。
第四,重试的放大是乘积,所以只能在一个边界层重试。 三层各 3 次就是 27 倍。加退避、加抖动、加预算、加熔断,四者缺一不可------但最有效的一条是架构约定:内部层快速失败。
第五,放大倍数是唯一能提前预警雪崩的指标。 我们的事故里它在业务告警响起前 3 分钟就开始上升了。给"消息放大倍数 > 3"设一条告警,是这次事故换来的最便宜的一条改进。
最后一句 :这些防护在正常路径上的成本约为 1% 的吞吐 (4.6 节最后一行)。真正贵的不是加防护,而是在没有防护的情况下出一次事故 ------1.2 万条污染数据、3218 条不可逆通知、4 小时不可用。如果你的 Agent 系统已经上了消息队列,那么本文的三个检测脚本(2.5 节)值得今天就跑一遍:它们不需要改任何生产代码,就能告诉你这五个根因里你正在犯哪几个。
落地自检清单(Checklist)
- ✅ 幂等键由唯一函数生成,不含时间戳 / 随机数 / message_id
- ✅ 幂等去重能处理**"正在执行中又来一次重投"**(running 态)
- ✅ 幂等去重记录持久化,且与业务写入同事务
- ✅ 监控幂等命中率,并结合重复投递率判读
- ✅ 所有 状态写入走同一个 CAS 入口,不存在直接赋值路径
- ✅ 陈旧写抛可识别异常 ,且无副作用(有测试断言)
- ✅ 冲突被引发时不重试(直接丢弃)
- ✅ 排序只用 causation_id,时间戳仅用于观测
- ✅ 审计表 / 回放表 / 日志表的排序也已排查(不只是内存)
- ✅ 因果排序器有环检测 与父消息未到的缓冲
- ✅ 缓冲区有 TTL,超时转 DLQ
- ✅ 重试只发生在一个边界层,内部层快速失败
- ✅ 重试有指数退避 + 抖动 + 上限
- ✅ 有重试预算(比例上限,且多实例时全局共享)
- ✅ 熔断在外、重试在内(有测试锁定)
- ✅ 4xx / 鉴权 / 校验失败不重试
- ✅ 消费者可见性超时 > 最大处理时间
- ✅ 有死信队列,且 DLQ 深度有告警
- ✅ 监控六项:放大倍数、幂等命中率、冲突率、因果违反数、重试占比、DLQ 深度
- ✅ 三类注入(重复 / 乱序 / 陈旧写)已进入 CI 混沌测试
常见问题(FAQ)
Q1:能不能直接上 exactly-once 语义来避免重复投递?
能,但通常不划算。 exactly-once 需要事务性投递 + 幂等消费者 + 去重存储三层配合,成本高且会降低吞吐。Kafka 等系统的标准建议是"幂等消费者 + at-least-once"------这一层就能解决 95% 的问题。 而且真正的 exactly-once 也要求消费者侧幂等(否则事务提交与副作用之间仍有窗口),所以幂等这层无论如何都省不掉。
Q2:幂等命中率多少算健康?
不能孤立地看。 命中率 = 重投次数 / 总处理次数。健康的关系是:命中率应该与"重复投递率"接近 。如果重复投递率是 30% 而命中率是 4%,说明幂等键有问题(我们事故的真实数据);如果两者都接近 30%,说明幂等工作正常。所以这两个指标必须成对监控。
Q3:版本冲突应该重试吗?
不应该。 版本冲突的语义是"别人已经在我读取之后写过了",重试只是拿一个更新的版本号再算一遍------通常不需要,因为它要重新跑一遍 LLM(贵) 。正确做法是:丢弃本次写入 (它的数据已经过时了)。如果业务上确实需要重算,应该由入口层发起一次新的逻辑操作,而不是在同一次处理里重试 CAS。
Q4:为什么不能用时间戳排序?用 NTP 同步时钟不行吗?
不行。 NTP 能做到的精度是毫秒级(同机房),而 Agent 消息的间隔常常也是毫秒级甚至亚毫秒级。我们事故里两台机器差 40ms,消息间隔 5ms------时钟误差比消息间隔大一个数量级。 而且跨机房、跨云时误差更大。时间戳是物理测量值,因果是逻辑事实(谁引用了谁)------后者永远不会错。
Q5:重试预算的 20% 是怎么定的?
经验起点,需要按自己的依赖特性调。 Google SRE 的建议量级是 10%~20%。调的依据是"下游能承受多少额外负载" :如果下游已经满载,额外的 20% 也会压垮它,那就该降到 5%。判断方法是压测:逐步提高预算,看下游的错误率什么时候开始恶化。
Q6:熔断应该每个实例独立还是全局共享?
独立即可,而且更好。 熔断的目的是"这个实例别再往死掉的下游发请求",每个实例独立判断能更快止损 ,而且不需要跨实例协调(省掉了 Redis 依赖和一致性问题)。而重试预算必须全局共享------10 个实例各持 20% 预算,等于 200%。
Q7:多实例部署时版本校验怎么做?
用数据库的原子 CAS(UPDATE ... WHERE version = ?),不要自己实现分布式锁。 数据库已经帮你解决了原子性问题,而分布式锁会带来超时、续期、锁服务故障等一串新问题。第 40 篇的结论在这里同样适用:优先把协调问题转化为单机/路由问题。
Q8:怎么验证我的幂等层真的在工作,而不是空转?
注入一次重复投递,看三件事 :① 副作用计数是否只增加 1;② stats["hits"] 是否 +1;③ 第二次返回的结果是否与第一次相同。三个都满足才算通过。 只验证第 ① 条不够------有些实现会"执行两次但只返回一次结果",副作用仍然发生了。 建议在 CI 里把这个测试跑在并发条件下(5.3 节第一个测试)。
参考资料
- Google SRE Book --- Addressing Cascading Failures (雪崩、重试放大、队列与负载丢弃):https://sre.google/sre-book/addressing-cascading-failures/
- Google SRE Book --- Handling Overload (负载丢弃、背压与优雅降级):https://sre.google/sre-book/handling-overload/
- Amazon Builders' Library --- Timeouts, retries and backoff with jitter (抖动、单层重试、熔断建议):https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
- Amazon Builders' Library --- Making retries safe with idempotent APIs (幂等 API 与重试安全):https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
- Lamport, L. --- Time, Clocks, and the Ordering of Events in a Distributed System (因果序的经典论文,本文因果排序的理论来源):https://lamport.azurewebsites.net/pubs/time-clocks.pdf
- Apache Kafka 官方文档 --- Message Delivery Semantics (at-least-once / exactly-once 与幂等生产者):https://kafka.apache.org/documentation/#semantics
- RabbitMQ 官方文档 --- Consumer Acknowledgements and Publisher Confirms (可见性超时与重投机制):https://www.rabbitmq.com/docs/confirms
- Nygard, M. T. --- Release It! (舱壁、熔断、稳态模式,本文隔离设计的思想来源):https://pragprog.com/titles/mnee2/release-it-second-edition/
- Kleppmann, M. --- Designing Data-Intensive Applications (一致性模型、因果一致、幂等与并发控制):添加链接描述
- Microsoft Azure Architecture Center --- Retry pattern (重试策略的分类与参数建议):https://learn.microsoft.com/en-us/azure/architecture/patterns/retry