Nginx 反向代理入门:proxy_pass 两种形态、超时链与 502/504 分辨

这是《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. 常见坑

  1. 后端全部 404,路径像是少了一段 。现象:/api/users 打到后端成了 /users。根因:proxy_pass 带 URI 后以为路径不变,实际 location 前缀被替换掉了。正解:记住替换规则------/api/ + http://app_pool/ → 上游收到 /json;要保住前缀就去掉结尾那个 /。

  2. 后端日志里 Host 是 app_pool 。现象:后端按域名分站点全部错乱、绝对 URL 拼错。根因:proxy_set_header 默认 Host $proxy_host,$proxy_host 就是 upstream 组名。正解:显式写 proxy_set_header Host $host;。

  3. 加了 keepalive 但连接数不降 。现象:keepalive 32 写了,TIME_WAIT 照样涨。根因:缺 proxy_http_version 1.1 或 proxy_set_header Connection ""。正解:三条一起写,用实验 4 的连接计数验证,别凭感觉。

  4. 后端重启后网关一直 502,reload 才恢复 。现象:容器 IP 变了,但流量还打向旧地址。根因:upstream 域名默认只在启动/reload 时解析一次。正解:resolver + zone + server ... resolve(开源 ≥1.27.3);旧版本只能靠 reload 或模板重生成。

  5. SSE/流式接口前端几十秒才收到一堆数据 。现象:数据都出来了却不逐条到达。根因:proxy_buffering on 是默认值,响应被攒住了。正解:proxy_buffering off,或让上游回 X-Accel-Buffering: no;同时放大 proxy_read_timeout。

  6. WebSocket 握手 400 或一直 pending 。现象:浏览器控制台卡在 101 之前。根因:只转了 Upgrade 没转 Connection,或读超时还是 60s。正解:两个头都写,proxy_read_timeout 3600s;用实验 3 的回显探针确认两个头都到了上游。

  7. 日志里 up= 是逗号分隔的多个地址 。现象:一行日志里 up=172.x:8080, 172.y:8080。根因:触发了 proxy_next_upstream 重试,up/urt/ust 都是多值且按位置对齐。正解:用 $upstream_status 与 $upstream_response_time 按位置读(第 9 篇给了解析命令)。

  8. 本地 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 篇故障案例库

相关推荐
十有八七30 分钟前
手搓 Agent(四):长点记性——上下文满了怎么办,怎么记住上一次
前端·人工智能·后端
王晋15744 分钟前
第一次使用银河麒麟:从 Windows 迁移到国产 Linux 桌面的入门指南
后端
tonydf1 小时前
没完了,Nginx又报新漏洞!
运维·nginx
用户46043852250862 小时前
关于 Paimon-Rust 的写操作(细节)
后端
掘金酱2 小时前
AI 带来的新生意|稀土掘金 X-Lab 年度大会招募开启
前端·后端·vibecoding
nice_lcj5203 小时前
【从零理解计算机网络 · 02】分层模型:别背 OSI 七层,看数据怎么被“打包“和“拆包“
java·后端·tcp/ip·计算机网络·面试·osi·分层模型
SimonKing4 小时前
给Deepseek Harness装上插件市场,从此插件无忧
java·后端·程序员
利威尔xu4 小时前
Go Mutex 饥饿模式:正常模式等待者饿死,1ms 阈值自动切换崩溃
开发语言·后端·面试·golang·并发编程
一条Go4 小时前
边缘 Agent:为什么是它连出来,而不是平台连进去
后端·架构·github