多 Agent 通信灾难:状态不一致导致雪崩故障的排查与防护

摘要 :凌晨两点,我们的工单处理 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 篇已经把这条讲透了,这里补充事故里的两个具体教训:

  1. 协议层正确 ≠ 全链路正确。 我们在内存里用 causal_history 排序,但审计表落盘用了 ORDER BY timestamp_ms ,下游回放读了这份表。一个"顺手"的排序把整个协议的努力作废了。
  2. 并发旁支(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 倍)
熔断 进程内 进程内即可(每个实例独立熔断是合理的) 无需共享

两条关键判断:

  1. 幂等与版本必须跨实例共享 ,因为它们保护的是共享状态;熔断不需要共享,每个实例独立判断反而能更快止损。
  2. 重试预算必须全局共享 。如果每个实例各自持有 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                               # 正常:别人已经写过了

使用要点三条:

  1. idem_key 里绝不允许出现时间戳、随机数、message_id。 这是 R2 的全部教训,也是最容易在后续迭代中被"顺手改坏"的地方------建议加一条 lint 规则或单元测试锁定它。
  2. read 返回的版本号必须原样带回 write。 不要在中间重新读一次再写------那正是陈旧写的来源。
  3. 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 节第一个测试)。


参考资料

  1. Google SRE Book --- Addressing Cascading Failures (雪崩、重试放大、队列与负载丢弃):https://sre.google/sre-book/addressing-cascading-failures/
  2. Google SRE Book --- Handling Overload (负载丢弃、背压与优雅降级):https://sre.google/sre-book/handling-overload/
  3. Amazon Builders' Library --- Timeouts, retries and backoff with jitter (抖动、单层重试、熔断建议):https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
  4. Amazon Builders' Library --- Making retries safe with idempotent APIs (幂等 API 与重试安全):https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
  5. Lamport, L. --- Time, Clocks, and the Ordering of Events in a Distributed System (因果序的经典论文,本文因果排序的理论来源):https://lamport.azurewebsites.net/pubs/time-clocks.pdf
  6. Apache Kafka 官方文档 --- Message Delivery Semantics (at-least-once / exactly-once 与幂等生产者):https://kafka.apache.org/documentation/#semantics
  7. RabbitMQ 官方文档 --- Consumer Acknowledgements and Publisher Confirms (可见性超时与重投机制):https://www.rabbitmq.com/docs/confirms
  8. Nygard, M. T. --- Release It! (舱壁、熔断、稳态模式,本文隔离设计的思想来源):https://pragprog.com/titles/mnee2/release-it-second-edition/
  9. Kleppmann, M. --- Designing Data-Intensive Applications (一致性模型、因果一致、幂等与并发控制):添加链接描述
  10. Microsoft Azure Architecture Center --- Retry pattern (重试策略的分类与参数建议):https://learn.microsoft.com/en-us/azure/architecture/patterns/retry
相关推荐
谙弆悕博士1 小时前
多智能体架构详解:层级树状架构(分级主从型)
运维·架构·大模型·agent·多智能体·langgraph·层级树状
Forget the Dream2 小时前
Spring AI 2.0 系列(二):第一个 ChatClient——从注入到一次完整调用
java·人工智能·spring boot·ai·springai
学无止境小袁同学2 小时前
Google ADK 学习指南
python·llm·agent·多agent·google adk·llmagent·agent cli
塑料铲子3 小时前
你的 Skill 越多越蠢?Token 上下文爆炸的求生指南
机器学习·agent
qinglongcn4 小时前
四面统一:记忆/Session/观测/Cron
agent·ai编程
货拉拉技术4 小时前
AI Agent 如何进入实时交易系统:货拉拉的三个实践与一套工程方法论
后端·架构·agent
qinglongcn4 小时前
从 metadata 键到独立列
agent·ai编程
zdr尽职尽责4 小时前
UnityCli 兼容2022版本
ui·unity·ai·c#·游戏引擎
小龙66664 小时前
给 Agent 一张地图,而不是一座迷宫:前端 monorepo 目录结构重构实录
前端·agent