upstream 必须定义在 http 块内（如 nginx.conf 或 conf.d/*.conf），命名仅支持字母、数字、短横线，server 行末需加分号；proxy_pass 路径斜杠影响 URI 截断；需手动配置 max_fails、fail_timeout、proxy_next_upstream 实现基础健康检查与重试；权重和 hash 算法需按实际场景合理选用。
nginx upstream 配置写在哪、怎么写才生效
配置 Nginx 负载均衡，核心是 upstream 块，但它不能随便放——必须在 http 块里定义，不能放在 server 或 location 里，否则启动直接报错：unknown directive "upstream"。
常见错误是把 upstream 塞进某个 server 段里，以为“就近定义”更清晰，结果 nginx -t 直接失败。
-
upstream必须位于http { ... }范围内（通常在/etc/nginx/nginx.conf或/etc/nginx/conf.d/*.conf中） - 名字不能含下划线（
my_backend❌），只支持字母、数字、短横线（my-backend✅） - 每个
server行后面别漏分号，少一个就整个 upstream 解析失败 - 如果用域名（如
backend1.example.com），Nginx 启动时只解析一次，DNS 变更后不会自动刷新（需加resolve参数或用 resolver 配合）
http {
upstream api-cluster {
server 192.168.1.10:8080;
server 192.168.1.11:8080;
server 192.168.1.12:8080;
}
server {
location /api/ {
proxy_pass http://api-cluster;
}
}
}
proxy_pass 指向 upstream 时路径处理容易出错
用 proxy_pass 转发到 upstream，路径是否带结尾斜杠，直接影响后端收到的 URI——这是最常导致 404 或静态资源加载失败的原因。
比如请求 /api/v1/users，若配置为 proxy_pass http://api-cluster/;（结尾有 /），Nginx 会把 /api/ 截掉，后端实际收到 /v1/users；若写成 proxy_pass http://api-cluster;（无斜杠），则原样转发，后端收到完整路径 /api/v1/users。
- 后端服务根路径是
/→ 用proxy_pass http://upstream/;（推荐，避免路径重复） - 后端服务挂载在子路径（如 Spring Boot 的
server.servlet.context-path=/svc）→ 用proxy_pass http://upstream/svc/; - 绝对不要混用：比如
location /api/ { proxy_pass http://upstream/api/; }，会导致路径变成/api/api/...
健康检查不是默认开启的，得手动配 keepalive 和 retry
Nginx 开源版不提供主动健康检查（如定期发 HEAD 请求探测），所谓“故障转移”仅靠连接失败触发，且默认不重试——这意味着某台后端挂了，用户第一次请求大概率直接 502，第二次才可能落到正常机器上。
要让失效感知快一点、请求更稳，得靠两个参数配合：
-
max_fails=3 fail_timeout=30s：连续 3 次失败（连接超时或 5xx）就标记该节点不可用 30 秒 -
proxy_next_upstream error timeout http_502 http_503：在location里启用，遇到这些情况才尝试下一个 upstream server -
keepalive 32（在 upstream 块里）：复用连接，减少握手开销；但必须配合proxy_http_version 1.1和proxy_set_header Connection ''才生效
没配 proxy_next_upstream，哪怕 upstream 里写了 10 台机器，只要第一台连不上，就直接 502，根本不会往下试。
权重和调度算法选错会导致流量倾斜严重
默认轮询（round-robin）假设所有后端性能一致。现实中机器配置不同、部署了不同版本服务、甚至 JVM GC 周期都会影响吞吐——这时硬套默认策略，强机器可能被打满，弱机器空转。
- 用
weight=2给高性能机器加权（如server 192.168.1.10:8080 weight=2;），注意权重是相对值，不是百分比 -
ip_hash能做简单会话保持，但不适用于有 CDN 或 NAT 的场景（所有用户 IP 可能被压成同一个出口 IP） -
hash $request_uri consistent;适合缓存友好型服务，但对动态接口可能加剧热点（比如某条慢查询 URI 被反复哈希到同一台） - 开源版没有 least_conn（最少连接数）以外的高级算法，别指望类似 “响应时间加权” 这种功能，得上 Plus 版或换 OpenResty
真正难的是监控反馈闭环：光配了 weight 不行，得看 nginx stub_status 或日志里的 $upstream_addr，确认流量确实按预期分过去了——否则权重只是自我安慰。
