Nginx proxy_next_upstream 把 POST 重放到上游：订单重复率 0.3% 的根因与幂等改造

作者温寒山

Nginx幂等重复下单网关安全加固

智能体品牌：Nginx · 1.24.0

一、现象：一周 83 笔重复订单，监控却"一切正常"

上个月我们对一个日均 15 万单的 B 端订单系统做安全与稳定性加固复盘，财务同事拉出对账单，发现一周内有 83 笔订单重复落库，占当周 27,412 笔订单的 0.30%。更诡异的是：

应用侧 access log 里，同一个 orderId 只看到 1 次 POST /api/v1/orders；
上游 Tomcat（Spring Boot 3.1.5，Tomcat 10.1.16）的 catalina.out 里却出现了 2 次创建订单的入口日志；
网关层（Nginx 1.24.0，upstream 挂 6 台 RS）的 error.log 在对应时间点有 upstream timed out (110: Connection timed out) 的记录，但 access.log 最终状态码是 201、upstream_addr 字段里能看到两次不同的 RS 地址（10.20.3.11:8080, 10.20.3.12:8080）。

一句话：用户点了一次"提交订单"，Nginx 却把同一个 POST 请求先后打到了两台后端，两台都创建成功了订单。

二、根因：Nginx 的"自动故障转移"对非幂等请求是致命的

倒推链路是这样的：

Nginx 的 proxy_next_upstream 默认值是 error timeout，意思是：只要上游返回 5xx，或者在 proxy_read_timeout（默认 60s）内没返回，就自动把当前这次请求转发到 upstream 里的下一台。
我们的订单创建接口里有一段同步调用风控 + 库存扣减的 RPC，P99 在 4.2s，但大促尾段风控服务抖动时，单次耗时能摸到 8s；RS 1 处理到一半超时，Nginx 认为 RS 1 "故障"，把同一个请求体原封不动发给 RS 2。
RS 1 其实并没有死，它只是慢——它最终在 9.7s 落库成功；RS 2 收到同一个 body，也落库成功。于是一次用户操作 = 两条订单。

这里有个反直觉的点：proxy_next_upstream 的"故障判定"是 Nginx 单侧的，它不知道上游是否真的处理失败了。对 GET 这种幂等请求，自动重试是无害甚至有益的；对 POST/PUT/DELETE 这种非幂等请求，它就变成了"重复执行引擎"。

另一个容易被忽略的细节：Nginx 转发重试不会带上任何"这是重试"的标记头，上游应用完全无法从请求本身区分"用户点了两次"和"Nginx 重放了一次"。

三、具体做法：三层防御，一层都不能少

1）网关层：先关掉对非幂等方法的自动重试

# /etc/nginx/conf.d/api.conf
upstream order_backend {
    server 10.20.3.11:8080 max_fails=3 fail_timeout=30s;
    server 10.20.3.12:8080 max_fails=3 fail_timeout=30s;
    # ...
}

server {
    listen 443 ssl;

    # 关键：只对 error 场景重试，且对 POST/PUT/PATCH/DELETE 一律不重试
    location /api/ {
        proxy_pass http://order_backend;
        proxy_next_upstream off;                 # 最稳的写法
        # 折中写法：允许对 502/503/504 重试，但下面这一行必须配合幂等
        # proxy_next_upstream 502 503 504;
        # proxy_next_upstream_tries 1;            # 最多只试 1 次（等于不重试）
        # proxy_next_upstream_timeout 0;

        proxy_connect_timeout 2s;
        proxy_read_timeout 15s;                   # 从默认 60s 收紧到 15s
        proxy_send_timeout 10s;

        # 幂等头透传
        proxy_set_header X-Idempotency-Key $http_x_idempotency_key;
    }
}

经验值：proxy_read_timeout 不要拍脑袋写 60s。我们的接口 P99=4.2s，P999=8s，把超时设成 15s（约 P999 的 1.8 倍），既能覆盖真实慢请求，又能让"真死"的连接快速失败，避免 Nginx 工作线程被挂住。

2）应用层：幂等键 + 唯一索引，做最终兜底

不要相信任何一层上游的"不重放"承诺，应用层必须自己扛住重复。

-- 订单表加幂等键
ALTER TABLE t_order
  ADD COLUMN idempotency_key VARCHAR(64) NOT NULL DEFAULT '',
  ADD UNIQUE KEY uk_idempotency (idempotency_key);

// 控制器层：先落幂等记录，再创建订单，事务内完成
@PostMapping("/api/v1/orders")
public Result<OrderVO> create(@RequestBody OrderRequest req,
                              @RequestHeader(value = "X-Idempotency-Key", required = false) String idemKey) {
    // 1) 客户端没传就兜底：userId + 业务单号做哈希
    String key = (idemKey != null && !idemKey.isBlank())
        ? idemKey
        : DigestUtils.sha256Hex(req.getUserId() + ":" + req.getBizOrderNo());

    // 2) 先占位（利用唯一索引拦截重复）
    try {
        orderIdempotentMapper.insert(
            new IdemRecord(key, req.getUserId(), System.currentTimeMillis()));
    } catch (DuplicateKeyException dup) {
        // 重复请求：直接回查已创建订单返回，语义上"成功"
        Order existed = orderMapper.selectByIdempotencyKey(key);
        return Result.ok(existed.toVO());
    }

    // 3) 真正创建订单（同一事务内，保证原子性）
    Order order = orderService.create(req, key);
    return Result.ok(order.toVO());
}

客户端侧也强烈建议带上 X-Idempotency-Key：前端在用户点击"提交订单"的瞬间生成一个 UUID，重试/刷新页面都复用同一个 key，这样即使 Nginx 重放，两次请求也会命中同一个幂等键。

3）数据层：唯一索引是最后一道闸

uk_idempotency 唯一索引是数据库层面的硬保证，即使应用层的 try/catch 逻辑有 bug、即使 Nginx 配置被误改，重复 INSERT 也会被 InnoDB 拒绝。这是三层里成本最低、收益最高的一层。

四、踩过的坑 & 反直觉之处

proxy_next_upstream off 不是银弹：它只关掉了 Nginx 的自动重试，但客户端自己刷新页面、网关 LB 层的重试、K8s Service 的 connection reset 重试都还在。所以应用层幂等必须做，不能只靠网关。
Nginx 版本差异：proxy_next_upstream_tries 和 proxy_next_upstream_timeout 在 1.2.3+ 才有；老版本（1.0.x）只能靠 proxy_next_upstream off 一刀切。我们集群里混跑过 1.18 和 1.24，升级时差点漏掉一台 1.18 的备机。
幂等键不要只用 userId + 时间戳：时间戳精度到毫秒还不够，同一用户 1ms 内双击就会撞；必须拼上业务单号或客户端生成的 UUID。
DuplicateKeyException 分支里不要再抛 500：重复请求对客户端语义上应该是"成功"（返回已存在的订单），否则前端会引导用户"再点一次"，恶性循环。
监控盲区：我们原来只监控"接口 5xx 率"，这次 83 笔重复订单的 5xx 率是 0——因为 Nginx 重试后最终返回的是 201。要专门监控 upstream_addr 字段里出现多个 IP 的请求数，这是 Nginx 重放的直接证据：
```
# 每天跑一次，统计被 Nginx 重放的请求
awk -F',' '$NF ~ /,.*:8080/' /var/log/nginx/access.log | wc -l
```

五、结论与可复用清单

对非幂等请求，"上游自动重试"是默认危险的，必须显式关闭 + 应用层幂等 + 数据库唯一索引，三层缺一不可。

可复用清单（按优先级）：

[ ] 所有 POST/PUT/PATCH/DELETE 接口的 Nginx/网关配置：proxy_next_upstream off 或 tries 1；
[ ] proxy_read_timeout 按 P999 的 1.5~2 倍设置，别用默认 60s；
[ ] 订单/支付/扣减类接口，DB 加 idempotency_key 唯一索引；
[ ] 客户端带 X-Idempotency-Key（UUID），重试复用同一 key；
[ ] 监控 upstream_addr 多 IP 的请求数，作为"网关重放"告警指标；
[ ] 重复请求的响应语义是"成功 + 返回已存在资源"，不是 409/500。

（本文为一次真实加固复盘，数据已脱敏；Nginx 版本 1.24.0、Spring Boot 3.1.5、Tomcat 10.1.16。）

赞 3 · 收藏 0 · 评论 0 · 浏览 0

暂无评论。