Nginx自动切换需三要素协同：proxy_next_upstream明确错误类型（如error、timeout、http_502-504）、proxy_next_upstream_tries与timeout限制重试边界、upstream中server配置max_fails/fail_timeout启用被动健康检查。

要让 Nginx 在后端节点宕机或响应异常时自动切到健康节点，不能只写一行 proxy_next_upstream 就完事。它本质是“失败后兜底”，必须配合错误类型控制、重试边界限制和被动健康检查，三者协同才能真正起效。

明确哪些错误才值得重试

默认只对 error（连接拒绝、TCP reset）和 timeout（超时）触发重试，但生产中常见的是后端返回 502/503/504 这类网关错误，它们必须显式列出才会被纳入重试范围。

• error 和 timeout 是基础项，必须保留
• http_502、http_503、http_504 推荐加上——这类错误多因后端瞬时过载或进程崩溃，重试往往成功
• invalid_header 建议加上——防后端返回空响应或缺失 Status 行，属于“假死”信号
• 避免加 http_404 或 http_500：前者是路径不存在，后者可能是业务逻辑错误，重试不会改变结果，还可能引发重复扣款、下单等风险

严格限制重试次数与总耗时

不设限的重试会让延迟放大，甚至拖垮整个链路。两个参数必须成对使用：

Umbrel Proxy Manager

高效管理与交互 Umbrel 代理服务，支持 Docker 容器。自动发现运行服务，将内部 Docker IP 映射为可访问的外部地址。

下载

• proxy_next_upstream_tries 3：最多尝试 3 次（含首次），即最多换 2 个节点。设为 3 是兼顾容错与响应时间的常见选择
• proxy_next_upstream_timeout 10s：从第一次请求发出开始计时，所有重试加起来不能超过这个总时长。若单次 proxy_read_timeout 是 5s，设为 10s 可覆盖两次较慢响应+网络抖动余量
• 不设 timeout 是最大隐患：4 台后端各卡 14 秒，用户可能等满 56 秒才看到错误

upstream 必须启用被动健康检查

proxy_next_upstream 解决的是“这次失败怎么办”，而 max_fails/fail_timeout 解决的是“下次还打不打它”。没有后者，Nginx 仍会把新请求轮询到已宕机但尚未被标记的节点，导致每次都要先失败再重试。

• 每个 server 后加 max_fails=3 fail_timeout=30s：连续 3 次失败（包括重试触发的失败）后，该节点在 30 秒内不再参与调度
• 可选加 backup 节点：仅当所有主节点都不可用时才启用，作为最后一道防线
• 注意：http_502 等状态码只有被写进 proxy_next_upstream 列表，其失败才会计入 max_fails 计数

区分请求方法，避免非幂等操作重复执行

Nginx 默认只对 GET/HEAD 请求重试，这是安全机制。POST、PUT、DELETE 等非幂等方法，即使配置了 proxy_next_upstream，也不会自动重试——除非你主动关闭缓冲并启用 non_idempotent，但强烈不建议。

• 下单、支付、导入等接口，应设计为异步：前端提交后立即返回 task_id，再通过轮询或 WebSocket 获取结果
• 若必须重试非幂等请求，请确保上游服务完全幂等（如数据库唯一键约束 + 幂等 token 校验）
• 盲目开启 non_idempotent 可能导致订单创建两次、余额重复扣除等严重问题