Nginx upstream必须定义在http块内且位于所有include之前，命名需业务化、静态化；server行须配置max_fails、fail_timeout等参数实现健康检查；负载策略如least_conn、ip_hash须首行显式声明；proxy_pass引用需准确并配全请求头与超时。
配置 Nginx 的 upstream 块管理后端集群，核心是结构合规、参数实用、策略匹配业务真实需求。它不是把几台服务器列出来就行，而是要让 Nginx 能识别状态、合理分发、自动避错。
upstream 必须写在 http 块内，位置不能错
这是最常踩的坑——upstream 只能在 http { } 作用域中定义，不能嵌套在 server 或 location 里，也不该放在宝塔等面板生成的站点配置文件（如 /www/server/panel/vhost/nginx/*.conf）中。
- 正确位置：主配置文件（如
/etc/nginx/nginx.conf或/www/server/nginx/conf/nginx.conf）的http区块开头，且建议放在所有include语句之前，避免被覆盖 - 命名要有业务含义，比如
api_backend、user_service，方便后续维护和日志追踪 - 不支持变量或动态名称，必须是静态字符串，且大小写敏感
每个 server 行要带运行时控制参数
只写 server 10.0.1.5:8001; 是无效的“摆设”——没有健康检查、无法自动剔除故障节点，等于把负载均衡降级为静态转发。
-
max_fails=3 fail_timeout=30s：30 秒内连续失败 3 次，该节点被临时下线，30 秒后自动重试；单节点 upstream 不生效，至少两个server才起作用 -
backup：仅当所有非 backup 节点都不可用时才启用，适合灾备机或低优先级实例 -
down：手动标记为下线，保留配置但不参与调度，适用于计划内维护 - 支持 IP+端口、域名（需确保 DNS 解析稳定）、Unix socket（如
unix:/tmp/app.sock）
负载策略要按业务显式声明
Nginx 默认轮询，但其他算法必须在 upstream 块**第一行**明确写出，且不可混用冲突策略（例如 ip_hash 和 weight 互斥）。
-
least_conn;：优先派发到当前活跃连接数最少的节点，适合 WebSocket、gRPC、文件上传等长连接或响应时间差异大的场景 -
ip_hash;：同一客户端 IP 始终打到同一后端，用于无共享 Session 的老系统；注意多层代理时需配合$http_x_forwarded_for使用 -
weight=：加权轮询，按数值比例分配流量，例如高配节点设weight=5，低配设weight=2
proxy_pass 引用必须准确，配套头和超时不能少
定义了 upstream 只是第一步，真正生效靠 location 中的 proxy_pass 正确引用，以及完整的代理上下文透传。
-
proxy_pass http://api_backend/;—— 注意末尾斜杠：有斜杠会截断location路径，无斜杠则原样转发 - 必设四类请求头：
Host $host、X-Real-IP $remote_addr、X-Forwarded-For $proxy_add_x_forwarded_for、X-Forwarded-Proto $scheme - 设置基础超时：
proxy_connect_timeout 5s、proxy_send_timeout 30s、proxy_read_timeout 60s，防止单节点拖垮整个连接池 - 开启重试控制：
proxy_next_upstream error timeout http_502 http_503 http_504，禁用http_500和 4xx，避免业务异常被重复提交
