启用 non_idempotent 有风险，仅适用于日志上报、带幂等ID提交等可容忍重复或后端已防护的场景；必须配合 proxy_next_upstream、proxy_next_upstream_tries 等配置，并确保 proxy_buffering on 才能安全重试。

直接启用 non_idempotent 是有风险的，尤其对 POST、PATCH、LOCK 等非幂等请求——Nginx 默认不重试它们，正是为了避免重复提交引发数据异常（比如重复下单、重复扣款、重复创建）。要安全使用它，必须明确知道“什么情况下可以重试”以及“重试前该做什么”。

理解 non_idempotent 的真实作用

它不是让 Nginx “自动重试所有 POST”，而是解除默认限制：当 upstream 出现 error/timeout 等触发条件时，允许 Nginx 把已发出但未收到响应的非幂等请求，转发给下一台服务器。

关键前提是：请求尚未被上游完整接收并处理。如果后端已接收并执行了业务逻辑（例如数据库已插入），此时重试就会导致重复操作。

• Nginx 只能判断“连接失败”或“超时未响应”，无法感知后端是否已执行成功
• 一旦请求体（request body）被完整发送到某台 upstream，Nginx 就不再具备重试能力（除非开启 proxy_buffering on 并保留缓存）
• proxy_request_buffering off 会直接禁用重试，即使配置了 non_idempotent

必须配套的关键配置项

单独加 non_idempotent 没有意义，需与以下指令协同控制重试边界：

WebChat Voice Proxy

⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**

下载

• proxy_next_upstream error timeout http_502 http_503 http_504：明确哪些错误才触发重试，避免对 4xx（如 400、401）盲目重试
• proxy_next_upstream_tries 2：限制最多尝试次数（建议 ≤ 后端节点数），防止全量轮询放大风险
• proxy_next_upstream_timeout 10s：设置整个重试过程的总耗时上限，超时即返回最终错误
• proxy_buffering on（默认开启）：确保请求体在内存中可复用；若关闭，则非幂等请求基本无法重试
• client_max_body_size 和 proxy_buffer_size 要匹配，避免因缓冲不足导致 body 被写入临时文件而丢失重试能力

适合启用 non_idempotent 的典型场景

不是所有 POST 都适合重试，仅推荐用于语义上可容忍重复、或后端已做幂等防护的接口：

• 日志上报类接口（重复写入不影响业务）
• 带唯一业务 ID 的提交（后端通过 ID 去重或幂等校验）
• 异步任务触发（如“发起导出”，实际执行由队列调度，重试只触发一次任务）
• 内部服务间调用，且下游明确支持重试语义（例如 gRPC 中的 retry policy）

支付、充值、订单创建等强一致性操作，不应依赖 Nginx 层重试，而应由应用层实现幂等或补偿机制。

验证与观测建议

上线前务必通过日志和监控确认行为符合预期：

• 开启 error_log ... debug（谨慎用于测试环境），观察 upstream: retry 日志是否出现在预期错误路径上
• 在 access_log 中加入 $upstream_addr 和 $upstream_status，确认失败后是否真的切换了后端地址
• 对关键接口做压测：模拟某台 upstream 延迟或返回 502，检查是否按配置重试、是否出现重复落库
• 禁用 non_idempotent 对比测试，确认无重试时的失败率，评估开启后的可用性提升是否值得风险