proxy_next_upstream 是 nginx 实现后端高可用的被动容错机制，定义请求在 error、timeout、指定 5xx 等条件下自动转向下一健康 upstream 节点；需配合 proxy_next_upstream_tries、max_fails 等参数及健康检查使用。
proxy_next_upstream 是 Nginx 实现后端服务高可用的关键机制，它让请求在某个 upstream 节点失败时，自动转发给下一个健康节点，无需客户端重试。
一、proxy_next_upstream 的作用和触发条件
该指令本身不决定“谁是下一个”，而是定义“什么情况下尝试下一个”。只有当当前节点返回特定错误时，Nginx 才会按 upstream 配置顺序尝试下一个 server。
常见可触发转移的响应类型包括：
- error：与后端建立连接、发送请求或读取响应头时发生网络/系统级错误（如 connection refused、timeout）
- timeout：连接或响应超时（需配合 proxy_connect_timeout / proxy_read_timeout 使用）
- http_500、http_502、http_503、http_504：后端明确返回这些 5xx 状态码
- invalid_header：后端返回了非法 HTTP 响应头（如缺少冒号、格式错误）
注意：默认只启用 error 和 timeout，其他需显式配置。例如：proxy_next_upstream error timeout http_502 http_503;
二、基础配置示例
在 location 或 server 块中启用，并配合 upstream 使用：
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
upstream backend {
server 192.168.1.10:8080;
server 192.168.1.11:8080;
server 192.168.1.12:8080;
}
<p>server {
listen 80;
location / {
proxy_pass <a href="https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e">https://www.php.cn/link/65b5b8d1f89bf53a5713bc3afdd83e9e</a>;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 3; # 最多重试 2 次（共最多 3 次尝试）
proxy_next_upstream_timeout 10s; # 整个重试过程总超时时间
proxy_connect_timeout 3s;
proxy_send_timeout 5s;
proxy_read_timeout 5s;
}
}</p>
说明：
– proxy_next_upstream_tries 控制最大尝试次数（含首次），设为 3 表示最多换 2 个节点；
– proxy_next_upstream_timeout 是所有重试加起来的总耗时上限，超时即返回错误给客户端；
– 单次超时由 proxy_connect_timeout、proxy_read_timeout 等控制。
三、配合健康检查提升可靠性
proxy_next_upstream 是“被动容错”——出错才切换。若想主动剔除故障节点，需结合健康检查：
- 免费版 Nginx（开源）：仅支持基于 passive 检查（靠 proxy_next_upstream 触发失败计数 + max_fails/fail_timeout）
- Nginx Plus：支持 active health check（定期发探测请求）
开源版典型配置：
upstream 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;
server 192.168.1.12:8080 max_fails=3 fail_timeout=30s;
}
含义：某节点连续 3 次被 proxy_next_upstream 标记为失败（如超时或 502），则在 30 秒内不再分发新请求给它，到期后自动恢复试探。
四、注意事项与避坑点
以下情况不会触发重试，容易误以为配置失效：
- 后端返回 2xx 或 3xx 响应但内容异常（如 JSON 缺字段）——proxy_next_upstream 不感知业务逻辑，只看状态码和连接层错误
- 使用了 proxy_buffering off 且后端流式输出，部分响应已发送给客户端后出错 —— 此时无法重试（违反 HTTP 协议）
- 启用了 proxy_cache 且缓存生效 —— 请求可能根本不到 upstream，自然不走重试逻辑
-
POST/PUT 等非幂等请求默认不重试（除非显式加上
http_400等，但语义上不合理）；Nginx 默认只对幂等方法（GET、HEAD、OPTIONS）安全重试
如需对 POST 也重试，需确认后端支持幂等（例如带唯一 id），并添加：proxy_next_upstream error timeout http_502 http_503 non_idempotent;（Nginx 1.9.13+ 支持）
