这是《Nginx 从入门到精通》系列的第 5 篇(全系列 15 篇 + 4 个实战项目)。目标:把「1 个 Nginx + 3 个后端」的反代链路跑通------能画出带 URI 的
proxy_pass的路径映射表,能用TIME_WAIT计数证明 upstream 长连接真的生效,能说清本拓扑里 502 与 504 各自的具体触发方式。前置 :第 3 篇(http/server/location 上下文与指令书写规则)、第 4 篇(location 前缀与正则的匹配顺序);实验复用
lab/00-env(按需)。 本文所有数字与输出均为 nginx 1.30.6(stable)实测,文末附自测 5 题与延伸阅读。
1. 先跑起来(5 分钟实验)
实验环境就是 lab/00-env:网关宿主端口 8080 、上游组 app_pool 、成员 app1:8080 / app2:8080 / app3:8080。本篇不改实验室文件,所有改动都在副本里做对照。
bash
cd nginx/lab/00-env
docker compose up -d
docker compose ps # 5 个容器 running;app* 稍后转 healthy
# ① 轮询:同一个 /api/json 连续 6 次,看 app= 字段变化
for i in $(seq 6); do curl -s localhost:8080/api/json | grep -o '"app": "[^"]*"'; done
# "app": "app1" "app": "app2" "app": "app3" "app": "app1" "app": "app2" "app": "app3"
# ② 带 URI 的 proxy_pass:location /api/ + proxy_pass http://app_pool/ → /api/json 变成 /json
curl -s localhost:8080/api/json | grep '"path"'
# "path": "/json",
# ③ 不带 URI 的 proxy_pass:/slow/1 原样透传,后端自己 sleep 2 秒
curl -s -o /dev/null -w 'code=%{http_code} rt=%{time_total}\n' localhost:8080/slow/1
# code=200 rt=2.0xx
# ④ 停一个后端:等解析周期过去(resolver valid=5s)再看轮询
docker compose stop app2 && sleep 6
for i in $(seq 6); do curl -s localhost:8080/api/json | grep -o '"app": "[^"]*"'; done
# 只剩 app1 / app3
docker exec lab-gateway tail -5 /var/log/nginx/lab_error.log
# 可见 app2 对应的 upstream 条目被摘除(temporarily disabled,或被 resolve 直接从组里移除)
docker compose start app2
四步分别对应本篇的四条主线:上游组 → 路径改写 → 超时 → 被动摘除。改完配置永远走这三步:
bash
docker compose exec -T gateway nginx -t -c /etc/nginx/lab/nginx.conf # 必须带 -c
docker compose exec -T gateway nginx -s reload
curl -s localhost:8080/healthz # gateway ok
-t不带-c校验的是镜像自带的/etc/nginx/nginx.conf,等于没校验。这是整套教程里最容易白干的一件事(第 2 篇已经用nginx -t的两种报错演示过)。
2. 核心概念
2.1 一条请求在反代链路里经过谁
| 环节 | 本实验实体 | 看到的东西 | 对应指令 |
|---|---|---|---|
| 客户端 | curl localhost:8080 |
目标地址是网关,不是后端 | --- |
| 网关(反向代理) | gateway 容器,listen 80,宿主映射 8080 |
客户端 IP、原始 URI、原始请求头 | proxy_pass、proxy_set_header |
| 上游组 | upstream app_pool |
选哪台、算几次失败 | server、算法指令 |
| 上游进程 | app1/app2/app3 的 app.py |
只有网关给的 Host 与 X-Forwarded-* |
后端代码读头 |
「反向」的含义是代理替服务端接收请求 :客户端不知道后端存在,后端也不该直接对外。所以第一件事是让后端认得真实来源(X-Forwarded-For),第二件事是让网关能在多台后端之间挑一台(upstream + 算法),第三件事是任意一台坏了不能让用户看到报错(max_fails + proxy_next_upstream)。
2.2 upstream 与负载算法
upstream 块必须在 http 上下文里声明,proxy_pass 才能用名字引用它。三种入门算法对照:
| 算法 | 写法 | 选谁 | 什么时候必须改 | 改错的后果 |
|---|---|---|---|---|
| 轮询(默认) | 不写 | 按 weight 依次轮转 |
后端算力一致时不要改 | 无 |
| 最少连接 | least_conn; |
当前活动连接数最少的那台 | 请求耗时差异大(慢查询、长连接多) | 慢后端堆积、快后端闲着 |
| IP 哈希 | ip_hash; |
按客户端 IPv4 前三段哈希 | 会话存在进程内存、不能集中存储 | NAT 出口后整栋楼落到同一台 |
server 行参数决定「一台后端怎么被看待」:weight=5 加权、max_fails=3 fail_timeout=10s 被动摘除、backup 兜底、down 手动摘流。默认值分别是 weight=1、max_fails=1、fail_timeout=10s------注意默认只失败 1 次就摘,实验环境显式写成 3 是为了让摘除过程可观察。
2.3 proxy_pass 的两种形态
判定规则只有一句:proxy_pass 的地址里带不带路径部分。
| location | proxy_pass 写法 | 客户端请求 | 上游收到的 path |
|---|---|---|---|
location /api/ |
http://app_pool/(带 URI) |
GET /api/json |
/json |
location /api/ |
http://app_pool(不带 URI) |
GET /api/json |
/api/json |
location /slow/ |
http://app_pool(不带 URI) |
GET /slow/1 |
/slow/1 |
location /api/ |
http://app_pool/v2/(带 URI) |
GET /api/json |
/v2/json |
「带 URI」的语义是:把 location 匹配到的那段前缀替换成 proxy_pass 里的 URI ,剩余部分拼在后面。所以末尾那个 / 不是装饰,是「替换成空路径」的明确写法。不带 URI 时 Nginx 原样透传原始请求行(连 query string 一起),这也是唯一能保住后端路由前缀的写法。
正则 location(
location ~)里不能带 URI 写proxy_pass,否则nginx -t直接报错。另一半是 rewrite 改完 URI 之后前缀替换会失效,两条一起构成第 6 篇的实验入口。
2.4 必须转发的请求头与「受信代理」
后端看到的是网关的 连接,$remote_addr 默认是网关自己在容器网络里的 IP。要让后端知道真实客户端,就得靠头:
| 头 | 推荐值 | 为什么必须有 | 不改会怎样 |
|---|---|---|---|
Host |
$host |
后端按域名分站点、拼绝对 URL | 后端收到 app_pool($proxy_host 默认值),虚拟主机全错 |
X-Real-IP |
$remote_addr |
单值,最省事的真实 IP | 后端日志全是网关 IP |
X-Forwarded-For |
$proxy_add_x_forwarded_for |
追加式,多级代理可追溯 | 无法还原链路;手写 $remote_addr 会覆盖上游信息 |
X-Forwarded-Proto |
$scheme |
后端要判断是否 HTTPS 才能决定跳转与 Cookie Secure |
后端生成 http:// 链接,跳转死循环 |
Connection |
""(空串) |
见 2.7,upstream 长连接必需 | 每个请求新建 TCP 连接 |
proxy_set_header 的默认行为要记住:默认只重定义 Host 为 $proxy_host、Connection 为 close ;而且当前层级一旦写了任何一条 proxy_set_header,上一层的同名指令全部失效(不再继承)。这就是「server 里写了四条、location 里又写一条,结果只剩一条生效」的经典翻车点。
另一边是采信 :X-Forwarded-For 是客户端可以随便填的头。只有来自可信来源时才该相信它,用 realip 模块白名单化:
nginx
# 只有网关前面还有一层可信 LB 时才写;本实验没有,写了就是自欺
set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;
real_ip_header 默认是 X-Real-IP,set_real_ip_from 默认无(不信任任何人)。不加白名单就直接 real_ip_header X-Forwarded-For,等于允许任何客户端伪造 IP 绕过 allow/deny 与限流,是能上安全事故的配置。
2.5 超时三件套与 502 / 504 的成因链
| 超时指令 | 默认值 | 管哪一段 | 卡住时的现象 |
|---|---|---|---|
proxy_connect_timeout |
60s | 与上游建 TCP 连接 | 上游端口没监听 → 连接被拒(立刻 502),不是超时 |
proxy_send_timeout |
60s | 把请求发给上游 | 两次写之间静默超时 → 504 |
proxy_read_timeout |
60s | 等上游响应(两次读之间) | 上游 hang 住 → 60s 后 504 |
502 与 504 不是一回事,成因链要能背出来:
| 状态码 | 成因(本拓扑里的具体触发) | 关键证据 |
|---|---|---|
| 502 | 后端全停 → 连不上;后端进程被 kill → 连接被重置;上游响应头不合法 → invalid_header |
lab_error.log 里 connect() failed (111: Connection refused) 或 no live upstreams |
| 504 | 后端活着但 proxy_read_timeout 内不吐数据;/slow/ 上游 sleep 超过读超时 |
日志 urt= 接近超时值,up= 有地址 |
| 499 | 客户端先断(通常是客户端自己超时),网关侧记 499,不算上游错 | status 499、urt=- |
实验环境把 proxy_connect_timeout 压到 2s ,是为了让「后端挂了」这件事 0.7 秒内变成 502 而不是干等 60 秒。proxy_next_upstream 默认是 error timeout:建连失败、超时、读不到响应头,都会换下一台再试。
关键约束:默认不重试非幂等请求 。GET/HEAD/PUT/DELETE/OPTIONS/TRACE 之外的 POST 等,只有显式加上 non_idempotent 参数才会被转给下一台------打开它之前先想清楚重复下单、重复扣款的风险。另外用 proxy_next_upstream_tries 限制重试次数(默认 0 表示不限),避免 3 台全挂时被放大成 9 次尝试。
2.6 buffering:网关要不要先替上游存住响应
proxy_buffering 默认 on :网关先从上游把响应读进内存缓冲(proxy_buffers 默认 8 4k|8k,可占用的大小由 proxy_busy_buffers_size 限制,默认 8k|16k),再慢慢发给慢客户端。好处是上游连接能尽早释放;代价是流式响应会被攒住。
| 场景 | buffering | 原因 |
|---|---|---|
| 普通 HTML/JSON 响应 | on(默认) |
响应小,缓冲完立刻释放上游连接 |
| SSE / 长轮询 / 流式下载 | off | 攒缓冲等于把实时性扔掉 |
| 上游自己说了算 | 上游回 X-Accel-Buffering: no |
不改网关配置就能逐条关闭(proxy_ignore_headers 可禁用该能力) |
请求方向还有一个开关:proxy_request_buffering 默认 on,即网关先把整个请求体收完再转给上游;大文件上传想边收边转就设 off,代价是「上游已收到一半才失败」时无法重试到另一台。
请求体相关的三个默认值是新手最常撞的墙:client_max_body_size 默认 1m (超了返回 413 ,请求根本不会到上游),client_body_buffer_size 默认 8k/16k(超过就落临时文件,不是限制),client_body_timeout 默认 60s (两次读之间静默超时返回 408)。
2.7 proxy_http_version × Connection 的组合矩阵
proxy_http_version 的默认值有版本变化:≥1.29.7 默认 1.1,之前默认 1.0。这个差别直接决定 upstream 长连接能不能用。
| 场景 | proxy_http_version |
Connection |
其它必须项 |
|---|---|---|---|
| 普通反代(一次性连接) | 默认即可 | 默认 close |
无需额外配置 |
| upstream 长连接池 | 1.1 |
""(空串) |
upstream 里加 keepalive 32 |
| WebSocket | 1.1 |
"upgrade" |
Upgrade $http_upgrade;放大 proxy_read_timeout |
| SSE / 流式 | 1.1 |
"" |
proxy_buffering off;proxy_cache off;放大读超时 |
规律:Connection 头是「这次连接怎么结束」的声明 。close 是短连接、空串是「别声明、交给长连接池」、upgrade 是协议升级。三者互斥,写混了就退化成短连接或握手失败。upstream 长连接要真正生效,keepalive N + proxy_http_version 1.1 + Connection "" 三个条件缺一不可 ,少一个都还是每次新建连接;N 限制的是空闲连接数,不是总数。
后端 app.py 把 protocol_version 设成 HTTP/1.1 就是为了让这条链路可验证;HTTP/1.0 后端拿到 Connection: keep-alive 也不会复用。
3. 指令详解
| 指令 | 默认值 | 上下文 | 说明与坑 |
|---|---|---|---|
proxy_pass |
--- | location / if / limit_except | 带 URI 时替换 location 前缀;不带 URI 原样透传;正则 location 里不能带 URI |
proxy_set_header |
Host $proxy_host、Connection close |
http / server / location | 当前层级写了任意一条,上层同名指令全部失效;转发 Host 用 $host |
proxy_http_version |
1.1(≥1.29.7);此前 1.0 |
http / server / location | 长连接/WS/SSE 必须显式写 1.1,别赌默认值 |
proxy_connect_timeout |
60s |
http / server / location | 只覆盖建连阶段;通常压到 1--3s,让故障快速变 502 |
proxy_read_timeout |
60s |
http / server / location | 两次读之间计时,不是总时长;WS/SSE 要放大到 3600s 级 |
proxy_send_timeout |
60s |
http / server / location | 两次写之间计时;大请求体配慢上游时才会撞到 |
proxy_next_upstream |
error timeout |
http / server / location | 非幂等请求默认不重试;non_idempotent 打开前评估重复执行代价 |
proxy_next_upstream_tries |
0(不限) |
http / server / location | 生产建议设 2--3,防止全挂时重试放大 |
proxy_buffering |
on |
http / server / location | 流式场景关掉;也可由上游 X-Accel-Buffering: no 逐条控制 |
proxy_request_buffering |
on |
http / server / location | 关掉后大文件直通上游,但失败重试到另一台变难 |
proxy_buffers |
`8 4k | 8k` | http / server / location |
client_max_body_size |
1m |
http / server / location | 上传必改;超限返回 413,请求不进上游 |
server(upstream 内) |
weight=1、max_fails=1、fail_timeout=10s |
upstream | resolve 需 zone + resolver 同时存在;开源版 ≥1.27.3 |
keepalive(upstream 内) |
--- | upstream | 是空闲 长连接数上限,不是超时;必须配 proxy_http_version 1.1 + Connection "" |
least_conn / ip_hash |
不写即轮询 | upstream | ip_hash 与 backup 不能同时用 |
4. 完整配置示例
nginx
# 宿主:lab/00-env/nginx/nginx.conf ;容器内:/etc/nginx/lab/nginx.conf
user nginx;
worker_processes 1; # 单 worker:轮询行为完全可预测
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;
# 本篇要看的四个字段:rt=总耗时 urt=上游耗时 up=上游地址 ust=上游状态
log_format main '$remote_addr - $remote_user "$request" '
'$status $body_bytes_sent rt=$request_time '
'urt=$upstream_response_time up=$upstream_addr '
'ust=$upstream_status rid=$request_id '
'xff="$http_x_forwarded_for"';
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;
resolver 127.0.0.11 valid=5s ipv6=off; # Docker 内置 DNS;配合 resolve 自愈
upstream app_pool {
zone app_pool 64k; # resolve 要求 upstream 在共享内存里
# least_conn; # 想验「最少连接」就取消注释
server app1:8080 resolve max_fails=3 fail_timeout=10s;
server app2:8080 resolve max_fails=3 fail_timeout=10s;
server app3:8080 resolve max_fails=3 fail_timeout=10s;
keepalive 32; # 空闲长连接上限(不是超时)
}
server {
listen 80;
server_name _;
root /usr/share/nginx/html;
index index.html;
client_max_body_size 20m; # 默认 1m:超过直接 413
client_body_timeout 30s; # 慢速上传:两次读之间静默超时 → 408
location = /healthz {
access_log off;
return 200 "gateway ok\n";
}
location /nginx_status {
stub_status;
allow 127.0.0.1;
deny all;
}
location /static/ {
alias /usr/share/nginx/html/;
expires 7d;
add_header Cache-Control "public";
}
# ① 不带 URI:原始路径透传(/slow/1 → 上游 /slow/1)
location /slow/ {
proxy_pass http://app_pool;
proxy_read_timeout 5s; # 上游 sleep 2s,故意留出余量
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
}
# ② 带 URI:location 前缀被替换(/api/json → 上游 /json)
location /api/ {
proxy_pass http://app_pool/;
proxy_connect_timeout 2s; # 后端挂了 0.7s 内 502,不干等 60s
proxy_read_timeout 10s;
proxy_send_timeout 10s;
proxy_http_version 1.1;
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;
proxy_set_header Connection "";
proxy_next_upstream error timeout http_502 http_503;
proxy_next_upstream_tries 2;
proxy_buffering on;
}
# ③ WebSocket:三个头一个都不能少
location /ws/ {
proxy_pass http://app_pool;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s; # 空闲就断的不叫长连接
proxy_send_timeout 3600s;
}
# ④ SSE / 流式:关缓冲、关缓存、放大读超时
location /events/ {
proxy_pass http://app_pool/;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 3600s;
}
location / {
try_files $uri $uri/ /index.html;
}
}
}
相对 lab/00-env 当前的 nginx.conf + conf.d/default.conf 只改了这 6 处,其余一行没动:
| # | 位置 | 改动 | 目的 |
|---|---|---|---|
| 1 | log_format main |
增加 ust=$upstream_status rid=$request_id |
区分「上游返回 502」与「网关自己判 502」 |
| 2 | upstream app_pool |
增加 keepalive 32(least_conn 注释掉) |
实验 4 的对照起点 |
| 3 | /slow/、/api/ |
补 proxy_http_version 1.1 + proxy_set_header Connection "" |
补齐长连接生效的三个条件 |
| 4 | /api/ |
增加 proxy_next_upstream / _tries 2 / send 与 read 超时 |
重试链可控、故障快速失败 |
| 5 | server 新增 |
client_max_body_size 20m、client_body_timeout 30s |
上传不再撞默认 1m |
| 6 | server 新增 |
location /ws/、location /events/ |
WebSocket 与 SSE 两条流式链路 |
改完照旧三步:nginx -t -c /etc/nginx/lab/nginx.conf → nginx -s reload → curl localhost:8080/healthz。
5. 必做实验
实验 1:三种算法的可观察差异
bash
cd nginx/lab/00-env
# 默认轮询
for i in $(seq 6); do curl -s localhost:8080/api/json | grep -o '"app": "[^"]*"'; done
# 改成 least_conn:取消 upstream 里的注释,然后校验 + 热加载
docker compose exec -T gateway nginx -t -c /etc/nginx/lab/nginx.conf && docker compose exec -T gateway nginx -s reload
for i in $(seq 6); do curl -s localhost:8080/api/json | grep -o '"app": "[^"]*"'; done
# 再改成 ip_hash(同样先 -t 再 -s reload)后看
for i in $(seq 6); do curl -s localhost:8080/api/json | grep -o '"app": "[^"]*"'; done
预期(实测):
| 算法 | 预期 | 为什么 |
|---|---|---|
| 轮询 | app1 app2 app3 app1 app2 app3 |
单 worker 下计数器确定,权重相等就严格轮转 |
| least_conn | 前几次可能落在同一台,随后偏向空闲的 | curl 是串行短请求,各台活动连接都接近 0,平票退回加权轮询 |
| ip_hash | 6 次全部同一台 | 同一个客户端 IP 前三段相同,哈希值恒定 |
为什么是这个结果 :轮询的计数器在每个 worker 内独立(ngx_http_upstream_rr_peers_t 里的 current),所以 worker_processes 1 时分布完全可预测;least_conn 的平票回退是模块实现细节,不是随机的。
若把
worker_processes改成auto,轮询就不再严格轮转:每个 worker 各有一份计数,分布要到几十次请求后才均匀,这是第 12 篇的内容。
实验 2:max_fails 被动摘除与恢复
bash
docker compose stop app2 && sleep 6
for i in $(seq 6); do curl -s localhost:8080/api/json | grep -o '"app": "[^"]*"'; done
docker exec lab-gateway tail -5 /var/log/nginx/lab_error.log
# ... upstream: "http://172.x.x.x:8080/", ... temporarily disabled(或被 resolve 直接摘掉)
docker compose start app2 && sleep 6
for i in $(seq 6); do curl -s localhost:8080/api/json | grep -o '"app": "[^"]*"'; done
预期:停掉后 6 次请求全部成功且不含 app2;起回后 app2 重新出现。
为什么是这个结果 :两层机制同时在起作用。连接层 max_fails=3 fail_timeout=10s 在累计 3 次失败后把它标记不可用 10 秒;解析层 resolve + resolver valid=5s 让 Docker DNS 的变化在 5 秒内落地,所以不需要 reload。这里 sleep 6 就是等过了 valid=5s 的解析周期。
想做「不自动恢复」的对照(去掉 zone/resolve/resolver,只能靠 reload 重解析)属第 7 篇。
实验 3:WebSocket 升级头是否真的送到上游
后端 app.py 的 /json 会回显全部请求头,正好当探针:
bash
# 先走 /api/(默认 Connection close)
curl -s -H 'Upgrade: websocket' -H 'Connection: Upgrade' localhost:8080/api/json | grep -i '"Connection"'
# "Connection": "close" ← 网关把它改写成 close
# 再走本篇的 /ws/(Connection "upgrade")
curl -s -H 'Upgrade: websocket' -H 'Connection: Upgrade' localhost:8080/ws/json | grep -iE '"(Connection|Upgrade)"'
# "Upgrade": "websocket"
# "Connection": "upgrade" ← 两个头都到了上游
| 现象 | 含义 |
|---|---|
上游看到 Connection: close |
没配 upgrade,握手必失败(后端当普通请求处理) |
只有 Upgrade 到了、Connection 还是 close |
漏了 proxy_set_header Connection "upgrade",最典型的 WS 失败原因 |
| 两个头都到,但连接 60s 就断 | proxy_read_timeout 还是默认 60s |
为什么是这个结果 :proxy_set_header 的默认值里有 Connection close,所以 /api/ 里即使客户端发了 Connection: Upgrade,网关也会把它重写成 close 再转发------这是「默认值代你做了决定」的典型例子。真握手可用任意 WS 客户端(如 npx wscat -c ws://localhost:8080/ws/);本实验后端只回显头,看到上表第二行即算通过。
实验 4:upstream 长连接是否真的生效
bash
# 关闭长连接:注释掉 upstream 的 keepalive,以及两条 proxy_set_header Connection ""
docker compose exec -T gateway nginx -t -c /etc/nginx/lab/nginx.conf && docker compose exec -T gateway nginx -s reload
for i in $(seq 200); do curl -s -o /dev/null localhost:8080/api/json; done
docker exec lab-gateway netstat -tan | grep -c TIME_WAIT
# busybox 没有 netstat 时:docker exec lab-gateway cat /proc/net/tcp | grep -c ' 06 '
# 打开长连接后重复同样的 200 次
for i in $(seq 200); do curl -s -o /dev/null localhost:8080/api/json; done
docker exec lab-gateway netstat -tan | grep -c TIME_WAIT
预期:关闭时 TIME_WAIT 累积到几十上百且随请求递增,打开后基本稳定在个位数。
为什么是这个结果 :/proc/net/tcp 里状态 06 就是 TIME_WAIT(01 是 ESTABLISHED)。短连接每次都由网关主动关闭,关方留下 TIME_WAIT 两倍 MSL;长连接把 200 次请求压到 32 条以内的连接上,几乎不新增。日志侧可交叉验证上游地址的复用情况:
bash
docker exec lab-gateway tail -200 /var/log/nginx/lab_access.log \
| awk '{for(i=1;i<=NF;i++) if($i ~ /^up=/) {split($i,a,"="); print a[2]}}' | sort | uniq -c
6. 验收自测(5 题)
Q1. location /api/ { proxy_pass http://app_pool; } 收到 GET /api/users/42?x=1,上游收到什么?把 proxy_pass 改成 http://app_pool/ 呢?
答案要点 :不带 URI(http://app_pool)原样透传,上游收到 GET /api/users/42?x=1;带 URI(http://app_pool/)时 location 前缀 /api/ 被替换为空,上游收到 GET /users/42?x=1,query string 保留。判定只看 proxy_pass 地址里有没有路径部分。
Q2. upstream 已经写了 keepalive 32,为什么连接状态里的 TIME_WAIT 还在涨?
答案要点 :长连接要三个条件同时满足:keepalive 32、proxy_http_version 1.1、proxy_set_header Connection ""。少任何一个,Nginx 仍按短连接语义每次发 Connection: close(HTTP/1.0 下更彻底),连接池形同虚设。另外后端必须具备 HTTP/1.1 持久连接能力(本实验 app.py 设了 protocol_version = "HTTP/1.1")。
Q3. 上游进程被 kill -9,用户拿到 502 还是 504?上游活着但卡住不回数据呢?
答案要点 :被 kill 立刻是 502 :连接被 RST,属于 proxy_next_upstream 的 error,日志里是 upstream prematurely closed connection 或 connect() failed。上游 hang 住不回数据是 504 :等满 proxy_read_timeout(默认 60s,本实验 /api/ 设 10s)才放弃,日志 urt= 接近超时值。客户端自己先走则记 499。
Q4. 给 /api/ 加一行 proxy_set_header Content-Type application/json; 有什么风险?
答案要点 :两层风险。一是继承被清空 :location 里出现任何 proxy_set_header 后,server/http 层的同名指令都不再继承,上层写过的 Host、X-Forwarded-For 会一起丢。二是无条件覆盖 :所有请求(含 GET、含 multipart/form-data 上传)的 Content-Type 都变成 JSON,后端解析全错。正确做法是只改该改的头,动态值用 map 生成。
Q5. 上传 5MB 文件得到 413;上传 1MB 但在传给后端时卡满 60 秒后 408,分别查哪个指令?
答案要点 :413 查 client_max_body_size(默认 1m,本实验设 20m),它按请求体大小直接拒绝,请求不进上游。408 查 client_body_timeout(默认 60s),它计的是两次读之间的静默时间,慢速上传或客户端卡住会撞到;与 proxy_send_timeout(网关→上游方向)不是一回事。
7. 常见坑
-
后端全部 404,路径像是少了一段 。现象:
/api/users打到后端成了/users。根因:proxy_pass带 URI 后以为路径不变,实际 location 前缀被替换掉了。正解:记住替换规则------/api/+http://app_pool/→ 上游收到/json;要保住前缀就去掉结尾那个/。 -
后端日志里
Host是app_pool。现象:后端按域名分站点全部错乱、绝对 URL 拼错。根因:proxy_set_header默认Host $proxy_host,$proxy_host就是 upstream 组名。正解:显式写proxy_set_header Host $host;。 -
加了
keepalive但连接数不降 。现象:keepalive 32写了,TIME_WAIT照样涨。根因:缺proxy_http_version 1.1或proxy_set_header Connection ""。正解:三条一起写,用实验 4 的连接计数验证,别凭感觉。 -
后端重启后网关一直 502,
reload才恢复 。现象:容器 IP 变了,但流量还打向旧地址。根因:upstream 域名默认只在启动/reload时解析一次。正解:resolver+zone+server ... resolve(开源 ≥1.27.3);旧版本只能靠 reload 或模板重生成。 -
SSE/流式接口前端几十秒才收到一堆数据 。现象:数据都出来了却不逐条到达。根因:
proxy_buffering on是默认值,响应被攒住了。正解:proxy_buffering off,或让上游回X-Accel-Buffering: no;同时放大proxy_read_timeout。 -
WebSocket 握手 400 或一直 pending 。现象:浏览器控制台卡在
101之前。根因:只转了Upgrade没转Connection,或读超时还是 60s。正解:两个头都写,proxy_read_timeout 3600s;用实验 3 的回显探针确认两个头都到了上游。 -
日志里
up=是逗号分隔的多个地址 。现象:一行日志里up=172.x:8080, 172.y:8080。根因:触发了proxy_next_upstream重试,up/urt/ust都是多值且按位置对齐。正解:用$upstream_status与$upstream_response_time按位置读(第 9 篇给了解析命令)。 -
本地
curl全部落到同一台,怀疑负载没生效 。现象:连打 10 次都是一个app。根因:用了ip_hash,或worker_processes auto下各 worker 计数独立、短请求内看不出均衡。正解:先看 upstream 到底用的哪个算法,再看 worker 数;两者都排除后才查网络。
8. 延伸阅读
| 文档页 | 解决什么问题 |
|---|---|
| ngx_http_proxy_module | 反代指令全集:proxy_pass 的 URI 规则、超时、buffering、X-Accel-Buffering |
| ngx_http_upstream_module | 负载算法、server 参数(max_fails/fail_timeout/backup)、zone/resolve/keepalive |
| WebSocket proxying | 官方 WS 代理示例:Upgrade 与 Connection 两个头为什么必须成对 |
| ngx_http_realip_module | set_real_ip_from / real_ip_header / real_ip_recursive 的白名单语义 |
| ngx_http_core_module | client_max_body_size、client_body_timeout、client_body_buffer_size 的官方定义 |
| nginx CHANGES | 版本行为变化的唯一权威出处(如 proxy_http_version 默认值、resolve 开源化) |
章节依赖 :本篇依赖第 3 篇的上下文规则与第 4 篇的 location 匹配顺序(proxy_pass 写在哪个 location 里,决定路径怎么改);第 6 篇把本篇散落的 Connection/Host 头改造成 map 查表的可维护写法;第 7 篇承接本篇的 upstream 算法与被动摘除,补主动健康检查与熔断;第 8 篇的缓存命中、第 9 篇的 up=/urt= 多值日志解析,都以本篇定义的字段为起点。
系列导航:第 1 篇进程模型 → 第 2 篇安装升级 → 第 3 篇配置语法 → 第 4 篇静态站与 location → 第 5 篇(本篇)反向代理 → 第 6 篇 rewrite 与 server_name → 第 7 篇负载均衡进阶 → 第 8 篇缓存 → 第 9 篇日志排障 → 第 10 篇 HTTPS 与安全 → 第 11 篇 Lua 与 OpenResty → 第 12 篇性能调优 → 第 13 篇高可用架构与网关 → 第 14 篇可观测性与工程化 → 第 15 篇故障案例库