upstream是nginx核心http模块，必须定义在http块内，用于实现负载均衡与容错；需配合proxy_pass调用，配置健康检查、合理负载策略及代理头。
nginx 通过 upstream 模块把一组后端服务器抽象成一个逻辑服务单元，实现请求分发、自动容错和流量调控。它不是插件，而是核心 HTTP 模块，无需额外编译，但必须按规范写在正确位置才能生效。
upstream 必须定义在 http 块内
这是硬性语法要求：不能放在 server 或 location 块里，否则 nginx 启动直接报错 upstream directive is not allowed here。主配置文件（如 /www/server/nginx/conf/nginx.conf 或 /etc/nginx/nginx.conf）的 http { } 区域才是唯一合法位置。
- 建议加在所有
include语句之前，避免被站点配置覆盖 - 宝塔面板的站点配置文件（
/www/server/panel/vhost/nginx/*.conf）只支持单目标反向代理，不支持 upstream 多节点逻辑 - 名称需全局唯一，推荐用小写+下划线，比如
api_cluster或cms_backend
选择适合业务的负载策略
默认轮询（round-robin）只是起点，真实场景需根据后端特性主动选型：
-
加权轮询（weight）：给高性能机器设更高权重，例如
server 10.0.1.5:8080 weight=4与server 10.0.1.6:8080 weight=1构成约 4:1 的流量比 - least_conn：新请求优先发给当前活跃连接最少的节点，适合 WebSocket、gRPC 等长连接服务
-
ip_hash：同一客户端 IP 固定路由到同一台后端，适用于无共享 session 的老系统；注意它与
weight冲突，不可共存
每个 server 都要配健康检查参数
只写 IP 和端口只是静态列表，没有故障感知能力。真正可用的配置必须带探测逻辑：
-
max_fails=3 fail_timeout=30s：30 秒内连续失败 3 次，该节点被临时剔除，30 秒后自动重试 -
backup：仅当所有非 backup 节点都不可用时才启用，适合灾备或低优先级实例 -
down：手动标记为离线，常用于计划内维护，重载配置后立即生效 - 注意：单节点 upstream 会忽略
max_fails/fail_timeout，健康检查实际失效，至少两个server才有意义
proxy_pass 必须严格引用 upstream 名称
upstream 定义完只是“声明”，真正起作用靠 proxy_pass 调用。常见错误是仍写死 IP 地址，导致 upstream 完全无效：
- ✅ 正确：
proxy_pass http://api_cluster;（注意http://前缀 + 名称 + 分号，结尾不加斜杠） - ❌ 错误：
proxy_pass http://192.168.1.10:8080;—— 这样 upstream 不参与任何转发 - 名称大小写、拼写必须完全一致；
$host不能写成$http_host，否则后端可能解析出错或 HTTPS 跳转异常 - 务必补全基础代理头：
proxy_set_header Host $host;、proxy_set_header X-Real-IP $remote_addr;、proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
