Nginx 负载均衡进阶与健康检查:哈希、keepalive 池与 DNS 自愈

0 阅读12分钟

这是《Nginx 从入门到精通》系列的第 7 篇(全系列 15 篇 + 4 个实战项目)。目标:把「三台机器轮询」升级成能上生产的上游组——按场景选算法、算清会话保持的代价、用被动摘除 + proxy_next_upstream 顶住单台故障、在容器/云里靠 DNS 自愈,并能用 stream 做四层转发。

前置:第 5 篇(proxy_pass 的路径语义、502/504 的触发方式)、第 6 篇(map 与变量做 key);实验复用 lab/00-env(按需)。 本文所有数字与输出均为 nginx 1.30.6(stable)实测,文末附自测 5 题与延伸阅读。


1. 先跑起来(5 分钟实验)

实验全部跑在 lab/00-env 的栈上,但不改 lab 里的任何文件:变体配置写进 /tmp/ch7/,再起一个「第二网关」容器挂到同一个 docker 网络上,宿主监听 8090(lab-gateway 仍占 8080)。跑坏了删容器即可回滚。

cd nginx/lab/00-env && docker compose up -d && docker compose ps
mkdir -p /tmp/ch7
cat > /tmp/ch7/hash.conf <<'EOF'
worker_processes 1;
pid /tmp/nginx.pid;
error_log /var/log/nginx/err.log warn;
events { worker_connections 1024; }
http {
    upstream app_pool {
        zone app_pool 64k;
        hash $arg_uid consistent;          # 同 uid 固定落同一台
        server app1:8080 max_fails=0;
        server app2:8080 max_fails=0;
        server app3:8080 max_fails=0;
    }
    server { listen 8080; location / { proxy_connect_timeout 1s; proxy_pass http://app_pool; } }
}
EOF
docker run -d --name ch7-gw2 --network nginx-lab_default -p 127.0.0.1:8090:8080 \
  -v /tmp/ch7:/etc/nginx/lab2:ro nginx:stable-alpine \
  nginx -c /etc/nginx/lab2/hash.conf -g 'daemon off;'

三条命令对应本章三条主线:算法(键怎么落)→ 摘流(故障怎么发现)→ 重试(故障怎么兜住)。

# ① 300 个 uid 落到哪台
for i in $(seq 1 300); do curl -s "localhost:8090/?uid=u$i" | head -1; done | cut -d= -f2 | sort | uniq -c
#   99 app1 / 102 app2 / 99 app3
# ② 删掉 app2 再起一个新网关:统计「换了机器」的 uid 占比
grep -v 'server app2:8080' /tmp/ch7/hash.conf > /tmp/ch7/hash2.conf
docker rm -f ch7-gw2 && docker run -d --name ch7-gw2 --network nginx-lab_default \
  -p 127.0.0.1:8090:8080 -v /tmp/ch7:/etc/nginx/lab2:ro nginx:stable-alpine \
  nginx -c /etc/nginx/lab2/hash2.conf -g 'daemon off;'
# 重跑 ① 的循环并与上次结果对比 → 实测 migrated=102/300 = 34.00%(理论 1/3 = 33.3%)
# ③ 停掉池里的一台(此刻池是 app1+app3),看 max_fails=0 的代价
docker stop lab-app3
for u in u1 u2 u3 u4 u5 u6; do curl -s -o /dev/null -w "uid=$u code=%{http_code} rt=%{time_total}\n" "localhost:8090/?uid=$u"; done
# uid=u1 code=200 rt=1.0078  ← 配置里 max_fails=0,app3 永不被摘
# uid=u2 code=200 rt=1.0020     所以散列到 app3 的请求每次都白等 1s 才切 app1
# uid=u3 code=200 rt=0.0412  ← 命中 app1;u4 0.9851 / u5 1.0029 / u6 0.0422
docker start lab-app3
# 错误日志里只有 upstream timed out,没有 temporarily disabled —— 摘流没发生

第二网关的配置校验与 reload 一律这样走(必须带 -c,理由见第 1 篇的坑 4):

docker exec ch7-gw2 nginx -t -c /etc/nginx/lab2/hash.conf
docker kill -s HUP ch7-gw2                                  # 等价 nginx -s reload

2. 核心概念

2.1 算法选型:先问「谁需要粘住」

算法选谁节点增减后果何时必须用改错会怎样
round-robin(默认)依次发均匀无状态服务有状态会话被打散,用户反复登录
least_conn活跃连接最少均匀请求耗时差异大(/slow、下载、长轮询)慢请求堆在同一台
random two least_conn随机抽 2 台再取连接少的均匀大集群(≥10 台)抗锯齿用默认 rr 时慢节点被压垮
hash $key按 key 取模大部分键重映射后端有本地缓存缓存全失效,回源打穿数据库
hash $key consistentketama 环只迁移 ≈1/N 的键同上,且节点会增减用非 consistent 版做缓存分片=每次扩容都雪崩
ip_hash按客户端 IP大部分重映射没有 cookie 的老系统NAT/CGNAT 后整栋楼压到一台
sticky cookie(≥1.29.6)按 nginx 下发的 cookie新增节点只影响未粘住的客户端需要在负载均衡层做会话保持用 ip_hash 顶替,IPv6 与代理后面全错

random two least_conn 是 Power-of-Two-Choices:只多打一次随机数,就能把「一台慢、全场排队」的概率压下去,成本几乎为零。大集群里优先选它而不是 least_conn——least_conn 在惊群瞬间会把所有新请求同时投给同一个「当前最空闲」的节点。

2.2 一致性哈希:为什么只迁移 1/N

hash key 的朴素实现是 hash(key) % 节点数,节点数一变,几乎所有键的余数都变了——实测 300 个 uid 从 3 台减到 2 台,178/300 = 59.33% 的 uid 换了机器;加 consistent 后走 ketama 环,只有落在被删节点上的那段区间需要搬走,实测 102/300 = 34.00%,正好是 1/3。这就是「缓存分片必须开 consistent」的量化依据:不做,一次扩容等于全站缓存同时失效。

key 的选择决定命中的稳定性:hash $arg_uid 便于压测复现(浏览器地址栏就能指定用户),上线后应换成 hash $cookie_uid 或 hash $http_x_user_id,否则 URL 上的参数一丢就退化成随机分配。参数一丢,命中率暴跌,但请求依旧「成功」,属于最难发现的一类问题。

2.3 被动健康检查的语义

开源版只有被动检查:靠真实请求的失败结果判断节点死活。

事实值依据
max_fails 默认1ngx_http_upstream_module 文档
fail_timeout 默认10s(既是统计窗口,也是摘除时长)同上
「失败」的定义由 proxy_next_upstream 决定(默认 error timeout)同上
max_fails=0关闭计数,节点永不被摘实测:散列到坏节点的请求每次都白等 1s,靠重试拿 200(见第 1 节 ③)

实测两处反直觉行为,必须记住:

  1. 故障转移不是免费的。 三台里停一台、max_fails=3,前 3 次落到坏节点上的请求各付 ~1s 的 proxy_connect_timeout 才切走(实测 rt=1.008 / 0.919),客户端看得到抖动。所以 proxy_connect_timeout 要小(2s、1s),别用默认 60s。
  2. 计数只在成功后清零。 节点被摘、fail_timeout 到期后放回池子,若第一次请求又失败会立刻再次摘除:实测日志里两次 upstream server temporarily disabled 相隔正好一个 fail_timeout,中间只夹一条超时记录,因为 fails 还没被任何一次成功响应归零。恢复期要按「失败一次就再摘 10s」估算抖动时长。

2.4 主动健康检查:开源版没有 health_check

health_check 是 Nginx Plus 专有指令,开源版 nginx -t 直接报 unknown directive。能落地的替代方案:

方案代价适用
外置探活 + 改 down/reload需要模板生成配置,秒级生效靠 reload传统虚机
OpenResty/lua 定时探活写共享内存引入 Lua 栈(见第 11 篇)已经在用 OpenResty
上游服务注册到 DNS,靠 resolve 摘除依赖服务发现容器/云原生(见 2.7)
只用被动检查零成本,但首个用户吃故障小流量、可容忍一次抖动

关键结论:proxy_next_upstream 不能替代探活。它只在「已经有请求打到坏节点」之后才起作用,永远慢一拍;而 max_fails 又是「最近 fail_timeout 内的历史」,节点刚恢复时它同样慢一拍。要靠主动探活解决的问题,只能引入上面第二/第三种方案。

同属 Plus 专有的还有两个「让流量更平滑」的参数:server … slow_start=30s(慢启动:节点恢复后 30s 内权重从 0 线性升到全额)与 queue 100 timeout=5s(max_conns 打满时排队而不是立刻 502)。开源版替代方案:慢启动用分批改权重 + reload 或靠 max_conns 限制单点速率近似;排队用前置限流(第 10 篇的 limit_req)或把 proxy_next_upstream_tries 调大,代价是故障时延迟被放大。别在开源版配置里硬写这两个参数:实测 queue 100 timeout=5s; 报 unknown directive "queue",slow_start=30s 报 invalid parameter "slow_start=30s"。

2.5 upstream keepalive:1.29.7 是一道分水岭

这是本章最容易被旧教程带偏的地方。用探针后端(响应体里带上「本次请求所用 TCP 连接的源端口」)连打 20 次,数不同端口:

环境配置20 次请求用到的上游连接数
nginx:stable-alpine(1.30.6)默认(什么都不写)1(复用了)
nginx:stable-alpine(1.30.6)proxy_http_version 1.0 + Connection "Close"20(每次新建)
nginx:1.24-alpine默认(什么都不写)20(GET / HTTP/1.0)

原因:≥1.29.7 起 nginx 到上游默认使用 HTTP/1.1 且默认开 keep-alive,proxy_http_version 1.1; + proxy_set_header Connection ""; 这两行的历史使命结束了;文档里 keepalive 的默认值已写成 keepalive 32 local——连接池默认有 32 个槽、且不跨 location 共享。在 ≤1.29.6 上这两行仍然是必需品,少了它 nginx 会以 HTTP/1.0 + Connection: close 发请求,每条请求一次握手。

还有三个容易混的点:keepalive N 的 N 是每 worker 的空闲连接池上限,估法是「上游并发 ÷ worker 数 × 0.8 起调」;proxy_socket_keepalive on(≥1.15.6)只打开 TCP 的 SO_KEEPALIVE,跟连接池毫无关系;keepalive 必须与 proxy_http_version 1.1 + 清空 Connection 头同时成立,否则池子里永远进不去连接。

2.6 会话保持四方案决策表

场景首选不选的理由
无状态 API(JWT)不用会话保持,random two least_conn粘住只会放大不均匀
有状态会话(老 session 在内存)sticky cookie(≥1.29.6)ip_hash 在 NAT 后塌缩、IPv6 直接失效
后端有本地缓存/分片hash $key consistent会话保持类方案不解决缓存亲和
客户端是移动端/长连接least_conn + 应用侧 token长连接天然按连接分,粘 cookie 意义有限
容器化、Pod 随时重建sticky cookie + resolve静态 ip_hash 在 IP 变化后全乱
不能改应用也不能下发 cookieip_hash 兜底必须接受 CGNAT 的集中风险

sticky cookie 的实测行为(三台 route=a/b/c):无 cookie 时按轮询走(app1, app2, app3, app1…),首个响应下发 Set-Cookie: srv_id=a,之后带 cookie 的 4 次请求全部落在 app1;把 app1 停掉后,第一个请求付掉 1.02s 的 proxy_connect_timeout 才切到 app2,并且 Set-Cookie 被改写成 srv_id=b(响应头里的 X-App: app2 与 cookie 值一致);app1 在 fail_timeout 后回池,浏览器手里的老 cookie(srv_id=a)仍能粘回 app1。换句话说:粘性只在「目标节点可用」时成立,故障期间客户端会被重新绑定。

2.7 DNS 动态解析:容器与云的命门

upstream 里的域名默认只在启动/reload 时解析一次。容器重启换 IP 后,nginx 会把流量一直打向旧 IP,直到有人 reload——这是「Pod 明明 healthy 却大量 502」的头号原因。两条自愈路径:

写法解析时机版本代价
server app1:8080;(静态名)启动时一次全版本IP 变了就 502
set $be svc.lab:8080; proxy_pass http://$be;每次请求走 resolver 缓存1.1.x 起每次请求过一次缓存查找,配置文件里不能再用静态 upstream 特性
upstream { zone …; server svc.lab:8080 resolve; }按 valid= 周期后台重解析≥1.27.3必须有 zone + resolver,否则启动即失败

实测(resolver 172.30.0.12 valid=5s ipv6=off,svc.lab 从 app1 改指 app2):改完立刻打,仍然返回 app=app1(缓存未过期);等 6s 后自动变 app=app2,全程没有 reload。反向验证:变量形式但漏掉 resolver,请求当场 502,错误日志写 no resolver defined to resolve svc.lab——这个报错只在运行期出现,nginx -t 查不出来。

2.8 stream:四层转发不改协议

http 块解 HTTP、stream 块只搬字节:TCP/UDP 转发、MySQL/Redis/DNS、TLS 按 SNI 分流(ssl_preread)都在这里做。它与 http 是平级的顶层块,不能互相嵌套。实测把 nc 发出的原始 HTTP 报文经 listen 3307 转发到 app1,返回 HTTP/1.1 200 OK——说明 nginx 没有解析也没有改写协议。加 proxy_protocol on 后,用裸 TCP 监听抓到的第一批字节是 PROXY TCP4 172.30.0.1 172.30.0.6 59084 3308\r\nHELLO\n:真实客户端 IP 与端口就写在这一行文本里(后端必须支持 PROXY 协议,否则只会把它当垃圾数据)。实验 5 用「只认 PROXY 头的 nginx 后端」把这件事变成可验收的结果——后端直接回显 real_ip=。

一个必须知道的默认值:proxy_half_close 默认 off。此时客户端发完请求就半关(printf … | nc 的典型行为),nginx 会立刻把上游连接一起关掉,后端连回包都发不出去(实测后端 BrokenPipeError、客户端零字节)。加 proxy_half_close on(≥1.21.4)后同一条命令立刻拿到 HTTP/1.1 200 OK。

UDP 也在这个块里,只需把监听改成 listen 53 udp;,并用 proxy_responses 1 告诉 nginx 一个请求期望几个响应包(不设则不限,会话结束靠 proxy_timeout)。三个经典用途:DNS 53 转发到内网解析器、MySQL listen 3307; proxy_pass mysql;、Redis listen 6380; proxy_pass redis;。四层池子同样支持 max_fails/fail_timeout、weight、backup,但没有 hash $cookie_*(四层看不到 HTTP 头),要按客户端 IP 粘只能用 hash $remote_addr consistent。

3. 指令详解

指令默认值上下文说明与坑
hash key [consistent]—upstream朴素版增减节点重映射绝大部分键(实测 59.33%);consistent 只迁 ≈1/N(实测 34.00%)。key 用变量,别写死
random [two [least_conn]]two 时用 least_connupstream≥1.15.1。大集群首选,替代 least_conn 防惊群;backup 不能与它同用
ip_hash—upstream只看客户端 IP 前三段(IPv4);NAT/CGNAT 后塌缩,IPv6 场景失效;不能与 backup/hash 同用
sticky cookie name …—upstream≥1.29.6 才开源(1.29.5 报 unknown directive)。支持 cookie/route/learn 三种;httponly/secure/samesite 建议全开
server … max_conns=N0(不限)upstream≥1.11.5 开源。无 zone 时是每 worker 计数,多 worker 下实际并发可到 N×worker
server … max_fails= fail_timeout=1 / 10supstreammax_fails=0 关闭计数=永不摘除;恢复后第一次失败立刻再摘(计数未清零)
server … backup / down—upstreambackup 只在主节点全不可用时接流量;与 hash/ip_hash/random 互斥
server … resolve—upstream≥1.27.3 开源。必须同时有 zone 与本块/http 块的 resolver,缺一启动失败
keepalive N32 local(≥1.29.7);≤1.29.6 为关闭upstreamN 是每 worker 空闲池上限;local 参数(≥1.29.7)禁止跨 location 共享
keepalive_requests / keepalive_time / keepalive_timeout1000(1.19.10 起)/ 1h / 60supstream三条一起决定连接何时回收;只调大 keepalive_requests 会推高每连接内存
proxy_http_version + proxy_set_header Connection ""1.1(≥1.29.7);1.0(≤1.29.6)http/server/location≤1.29.6 必须显式写这两行;≥1.29.7 冗余但无害,跨版本部署建议保留
proxy_next_upstreamerror timeouthttp/server/location默认不含 5xx:后端返回 503 会直接甩给用户;要切备用必须显式加 http_502 http_503
proxy_next_upstream_tries / _timeout0 / 0(不限)http/server/location≥1.7.5。不限次数时一次请求可能把所有节点都试一遍,放大延迟
resolver … valid= ipv6=off按响应 TTLhttp/server/locationvalid= 覆盖 TTL;ipv6=off 在只有 A 记录的环境能少一次失败查询
stream 的 proxy_protocol / proxy_half_close / proxy_timeoutoff / off / 10mstream/serverproxy_protocol≥1.9.2;proxy_half_close≥1.21.4(默认 off 会截断半关客户端的回包)

4. 完整配置示例

落盘路径与 lab 一致:/etc/nginx/lab/nginx.conf(容器里由 -c 指定)。

worker_processes  1;
error_log  /var/log/nginx/lab_error.log warn;
pid        /var/run/nginx.pid;

events { worker_connections 1024; }

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # 关键字段:urt 是重试链上的每一段耗时;up 多值=发生了重试
    log_format  main  '$remote_addr "$request" $status '
                      'rt=$request_time urt=$upstream_response_time '
                      'up=$upstream_addr us=$upstream_status ct=$upstream_connect_time';
    access_log  /var/log/nginx/lab_access.log  main;

    sendfile on;
    keepalive_timeout 65;
    gzip on;
    gzip_types text/css application/javascript application/json text/plain;

    # ① 容器/云:Docker 内置 DNS,5~10s 一轮,IP 变化即可自愈
    resolver 127.0.0.11 valid=10s ipv6=off;
    resolver_timeout 2s;

    upstream app_pool {
        zone app_pool 64k;                 # resolve / max_conns 跨 worker 共享的前提

        # ② 会话保持:一致性哈希,增删节点只迁 ≈1/N 的键
        #    要改成 cookie 亲和就换成 sticky cookie srv_id(≥1.29.6),二者不要并用
        hash $arg_uid consistent;

        # ③ max_conns 防单点过载;max_fails/fail_timeout 是开源版唯一的自动摘流手段
        server app1:8080 resolve max_fails=3 fail_timeout=10s max_conns=200;
        server app2:8080 resolve max_fails=3 fail_timeout=10s max_conns=200;
        server app3:8080 resolve max_fails=3 fail_timeout=10s max_conns=200;

        # ④ 上游长连接池。≥1.29.7 默认已有 32 条且不跨 location 共享;
        #    显式写是为了控制池大小与空闲回收时机
        keepalive 64;
        keepalive_requests 1000;
        keepalive_timeout 60s;
    }

    server {
        listen 80;
        server_name _;

        root  /usr/share/nginx/html;
        index index.html;
        # /healthz、/nginx_status、/static/ 三块沿用 conf.d/default.conf,本节不改
        location /api/ {
            proxy_pass http://app_pool/;
            proxy_connect_timeout 2s;      # 别用默认 60s:坏节点会让客户端干等
            proxy_read_timeout 10s;

            # ⑤ 只有幂等请求才把 5xx 当可重试;写接口要重试必须显式加 non_idempotent
            proxy_next_upstream error timeout http_502 http_503;
            proxy_next_upstream_tries 2;          # 最多试 2 台,防止故障放大
            proxy_next_upstream_timeout 3s;

            # ⑥ ≤1.29.6 这两行是必需品;≥1.29.7 已是默认值,保留只为跨版本一致
            proxy_http_version 1.1;
            proxy_set_header Connection "";

            proxy_set_header Host              $host;
            proxy_set_header X-Real-IP         $remote_addr;
            proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        location /slow/ {
            proxy_pass http://app_pool;
            proxy_read_timeout 5s;
            proxy_next_upstream error timeout http_502 http_503;
            proxy_next_upstream_tries 2;
        }

        location / { try_files $uri $uri/ /index.html; }
    }
}

相对 lab/00-env 改了这几行(conf.d/default.conf 的 location 不动):

位置原来现在为什么
log_format main无重试链字段加 us= ct=判断是否发生重试、是否复用连接
upstream app_pool纯轮询hash $arg_uid consistent会话保持 + 缓存亲和
三个 server无 max_connsmax_conns=200防单点过载(数值按压测定,见第 12 篇)
upstream 末尾无池参数keepalive 64 + 两条回收参数显式控制池大小
resolver valid=5s10s5s 对上游不友好(每 5s 一次 DNS 查询 × 节点数)
/api/只有超时加 next_upstream 三件套5xx/超时自动切节点并限次

5. 必做实验

实验 1:一致性哈希的键迁移比例(理论 ≈1/N)

cd /tmp/ch7 && grep -v 'server app2:8080' hash.conf > hash2.conf
run() { docker rm -f ch7-gw2 >/dev/null; docker run -d --name ch7-gw2 \
  --network nginx-lab_default -p 127.0.0.1:8090:8080 -v /tmp/ch7:/etc/nginx/lab2:ro \
  nginx:stable-alpine nginx -c /etc/nginx/lab2/$1 -g 'daemon off;' >/dev/null; sleep 2; }
run hash.conf;  for i in $(seq 1 300); do printf "u%s %s\n" $i "$(curl -s "localhost:8090/?uid=u$i" | head -1 | cut -d= -f2)"; done > m3.txt
run hash2.conf; for i in $(seq 1 300); do printf "u%s %s\n" $i "$(curl -s "localhost:8090/?uid=u$i" | head -1 | cut -d= -f2)"; done > m2.txt
join m3.txt m2.txt | awk '{n++; if($2!=$3) m++} END{printf "consistent: migrated=%d/%d = %.2f%%\n", m, n, 100*m/n}'
# consistent: migrated=102/300 = 34.00%
# 把两处 hash 都改成 hash $arg_uid;(去掉 consistent)再来一遍:
# plain     : migrated=178/300 = 59.33%

预期就是上面两行注释。为什么是这个结果:ketama 把 hash(key) 映射到 2^32 环上,节点各占若干虚拟节点区间;删掉一台只回收它占的那段环,其余键的落点不变,所以比例≈1/N。朴素取模是 hash % N,分母一变全体重算。

实验 2:被动摘除 + 切 backup(503 也能重试)

# 用一个「永远返回 503」的 nginx 当坏后端(不用写任何脚本)
docker run -d --name ch7-503 --network nginx-lab_default --network-alias r503 nginx:stable-alpine \
  sh -c 'echo "server{listen 8080;location /{return 503;}}" > /etc/nginx/conf.d/default.conf && nginx -g "daemon off;"'
cat > /tmp/ch7/nu_off.conf <<'EOF'
worker_processes 1;
events { worker_connections 1024; }
http {
    log_format nu '$request status=$status up=$upstream_addr urt=$upstream_response_time';
    access_log /var/log/nginx/nu.log nu;
    upstream app_pool { server r503:8080 max_fails=0; server app1:8080 backup; }
    server { listen 8080; location / { proxy_pass http://app_pool; } }
}
EOF
sed 's|proxy_pass http://app_pool;|proxy_next_upstream error timeout http_502 http_503;\n            proxy_pass http://app_pool;|' \
  /tmp/ch7/nu_off.conf > /tmp/ch7/nu_on.conf

两份配置分别起网关后各打两次请求(nginx -c …/nu_off.conf 与 …/nu_on.conf),实测日志:

配置客户端看到up= 字段(IP 随环境变化)
默认(error timeout)code=503up=172.27.0.6:8080(一个值,没重试)
http_502 http_503code=200up=172.27.0.6:8080, 172.27.0.2:8080(逗号=重试链,第二个是 backup)

为什么:默认值不含 5xx,503 属于「后端活着但拒绝服务」,nginx 认为这不是传输错误,直接把响应交给客户端。显式加了 http_503 才进入重试。结论:up 出现逗号就是重试链,urt 也是逗号分隔的对应耗时——排障时先看这两个字段,比 $status 信息量大得多。

实验 3:max_conns 与上游连接池

# /tmp/ch7/mc_on.conf:upstream app_pool { server app1:8080 max_conns=1;
#   server app2:8080 max_conns=1; server app3:8080; }(location 里再加 proxy_read_timeout 5s)
rm -f o; for i in $(seq 1 6); do (curl -s localhost:8090/slow >> o) & done; wait
grep -o 'app=app[0-9]' o | sort | uniq -c
#  1 app=app1 / 1 app=app2 / 4 app=app3   ← 设了 max_conns;不设时是 2/2/2(对照组)

为什么:max_conns 数的是「正在处理的请求数」而不是「TCP 连接数」,所以配了 keepalive 也不会把池子里的空闲连接算进去;没有 zone 时它是每 worker 的上限,多 worker 下要把值除以 worker 数来理解。

连接池验证需要一个「能报出连接源端口」的探针后端,自己造十行就够:

cat > /tmp/ch7/probe.py <<'EOF'
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class H(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"
    def do_GET(self):
        b = f"conn={self.client_address[1]}\n".encode()    # 本次请求所在 TCP 连接的源端口
        self.send_response(200); self.send_header("Content-Length", str(len(b)))
        self.end_headers(); self.wfile.write(b)
    def log_message(self, *a): pass
ThreadingHTTPServer(("0.0.0.0", 8080), H).serve_forever()
EOF
docker run -d --name ch7-probe --network nginx-lab_default --network-alias probe1 \
  -v /tmp/ch7:/srv:ro python:3-alpine python /srv/probe.py
# 网关 upstream 只放 probe1,连打 20 次数不同 conn:
for i in $(seq 1 20); do curl -s localhost:8090/; done | sed 's/.*conn=//' | sort -u | wc -l

实测:默认配置在 nginx:stable-alpine(1.30.6)上是 1(20 个请求复用一条 TCP);把它改成 proxy_http_version 1.0; proxy_set_header Connection "Close"; 后是 20;同样「什么都不写」放到 nginx:1.24-alpine 上也是 20(请求行是 GET / HTTP/1.0)。三组数字就是 2.5 节那张表的来源。

为什么:连接池是「主动保留空闲连接」的机制,它必须先有一个符合 HTTP/1.1 语义的连接——HTTP/1.0 默认一请求一连接,nginx 用完即关,池子里永远是空的。

实验 4:dnsmasq + resolver 验证动态解析

mkdir -p /tmp/ch7/dns && echo '172.30.0.4 svc.lab' > /tmp/ch7/dns/lab.hosts   # 先指向 app1
docker run -d --name ch7-dns --network nginx-lab_default -v /tmp/ch7/dns:/etc/dnsmasq.d:ro \
  alpine:latest sh -c 'apk add --no-cache dnsmasq >/dev/null 2>&1 &&
    exec dnsmasq -k --no-resolv --addn-hosts=/etc/dnsmasq.d/lab.hosts'
# 网关:resolver <ch7-dns 的 IP> valid=5s ipv6=off; upstream { zone app_pool 64k; server svc.lab:8080 resolve max_fails=0; }
echo '172.30.0.3 svc.lab' > /tmp/ch7/dns/lab.hosts && docker kill -s HUP ch7-dns
for i in 1 2; do curl -s localhost:8090/ | head -1; done   # app=app1 app=app1(缓存未过期)
sleep 6; for i in 1 2 3; do curl -s localhost:8090/ | head -1; done  # app=app2 ×3

为什么:resolve 让 nginx 起一个后台解析任务,按 valid= 周期重查;valid=5s 意味着改动最多 5 秒后生效,所以立刻打还是 app=app1、等 6s 就变 app=app2,全程没有 reload。

两个必须记住的对照:把 server svc.lab:8080 resolve 换成静态 server app1:8080;,改 hosts 后不管等多久都不生效(要 reload);把 proxy_pass 写成变量形式 set $be "svc.lab:8080"; proxy_pass http://$be; 但漏掉 resolver,请求立刻 502,日志写 no resolver defined to resolve svc.lab。

实验 5:stream 四层转发与 PROXY 协议

stream {
    upstream app_tcp { server app1:8080; server app2:8080; }
    server { listen 3307; proxy_half_close on; proxy_timeout 5s; proxy_pass app_tcp; }
    server { listen 3308; proxy_protocol on; proxy_pass pp1:8080; }   # pp1 = 只认 PROXY 头的后端
}
# 后端:一份只接受 PROXY 头的 nginx,把真实客户端 IP 打回来
cat > /tmp/ch7/pp_backend.conf <<'EOF'
worker_processes 1;
events { worker_connections 128; }
http {
    server {
        listen 8080 proxy_protocol;        # 少了 PROXY 头直接连接失败
        set_real_ip_from 0.0.0.0/0;
        real_ip_header proxy_protocol;
        location / { return 200 "real_ip=$remote_addr\n"; }
    }
}
EOF
docker run -d --name ch7-pp --network nginx-lab_default --network-alias pp1 \
  -v /tmp/ch7:/etc/nginx/lab2:ro nginx:stable-alpine \
  nginx -c /etc/nginx/lab2/pp_backend.conf -g 'daemon off;'
# 第二网关需把容器 3307/3308 映射到宿主 13307/13308(-p 13307:3307 -p 13308:3308)
for i in 1 2 3; do printf 'GET / HTTP/1.1\r\nHost: x\r\nConnection: close\r\n\r\n' | nc 127.0.0.1 13307 | head -1; done
# HTTP/1.1 200 OK  ×3(四层透传,nginx 没解析协议,也没改 Host)
(printf 'GET / HTTP/1.1\r\nHost: x\r\n\r\n'; sleep 2) | nc 127.0.0.1 13308 | tail -1
# real_ip=172.30.0.1      ← 真实客户端 IP 由 PROXY 头带过来

为什么:stream 只在 TCP 字节流层面搬运,Connection: close 由后端自己处理,所以三次都是 200;而 PROXY 协议只是在正式数据前插一行文本,real_ip_header proxy_protocol 才让后端把它当客户端地址。

把 proxy_half_close on 去掉,同一条 printf … | nc 命令返回零字节,后端报 BrokenPipeError:客户端半关后 nginx 把上游连接也关了,回包来不及发。这是「stream 转发 HTTP 时莫名其妙没响应」的真实原因。

6. 验收自测(5 题)

Q1. 三台节点的池子里,为什么 hash $cookie_uid consistent 扩容到 4 台时只有约 25% 的用户会换机器?换成 hash $cookie_uid 会怎样?

答案要点:ketama 环上每个节点只拥有一段区间,加节点只从相邻区间「借」键,迁移量≈1/N≈25%(实测 3→2 为 34%);朴素 hash 用 hash % N,分母变化导致全体重算(实测 59.33% 换机器),后端本地缓存全部失效。

Q2. max_fails 默认值是多少?把它设成 max_fails=0 会发生什么?节点从故障中恢复后,第一次请求失败会怎样?

答案要点:默认 1,窗口与摘除时长都由 fail_timeout(默认 10s)决定;max_fails=0 关闭失败计数,故障节点会一直留在池子里接流量(实测每次白等 1s 再靠重试拿 200);恢复后 fails 未被成功响应清零,第一次失败会立刻再次摘除一个 fail_timeout。

Q3. 后端返回 503,proxy_next_upstream 用默认值,客户端会拿到什么?要切到备用节点要怎么做?

答案要点:默认只有 error timeout,不含 5xx,客户端直接拿到 503,日志 up= 只有一个地址;必须显式加 http_503(必要时 http_502),再配 proxy_next_upstream_tries 限次;up= 出现逗号即发生了重试。非幂等请求默认不重试,要重试得加 non_idempotent。

Q4. 在 nginx 1.24 上配 keepalive 32,为什么还必须写 proxy_http_version 1.1 和 proxy_set_header Connection ""?在 1.29.7 上还要写吗?

答案要点:≤1.29.6 默认用 HTTP/1.0 发请求,HTTP/1.0 没有长连接语义,池子进不去连接(实测每条请求一条连接);清空 Connection 头是为了别把客户端的 Connection: close 透给上游。≥1.29.7 默认就是 HTTP/1.1 + keep-alive(文档默认值 keepalive 32 local),两行冗余但无害。

Q5. 容器里 Pod 换了 IP,nginx 一直 502,nginx -t 却通过。为什么?怎么修?

答案要点:upstream 里的域名只在启动/reload 时解析一次,nginx -t 只校验语法不校验可达性。修法:zone + server … resolve + resolver … valid=(≥1.27.3),或变量形式 proxy_pass http://$be(必须配 resolver,否则运行期 502 no resolver defined)。顺带把 proxy_connect_timeout 调小,让故障节点少拖累用户。

7. 常见坑

  1. ip_hash 上了 CDN/NAT 就塌缩。现象:某台后端 CPU 打满,其余闲置。根因:ip_hash 只取客户端 IP,NAT 后整段用户共用一个出口 IP。正解:改用 sticky cookie(≥1.29.6)或 hash $cookie_uid。
  2. max_fails=0 当成「关掉健康检查更稳」。现象:一台后端挂了两小时仍在接流量,凡轮到它的请求都多等一个 proxy_connect_timeout(实测 1s 以上)。根因:0 表示不计数,节点永不被摘,只剩 proxy_next_upstream 兜底。正解:保留 max_fails=3,fail_timeout 调成 5~10s。
  3. backup 配在 hash/ip_hash/random 上。现象:nginx -t 直接报 balancing method does not support parameter "backup"。根因:文档明确 backup 不能与这三种算法同用。正解:备份节点放独立 upstream,或用 error_page 兜底。
  4. 只写 keepalive 32 不写 proxy_http_version 1.1(≤1.29.6)。现象:配了池子但 ss 里全是一闪而过的短连接。根因:HTTP/1.0 语义下连接不可复用。正解:三件套 keepalive + proxy_http_version 1.1 + Connection ""。
  5. 用变量形式 proxy_pass 却漏了 resolver。现象:nginx -t 通过,请求全 502。根因:变量形式强制走运行期解析。正解:配 resolver(容器里是 127.0.0.11),并接受每请求一次缓存查找的成本。
  6. proxy_next_upstream 不限次。现象:三台全挂时单个请求要等 3×connect_timeout,客户端超时雪崩。根因:proxy_next_upstream_tries 默认 0(不限)。正解:tries 2 + timeout 3s。
  7. stream 转发 HTTP 拿不到响应。现象:nc 连上但零字节,后端 BrokenPipeError。根因:proxy_half_close 默认 off,客户端半关即上游被关。正解:proxy_half_close on(≥1.21.4);长期方案是七层用 http 块。
  8. 以为 proxy_socket_keepalive on 就是上游长连接。现象:开了却没减少握手。根因:它只打开 TCP 的 SO_KEEPALIVE(探活),与连接池无关。正解:连接池靠 keepalive。

8. 延伸阅读

文档页解决什么问题
ngx_http_upstream_modulehash/random/max_conns/sticky/keepalive 的权威默认值与各自的版本行
ngx_http_proxy_moduleproxy_next_upstream 的默认值与 proxy_http_version 的 1.29.7 变更
Keep-alive to upstreams is now default in NGINX 1.29.7官方博客:为什么 1.29.7 起不用再写那两行,以及 keepalive … local 的含义
ngx_stream_proxy_moduleproxy_protocol/proxy_half_close/proxy_timeout 的准确定义
ngx_stream_core_modulelisten … udp 与 stream 块结构
resolvervalid= 与 DNS TTL 的关系,动态解析的唯一入口
nginx CHANGESsticky/resolve 等开源版本门槛的唯一权威出处

章节依赖:本篇建立在第 5 篇(proxy_pass 路径语义与超时)与第 6 篇(用 map/变量造 key)之上;第 8 篇的 proxy_cache 直接复用本篇的 upstream 与 zone,第 9 篇用本篇写入日志的 up=/urt= 多值字段做重试链排障,第 13 篇的 VIP + 双网关解决本篇仍存在的「网关自身是单点」。


系列导航:第 1 篇进程模型 → 第 2 篇安装升级 → 第 3 篇配置语法 → 第 4 篇静态站与 location → 第 5 篇反向代理 → 第 6 篇 rewrite 与 server_name → 第 7 篇(本篇)负载均衡进阶与健康检查 → 第 8 篇缓存 → 第 9 篇日志排障 → 第 10 篇 HTTPS 与安全 → 第 11 篇 Lua 与 OpenResty → 第 12 篇性能调优 → 第 13 篇高可用架构与网关 → 第 14 篇可观测性与工程化 → 第 15 篇故障案例库