这是《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)。跑坏了删容器即可回滚。
bash
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;'
三条命令对应本章三条主线:算法(键怎么落)→ 摘流(故障怎么发现)→ 重试(故障怎么兜住)。
bash
# ① 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
bash
# ② 删掉 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%)
bash
# ③ 停掉池里的一台(此刻池是 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):
bash
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 consistent |
ketama 环 | 只迁移 ≈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 默认 |
1 | ngx_http_upstream_module 文档 |
fail_timeout 默认 |
10s(既是统计窗口,也是摘除时长) | 同上 |
| 「失败」的定义 | 由 proxy_next_upstream 决定(默认 error timeout) |
同上 |
max_fails=0 |
关闭计数,节点永不被摘 | 实测:散列到坏节点的请求每次都白等 1s,靠重试拿 200(见第 1 节 ③) |
实测两处反直觉行为,必须记住:
- 故障转移不是免费的。 三台里停一台、
max_fails=3,前 3 次落到坏节点上的请求各付 ~1s 的proxy_connect_timeout才切走(实测rt=1.008 / 0.919),客户端看得到抖动。所以proxy_connect_timeout要小(2s、1s),别用默认 60s。 - 计数只在成功后清零。 节点被摘、
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 变化后全乱 |
| 不能改应用也不能下发 cookie | ip_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_conn |
upstream |
≥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=N |
0(不限) | upstream |
≥1.11.5 开源。无 zone 时是每 worker 计数,多 worker 下实际并发可到 N×worker |
server ... max_fails= fail_timeout= |
1 / 10s | upstream |
max_fails=0 关闭计数=永不摘除;恢复后第一次失败立刻再摘(计数未清零) |
server ... backup / down |
--- | upstream |
backup 只在主节点全不可用时接流量;与 hash/ip_hash/random 互斥 |
server ... resolve |
--- | upstream |
≥1.27.3 开源。必须同时有 zone 与本块/http 块的 resolver,缺一启动失败 |
keepalive N |
32 local(≥1.29.7);≤1.29.6 为关闭 |
upstream |
N 是每 worker 空闲池上限;local 参数(≥1.29.7)禁止跨 location 共享 |
keepalive_requests / keepalive_time / keepalive_timeout |
1000(1.19.10 起)/ 1h / 60s | upstream |
三条一起决定连接何时回收;只调大 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_upstream |
error timeout |
http/server/location |
默认不含 5xx :后端返回 503 会直接甩给用户;要切备用必须显式加 http_502 http_503 |
proxy_next_upstream_tries / _timeout |
0 / 0(不限) | http/server/location |
≥1.7.5。不限次数时一次请求可能把所有节点都试一遍,放大延迟 |
resolver ... valid= ipv6=off |
按响应 TTL | http/server/location |
valid= 覆盖 TTL;ipv6=off 在只有 A 记录的环境能少一次失败查询 |
stream 的 proxy_protocol / proxy_half_close / proxy_timeout |
off / off / 10m | stream/server |
proxy_protocol≥1.9.2;proxy_half_close≥1.21.4(默认 off 会截断半关客户端的回包) |
4. 完整配置示例
落盘路径与 lab 一致:/etc/nginx/lab/nginx.conf(容器里由 -c 指定)。
nginx
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_conns |
max_conns=200 |
防单点过载(数值按压测定,见第 12 篇) |
upstream 末尾 |
无池参数 | keepalive 64 + 两条回收参数 |
显式控制池大小 |
resolver valid= |
5s | 10s | 5s 对上游不友好(每 5s 一次 DNS 查询 × 节点数) |
/api/ |
只有超时 | 加 next_upstream 三件套 |
5xx/超时自动切节点并限次 |
5. 必做实验
实验 1:一致性哈希的键迁移比例(理论 ≈1/N)
bash
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 也能重试)
bash
# 用一个「永远返回 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=503 |
up=172.27.0.6:8080(一个值,没重试) |
http_502 http_503 |
code=200 |
up=172.27.0.6:8080, 172.27.0.2:8080(逗号=重试链,第二个是 backup) |
为什么 :默认值不含 5xx,503 属于「后端活着但拒绝服务」,nginx 认为这不是传输错误,直接把响应交给客户端。显式加了 http_503 才进入重试。结论:up 出现逗号就是重试链,urt 也是逗号分隔的对应耗时------排障时先看这两个字段,比 $status 信息量大得多。
实验 3:max_conns 与上游连接池
bash
# /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 数来理解。
连接池验证需要一个「能报出连接源端口」的探针后端,自己造十行就够:
bash
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 验证动态解析
bash
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 协议
nginx
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 头的后端
}
bash
# 后端:一份只接受 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,否则运行期 502no resolver defined)。顺带把proxy_connect_timeout调小,让故障节点少拖累用户。
7. 常见坑
ip_hash上了 CDN/NAT 就塌缩 。现象:某台后端 CPU 打满,其余闲置。根因:ip_hash只取客户端 IP,NAT 后整段用户共用一个出口 IP。正解:改用sticky cookie(≥1.29.6)或hash $cookie_uid。max_fails=0当成「关掉健康检查更稳」 。现象:一台后端挂了两小时仍在接流量,凡轮到它的请求都多等一个proxy_connect_timeout(实测 1s 以上)。根因:0 表示不计数,节点永不被摘,只剩proxy_next_upstream兜底。正解:保留max_fails=3,fail_timeout调成 5~10s。backup配在hash/ip_hash/random上 。现象:nginx -t直接报balancing method does not support parameter "backup"。根因:文档明确backup不能与这三种算法同用。正解:备份节点放独立 upstream,或用error_page兜底。- 只写
keepalive 32不写proxy_http_version 1.1(≤1.29.6) 。现象:配了池子但ss里全是一闪而过的短连接。根因:HTTP/1.0 语义下连接不可复用。正解:三件套keepalive+proxy_http_version 1.1+Connection ""。 - 用变量形式
proxy_pass却漏了resolver。现象:nginx -t通过,请求全 502。根因:变量形式强制走运行期解析。正解:配resolver(容器里是127.0.0.11),并接受每请求一次缓存查找的成本。 proxy_next_upstream不限次 。现象:三台全挂时单个请求要等 3×connect_timeout,客户端超时雪崩。根因:proxy_next_upstream_tries默认 0(不限)。正解:tries 2+timeout 3s。stream转发 HTTP 拿不到响应 。现象:nc连上但零字节,后端BrokenPipeError。根因:proxy_half_close默认 off,客户端半关即上游被关。正解:proxy_half_close on(≥1.21.4);长期方案是七层用http块。- 以为
proxy_socket_keepalive on就是上游长连接 。现象:开了却没减少握手。根因:它只打开 TCP 的SO_KEEPALIVE(探活),与连接池无关。正解:连接池靠keepalive。
8. 延伸阅读
| 文档页 | 解决什么问题 |
|---|---|
| ngx_http_upstream_module | hash/random/max_conns/sticky/keepalive 的权威默认值与各自的版本行 |
| ngx_http_proxy_module | proxy_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_module | proxy_protocol/proxy_half_close/proxy_timeout 的准确定义 |
| ngx_stream_core_module | listen ... udp 与 stream 块结构 |
| resolver | valid= 与 DNS TTL 的关系,动态解析的唯一入口 |
| nginx CHANGES | sticky/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 篇故障案例库