在 nginx 中，要实现请求超时后自动切换到下一个上游节点，需要在 `location` 块或 `upstream` 块中配置 proxy_next_upstream 指令并显式包含 timeout 参数。默认情况下该指令可能未开启超时重试，因此必须明确指定 proxy_next_upstream timeout;。当后端响应时间超过 proxy_connect_timeout、proxy_read_timeout 或 proxy_send_timeout 设定的阈值时，nginx 会自动将请求转发给列表中的下一个健康节点。
如何配置 proxy_next_upstream 以启用超时切换
要启用超时切换，必须在 Nginx 配置文件中使用 proxy_next_upstream 指令并添加 timeout 关键字。同时需要确保定义了合理的超时时间，例如 proxy_read_timeout。如果只写 proxy_next_upstream error; 而不加 timeout，则超时不会触发切换。配置完成后，Nginx 会在检测到读取或连接超时时，自动尝试下一个上游服务器。
server {
listen 80;
server_name example.com;
location /api/ {
proxy_pass http://backend_pool;
# 关键配置：允许在超时和错误时切换到下一个节点
proxy_next_upstream timeout error;
# 设置读取超时时间为 5 秒
proxy_read_timeout 5s;
# 设置连接超时时间为 3 秒
proxy_connect_timeout 3s;
# 传递真实客户端 IP
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
upstream backend_pool {
server 192.168.1.10:8080;
server 192.168.1.11:8080;
server 192.168.1.12:8080;
}
上述配置中，proxy_next_upstream timeout error; 是核心。当第一个节点 192.168.1.10 在 5 秒内未返回数据时，Nginx 会记录一个超时事件，并立即将请求发送给 192.168.1.11。如果所有节点都失败，Nginx 将返回最后一个节点的错误信息（通常是 502 Bad Gateway 或 504 Gateway Timeout）。
超时切换与错误切换的区别及组合使用
proxy_next_upstream 支持多种条件，其中 error 和 timeout 是最常用的两个。 error 通常指连接被拒绝、连接重置或无法连接到上游服务器等网络层面的故障。而 timeout 特指时间耗尽，包括连接建立超时、发送请求超时或等待响应超时。在实际生产中，建议同时启用两者，因为网络波动既可能导致连接失败，也可能导致响应缓慢。此外，还可以结合 http_502、http_503 和 http_504 来针对特定的 HTTP 状态码进行重试，但需注意避免无限循环重试导致的雪崩效应。
# 更完善的配置示例，包含 HTTP 状态码重试
location /api/ {
proxy_pass http://backend_pool;
# 仅在超时、网络错误或收到 502/504 时切换
proxy_next_upstream timeout error http_502 http_504;
# 限制最大重试次数为 2 次（即最多尝试 3 个节点）
# 注意：Nginx 原生不直接提供 max_retries 参数，
# 通常通过 upstream 的 weight 或 health check 模块控制，
# 或者依赖 upstream 节点数量自然限制。
proxy_read_timeout 10s;
proxy_connect_timeout 5s;
proxy_send_timeout 5s;
}
在这个增强版配置中，http_502 和 http_504 的加入使得 Nginx 不仅在网络层超时或错误时切换，还在上游服务器返回明确的网关错误时进行切换。这有助于提高系统的容错能力，特别是在上游服务部分实例不可用时。然而，必须注意 proxy_next_upstream 的重试机制是基于单个请求的，它不会自动限制重试次数，除非上游节点全部尝试完毕。因此，合理设置超时时间和上游节点的健康检查策略至关重要。
当所有上游节点均超时时 Nginx 的行为是什么
当配置了 proxy_next_upstream timeout 后，如果所有上游节点都在各自的超时时间内未能成功处理请求，Nginx 将停止重试并直接向客户端返回错误。此时返回的状态码通常是最后一个尝试节点的错误状态，最常见的是 504 Gateway Timeout。如果是因为连接被拒绝等 error 类型导致的所有节点失败，则可能返回 502 Bad Gateway。Nginx 不会无限重试，也不会尝试其他非上游节点。客户端会收到这个最终错误，应用层可能需要实现自己的重试逻辑来处理这种情况。
