Nginx 不支持 proxy_pass 直接配置备用集群，但可通过 upstream 健康检查 + proxy_next_upstream 重试 + error_page 回退 fallback_cluster 实现智能故障转移；推荐配合主动健康检查与外部控制面提升可靠性。

Nginx 本身不支持 proxy_pass 直接配置“备用集群节点”的智能故障转移逻辑（比如自动切到另一组 upstream），但可以通过 upstream 模块 + 健康检查机制 + 多级 fallback 策略，实现接近“智能故障转移”的效果。核心不在 proxy_pass 行内写备用地址，而在于 upstream 定义的健壮性设计。

用 upstream 定义主备集群并启用主动健康检查

Nginx 开源版默认只支持被动健康检查（fail_timeout + max_fails），要实现较可靠的故障识别和自动摘除，建议启用 nginx-plus 的主动健康检查，或使用开源版配合 nginx_upstream_check_module（需自行编译）。

• 主集群配置示例（带健康检查）：

upstream primary_cluster {
  server 192.168.1.10:8080 max_fails=3 fail_timeout=30s;
  server 192.168.1.11:8080 max_fails=3 fail_timeout=30s;
  # 若使用 check 模块：
  check interval=3 rise=2 fall=5 timeout=1 type=http;
  check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
  check_http_expect_alive http_2xx http_3xx;
}

• 备用集群独立定义（不参与主集群的失败计数）：

upstream fallback_cluster {
  server 192.168.1.20:8080 max_fails=2 fail_timeout=20s;
  server 192.168.1.21:8080 max_fails=2 fail_timeout=20s;
}

用 proxy_next_upstream 实现请求级自动重试

这是最常用、无需额外模块的方案。当主 upstream 中某台节点失败时，Nginx 可在当前 upstream 内重试其他节点；若整个主集群不可用，再结合 error_page 跳转到备用集群。

• 关键配置项：

location /api/ {
  proxy_pass http://primary_cluster;
  proxy_next_upstream error timeout http_500 http_502 http_503 http_504;
  proxy_next_upstream_tries 3;
  proxy_next_upstream_timeout 5s;
  # 若所有重试都失败，则触发 error_page
  error_page 502 503 504 = @fallback;
}

location @fallback {
  proxy_pass http://fallback_cluster;
  proxy_intercept_errors off;
}

用 map + resolver 实现动态上游切换（进阶）

适用于主备集群 IP 可能变化、或需根据外部状态（如 Consul 健康服务）动态路由的场景。通过 map 将变量映射为 upstream 名，配合定期 resolver 刷新 DNS，再结合 try_files 或 if（慎用）做条件判断。

WebChat Voice Proxy

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

下载

• 简单示意（依赖 DNS 解析结果）：

resolver 127.0.0.1 valid=10s;
map $host $backend {
  default "primary_cluster";
  ~*\.failover\.example\.com "fallback_cluster";
}

location / {
  proxy_pass http://$backend;
}

实际生产中更推荐结合外部控制面（如 Lua + OpenResty + etcd）做服务发现与熔断，而非纯 Nginx 配置硬编码。

注意事项与避坑点

• proxy_next_upstream 不重试 POST/PUT 等非幂等请求（除非显式加 non_idempotent）；
• error_page 的 = 后必须是内部 location（以 @ 开头），否则会发起外部重定向；
• 主备集群的超时参数（proxy_connect_timeout、proxy_read_timeout）应合理错开，避免 fallback 过早触发；
• 不要在 upstream 中混用 weight 和 backup 标记来模拟“主备”，backup 仅在所有非 backup 节点失效后才启用，无法实现跨集群智能调度。

本质上，Nginx 的角色是反向代理与负载均衡器，不是服务网格。真正的“智能”故障转移需要配合注册中心、健康探针、流量治理策略共同完成。Nginx 配置只是其中一环，重点是让它的行为可预测、可观察、可收敛。