nginx的upstream必须定义在http块内，不可置于server或location中；需配置健康检查参数、显式声明负载策略，并通过proxy_pass http://名称;正确引用。
Nginx 配置 upstream 后端服务器集群，关键在于结构位置正确、语法规范、策略匹配业务，并能被 proxy_pass 正确引用。不是随便写几行就能生效，必须遵循 Nginx 的作用域规则和配置逻辑。
upstream 必须定义在 http 块内
upstream 块不能出现在 server、location 或站点配置文件（如宝塔的 vhost/*.conf）里，否则启动会报错 “upstream directive is not allowed here”。 正确位置是主配置文件（如 `/etc/nginx/nginx.conf` 或 `/www/server/nginx/conf/nginx.conf`）的 `http { }` 区域内，且建议放在所有 `include` 语句之前，避免被覆盖： - ✅ 推荐写法： ```nginx http { upstream api_backend { server 192.168.1.10:8001 weight=3 max_fails=3 fail_timeout=30s; server 192.168.1.11:8001 weight=1; server 192.168.1.12:8001 backup; }include /etc/nginx/conf.d/*.conf; include /www/server/panel/vhost/nginx/*.conf;
}
- ❌ 错误写法：把 upstream 写进宝塔站点配置、或套在 server { } 里面——这类文件只支持单目标代理，集群逻辑不会加载。
<h3>每个 server 行要带健康与状态参数</h3>
只写 `server 10.0.1.5:8001;` 是静态列表，没有容错能力。真实生产环境必须为每个节点附加运行时控制参数：
- `max_fails=3 fail_timeout=30s`：30 秒内连续失败 3 次，该节点被临时剔除，30 秒后自动重试
- `backup`：仅当所有非 backup 节点都不可用时才启用，适合灾备机
- `down`：手动下线，保留配置但不参与调度，常用于计划维护
- 注意：单节点 upstream 会忽略 `max_fails` 和 `fail_timeout`，健康检查实际失效；至少两个 `server` 才有意义。
<h3>负载策略按需显式声明</h3>
Nginx 默认轮询，但其他策略必须在 upstream 块**首行**显式写出，且不可混用冲突组合：
- `least_conn;`：适合长连接或响应时间差异大的服务（如 WebSocket、gRPC）
- `ip_hash;`：实现客户端 IP 级别会话保持，适用于无共享 Session 的老系统；注意它与 `weight` 不兼容
- `hash $request_uri consistent;` 等高级哈希需第三方模块，标准版不支持
- 加权轮询靠 `weight=` 实现，例如 `server 192.168.1.10:8001 weight=4;` 和 `weight=1` 构成 4:1 流量比
<h3>proxy_pass 必须严格引用 upstream 名称</h3>
定义完 upstream，必须在 location 中通过 `proxy_pass http://名称;` 正确调用，否则整个集群配置无效：
- ✅ 正确：`proxy_pass http://api_backend;`（注意 `http://` 前缀 + 名称 + 分号，结尾**不要斜杠**，除非你明确需要路径截断）
- ❌ 错误：`proxy_pass http://192.168.1.10:8001;`（退化为单点代理）、`proxy_pass api_backend;`（缺协议头）、`proxy_pass http://api_backend/;`（末尾斜杠会触发路径重写，可能破坏后端路由）
- 名称大小写和拼写必须与 upstream 定义**完全一致**，Nginx 区分大小写。
不复杂但容易忽略。
