nginx 本身不支持 proxy_pass 直接主备切换，但可通过 upstream 定义主备服务器组（如主高权、备低权）、配置 max_fails/fail_timeout 实现被动故障转移，并结合主动健康检查（nginx plus 的 health_check 或开源版 lua 方案）提升探测实时性，最终达成等效主备自动切换效果。
Nginx 本身不支持 proxy_pass 直接配置主备切换（如“主挂了自动切到备”），但可以通过 upstream 模块 + 健康检查机制 实现高可用的后端自动故障转移，效果等同于主备切换。
1. 使用 upstream 定义主备服务器组
不能在 location 中直接对多个 proxy_pass 写条件判断，必须把后端服务抽象为一个命名 upstream，再在 proxy_pass 中引用它：
upstream backend_cluster {
server 192.168.1.10:8080 weight=10 max_fails=3 fail_timeout=30s; # 主
server 192.168.1.11:8080 weight=1 max_fails=3 fail_timeout=30s; # 备（权重低，仅主不可用时启用）
}
说明：
-
weight控制流量分配比例；设为主高备低，可实现“优先主、备用兜底” -
max_fails表示连续失败多少次后标记该节点为不可用 -
fail_timeout指定标记为不可用后，多久重新尝试连接（期间请求不会发给它）
2. 启用主动健康检查（推荐：Nginx Plus 或开源版配合 lua-nginx-module）
默认的被动检查（靠请求失败触发）有滞后性。若需更及时探测，可选以下方式：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
-
Nginx Plus：原生支持
health_check指令，例如：
upstream backend_cluster {
server 192.168.1.10:8080;
server 192.168.1.11:8080;
health_check interval=5 fails=2 passes=2 uri=/health;
}
- 开源 Nginx + lua-nginx-module：用 Lua 编写定时探活逻辑，动态更新 upstream（较复杂，适合定制化场景）
3. 在 location 中正确引用 upstream
确保 proxy_pass 指向 upstream 名称，且末尾不带 URI 路径（避免重写异常）：
server {
listen 80;
location /api/ {
proxy_pass http://backend_cluster; # 注意：无路径，否则会覆盖匹配前缀
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
⚠️ 常见错误：proxy_pass http://backend_cluster/;（结尾斜杠）会导致路径被截断或重复，应避免。
4. 验证与观察切换行为
可通过以下方式确认主备切换是否生效：
- 手动停掉主服务器（如
curl http://192.168.1.10:8080/health返回失败） - 持续请求 Nginx，观察响应来源（如返回头中加
X-Upstream: 192.168.1.10） - 查看 Nginx error log：
upstream [server] is unavailable或no live upstreams可辅助定位问题
注意：Nginx 默认采用轮询策略，但结合 weight 和故障标记后，实际表现为“主优先、故障自动剔除、恢复后自动回归”。
