Nginx的proxy_next_upstream仅在proxy_pass阶段发生特定错误（如timeout、error、502/503/504等）时才重试，需显式配置且受限于tries、timeout及upstream多节点等条件。
Nginx 的 ngx_http_proxy_module 本身不提供“智能容错”或“自动重试失败请求”的完整逻辑，它的重试行为是有限且需显式配置的，核心依赖于 proxy_next_upstream 指令及其相关参数。理解其机制的关键在于：它只在特定错误阶段、满足明确条件时，才将请求转发给下一个 upstream server，而非无差别重试。
触发重试的前提：仅限 proxy_pass 阶段的特定错误
重试不是对所有失败都生效。只有当 Nginx 在与 upstream 建立连接、发送请求、接收响应头（response header）的过程中发生错误时，proxy_next_upstream 才可能介入。常见可触发重试的错误包括：
-
timeout：连接 upstream 超时（
proxy_connect_timeout）、发送请求超时（proxy_send_timeout）、读取响应头超时（proxy_read_timeout） - error：网络连接被拒绝、断开、重置等底层 I/O 错误
- http_500、http_502、http_503、http_504：upstream 返回了这些状态码（注意：默认不包含 501/4xx 或 5xx 中未明确列出的状态）
-
invalid_header：upstream 返回了非法的响应头（如缺少
Status行、格式错误）
⚠️ 注意：如果 upstream 成功返回了合法的 200 响应体但业务逻辑出错（例如 JSON 中 "code":500），Nginx 无法感知，不会重试。
重试控制：proxy_next_upstream 与相关指令协同工作
重试不是“无限循环”，而是受多个指令共同约束：
-
proxy_next_upstream：定义哪些错误类型允许尝试下一个 upstream server（如error timeout http_502） -
proxy_next_upstream_tries：限制最多重试次数（含首次请求，默认为 0 表示不限，建议设为合理值如 3） -
proxy_next_upstream_timeout：限制整个重试过程的总耗时（从第一次请求开始计时，默认为 0 表示不限） -
upstream 中的
max_fails和fail_timeout：影响服务器是否被标记为不可用（即“被动健康检查”），这决定了后续请求是否会跳过该节点——它不直接控制单次请求重试，但影响重试时的可用候选列表
常见误区与关键细节
很多问题源于对机制的误解：
-
不重试 4xx 响应：默认情况下，4xx 是客户端错误，Nginx 认为重试无意义，除非显式添加
http_404等（极少推荐） -
重试不等于“幂等性保障”：如果 upstream 接口非幂等（如 POST 创建资源），重试可能导致重复操作。Nginx 不做请求体缓存或去重，对非 GET/HEAD 请求，若启用了
proxy_buffering off或请求体过大，重试可能失败（因请求体已发送不可复用） - upstream 必须定义多个 server：若 upstream 块中只有一个 server，即使配置了重试，也无“下一个”可选，实际不会发生重试
-
重试发生在同一 upstream 块内：不能跨 upstream 块跳转（例如从
backend_v1重试到backend_v2），需用其他方式（如 rewrite + if）实现更复杂路由
一个典型可靠配置示例
以下配置启用基础容错，适用于 HTTP API 场景：
upstream api_backend {
server 192.168.1.10:8080 max_fails=3 fail_timeout=30s;
server 192.168.1.11:8080 max_fails=3 fail_timeout=30s;
keepalive 32;
}
server {
location /api/ {
proxy_pass http://api_backend;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 10s;
proxy_connect_timeout 5s;
proxy_send_timeout 10s;
proxy_read_timeout 10s;
proxy_buffering on;
proxy_http_version 1.1;
proxy_set_header Connection '';
}
}
该配置表示：单次请求最多尝试 2 次（即最多 1 次重试），总耗时不超过 10 秒；遇到连接失败、超时或上游返回 502/503/504 时切换节点；同时通过 max_fails 实现被动健康检测。
