支付链路 P0 复盘：幂等键碰撞导致重复扣款

2026-05-15 事故复盘 — 范围、根因、修复、预防

核心决策

事故复盘会上提出过三个方向：回滚到旧路由、引入分布式锁、重设计幂等键。我们最终选择第三种，因为前两个都只是把窗口收窄，没有解决"两个不同请求可能合成同一个键"这个根本问题。

背景与误解

事故发生后社区出现了几种与事实不符的解读，先在这里厘清。

事件时间线

根因还原

下面这张流程图刻画了事故期间一笔订单的完整路径。两条相同的幂等键最终被网关视为同一笔交易，但下游各自完成了扣款。

幂等键的三种命运

网关在处理一个幂等键时，会走下面三个分支之一。事故期间，"键已存在但状态未达终态"这一支被错误地归并到了"新键"。

修复方案论证

选择 UUIDv7 作为幂等键的依据如下。每条结论都对应一段可验证的代码或测试。

// 10 亿次 UUIDv7 生成 — 单机基准，验证碰撞率。
import { generateUUIDv7 } from './uuid7'

const seen = new Set<string>()
const N = 1_000_000_000
let collisions = 0

for (let i = 0; i < N; i++) {
  const id = generateUUIDv7()
  if (seen.has(id)) collisions++
  seen.add(id)
}

console.log(`collisions=${collisions} of ${N}`)
// → collisions=0 of 1000000000

客户端只需要在请求头加一行：

headers.set('Idempotency-Key', generateUUIDv7())

方案多维评估

在三个候选方案之间做平面对比时，单一指标会掩盖权衡。下表把各个轨道单独展开。

客户端 vs 服务端生成键的取舍

修复进度

影响面与分布

受影响订单按金额分桶；可以看出绝大部分是小额订单，但单笔最大金额仍超过 ¥3,000。

补偿进度按渠道拆分。微信渠道占大头但退款最快；银联与信用卡因清算窗口需 T+1。

未消化的风险

修复方案合入后仍有几条遗留风险，监控中：

附录：原始日志与代码

下面这些是排查过程中提取的原始材料，平时不影响阅读，留给后续审计与新人 onboard。

async function dispatchByKey(key: string, req: Request) {
  const record = await store.get(key)
  switch (record?.status) {
    case 'committed':
    case 'failed':
      return replay(record)            // 终态 → 复用历史响应
    // BUG: missing 'processing' case
    default:
      return processAsNew(key, req)    // 误把"处理中"也当作新键
  }
}

2026-05-15T09:14:03.412Z gateway INFO  key=order-1023-1747291043 status=new dispatch=A
2026-05-15T09:14:03.918Z gateway INFO  key=order-1023-1747291043 status=new dispatch=B
2026-05-15T09:14:04.105Z gateway WARN  key=order-1023-1747291043 collision_detected committed=2

09:14:03.412 dispatch=A
09:14:03.918 dispatch=B
09:14:04.105 collision detected

Action items

责任人

本次修复涉及的文件

术语表

是这次事故的中心概念， 是修复采用的具体方案。两者结合的关键不在于"用了新算法"，而是 的转移。

操作

这一节是 Talon Doc Runtime 的交互演示，按钮触发的是 runtime 的内置 action：

定位 bug 源码 展开基准测试 切换深色 切换浅色 切换长文风格 切换办公风格

内联状态徽标也是组件的一种：当前事故 P0，目前状态 已关闭，仍有 3 项后续 待跟踪。