上个月的一个周四夜里,一台跑 nginx 1.24 的机器开始间歇报 502。nginx 502 排查要落在 error.log 里 upstream 那一行,不在后端的进程状态上。整站没有挂,每隔十几分钟冒一批,刷新一次又好了,两个人一起点同一个下单按钮,一个看到白页,另一个拿到正常页面。前面两个小时走的是反方向,按后端进程挂掉处理,重启过一次,没有修好任何东西。最后确认的两处,是一条被复用的死连接,和一段比后端长出去很多的 keepalive 空闲时间。

nginx 502 是 nginx 自己写出来的状态码
502 不是后端返回的,是 nginx 在拿到完整响应头之前就把这条请求判死了。502 Bad Gateway 指的是 nginx 作为反向代理,没能从上游取到一个合法的响应头,于是自己造一个状态码回给客户端。上游自己吐的 5xx 会原样透传,除非开了 proxy_intercept_errors,两种来源在浏览器里几乎看不出差别,形态都是白页加一行状态码。error.log 里这几类的文本各不相同,连接没建起来是一行,被对端提前关掉是另一行,响应头不成形和可用上游为空又各自一行。access.log 只记结果码,原因是那一行,而且这个码会被中间的设备一路往上传,传到用户那边看到的还是 502。

keepalive 把两侧的空闲时间摆在一起比
连接复用是 nginx 与上游之间的第二层状态,静态站里那条 404 没有这一层,代理站有。keepalive 让 nginx 把用过的连接留在池子里,下一个请求直接写进去,省掉三次握手。连接留多久由两侧各自决定,nginx 上游块里的 keepalive_timeout 管池子这一侧,后端进程自己的空闲超时管另一侧。两个值一旦错开,池里就会出现一条对端已经关掉、nginx 还以为活着的连接。这条连接不会自己消失,要等下一个请求写进去才暴露,暴露的方式是一次 RST。池子按 worker 分开,四个 worker 就有四份,同样的窗口在每一条空闲连接上重来一次。
bash
$ awk '$9==502' /var/log/nginx/access.log | wc -l
231
$ wc -l < /var/log/nginx/access.log
58214
combined 格式里第九列就是状态码,$9 取到的 231 条散在五万八千多条请求里,占 0.4%。这个比例和「后端挂了」对不上,进程真挂掉的时候 502 是几十个百分点,曲线是一道竖起来的墙。0.4% 的形状说明它只打中某一类请求,也就是那些刚好复用到旧连接上的请求。这个量级先给出了方向,后端可以先放着,把状态码摊开看更有用。
最初的判断是后端进程出了问题,理由是 502 集中在下单接口上,而那个接口的流量本来就不均匀。我把后端日志按时间对齐看了一遍,那段时间只有正常的访问记录,没有异常栈,CPU 和内存都是平的。动作是在 21 点 40 分把后端重启了一次,重启后的两分钟里 502 反而更密,之后回到原来的稀疏状态。密的那两分钟好解释,进程刚起来、池里没有连接可复用,所有请求都在建连。回到稀疏说明旧连接的窗口又攒起来了,这个动作排掉的是进程状态,不是根因。再去看 error.log,那一行给的信息比状态码多。
bash
$ grep 'upstream' /var/log/nginx/error.log | tail -n 3
2026/11/12 21:14:07 [error] 1843#1843: *90213 upstream timed out (110: Connection timed out) while reading response header from upstream, request: "GET /api/orders HTTP/1.1", upstream: "http://10.0.1.12:8080/api/orders"
2026/11/12 21:14:08 [error] 1843#1843: *90214 upstream prematurely closed connection while reading response header from upstream, request: "POST /api/cart HTTP/1.1", upstream: "http://10.0.1.12:8080/api/cart"
2026/11/12 21:27:31 [error] 1843#1843: *91770 upstream prematurely closed connection while reading response header from upstream, request: "POST /api/cart HTTP/1.1", upstream: "http://10.0.1.12:8080/api/cart"
两行文本对应两种原因,落到状态码上是分开的。110 那一行是等响应头等过了 proxy_read_timeout,它给客户端的是 504,不是 502。prematurely closed 那一行是连接已经被对面关掉,请求写进了一条 nginx 以为还活着的连接,客户端拿到 502。当晚 502 的请求绝大多数对的是第二行,第一行在 504 里占大头,两者混在同一分钟出现,只看状态码很容易归成一类。上游段那三个时间值写在 /etc/nginx/conf.d/app.conf 里,用 nginx -T 把合并后的全文打出来,才能确认有没有被人改过。
nginx
upstream app_backend {
server 10.0.1.12:8080;
keepalive 32;
keepalive_timeout 60s;
}
location /api/ {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_read_timeout 60s;
}
```
keepalive 32 是每个 worker 缓存的空闲连接数,keepalive_timeout 60s 是这些连接最多留 60 秒,默认值也是 60 秒,没写和写了效果一样。后端是 gunicorn,keep-alive 的默认值是 2 秒,中间那台四层负载均衡的空闲超时是 15 秒。一条连接在后端的视角里 2 秒就过期,在 nginx 的视角里还能再用 58 秒,这 58 秒就是池里的死连接窗口。keepalive 要生效还有两个前提,缺一个池子就存不住连接:proxy_http_version 必须写成 1.1,Connection 头必须清空,默认的 1.0 会让 nginx 每次带上 Connection: close。
## 三种规模,先查的那一项不一样
三档里先查的那一项不同,单机档看两侧的空闲时间差,隔一层设备的那档看设备自己的超时。慢接口那一档看的是等待上限,和连接复用没有关系。分界不按 QPS 走,按上游是谁、空闲时间由谁定。档位搞错,查一整晚也碰不到那个值,三档之间没有一条判据能跨档成立。三档的分界还落在配置能不能拿到上,拿不到就只能从日志倒推,倒推时手里只有两张表,access.log 和 error.log。

### 单机同机,先看两侧的空闲时间差
适用面较宽的一档是后端和 nginx 挤在同一台机器上,后端是 gunicorn 或 uvicorn 这类带 worker 的进程。这一档的判据只有一个差值,nginx 上游块的 keepalive_timeout 减去后端进程的 keep-alive,差值必须为负,短到后端还没关、nginx 就已经把这条连接换掉。差值是正的几十秒就会出 502,出在空闲超过后端超时、又没超过 nginx 超时的那一段请求上。把 60 秒压到 1 秒,这一档的 502 基本消失,代价是复用率降下来一点,连接重建的开销在单机上看得出来,但不大。这一档也容易自己造出来,默认值一个 60 秒一个 2 秒,谁都不动就是错的。
### 中间有一层负载均衡,先查它自己的空闲时间
nginx 和后端之间还隔着一台四层设备时,决定窗口的是那台设备的空闲超时,常见值是 15 秒或者 60 秒,也有设备留到 900 秒。这一档的现象和上一档不同,502 扎堆出现在隔了十几秒没有请求之后的第一个请求上,连续的请求反而不报错。判据落在访问日志的间隔上,把 time_local 排序后算前后两条的差,再看差超过 15 秒的那些请求里 502 的占比。当时看不到负载均衡那一侧的空闲配置,只能从间隔上倒推,这一点让排查多花了一个小时。倒推的办法是把每条 502 和它前一条请求的时间差列出来,差值集中在同一个数上,那个数就是对面设备的空闲超时。
### 慢接口,先看超时上限与它自己的耗时
导出和报表这类一次跑几秒的接口,瓶颈不在复用上,在等待上。判据是后端该接口的 P99 与 proxy_read_timeout 的关系,P99 压在超时线上时,报出来的是 timeout 那一行,客户端拿到 504。这一档要按接口分开设超时,全站一个 60 秒的值,慢接口会把别的请求一起拖在队列里。要看是哪一条接口吃掉了时间,得看 upstream_response_time,这个变量默认不进 combined 格式,要自己在 log_format 里加进去。加进去之后再跑一遍,慢接口的名字会自己浮出来,不用一条条猜。
## 几个被当成结论的动作
重启后端和调大超时这两个动作,都没有把池里的窗口改小。重启清空的是进程这一侧,nginx 池里那批连接跟着断一次,之后按同样的 60 秒重新攒起来,窗口一点没变。调大 proxy_read_timeout 改的是等待上限,和复用没有关系,只会把超时那一条从 504 变成更长的等待。把超时从 60 秒改成 5 秒这个动作当时也做过,结果是 timeout 那一行变多,nginx 502 的量没有动,两个数字分开走,正好说明它们由不同的原因产生。
另一个被当成结论的判断是「开了 keepalive 就一定更快」,配置不全的时候这条会反着来。只写 keepalive 32 而不写 proxy_http_version 1.1 和 Connection 清空,池子存不住连接,等于没开。三个都写上但 keepalive_timeout 留默认值,窗口比后端长,502 就从偶发变成稳定。只看 access.log 里 502 的计数也容易走偏,那个数字只说明结果,说明不了是哪一类原因,两行文本对的是两套完全不同的处理。三个值对不齐的时候,慢和 502 会一起冒出来,只看现象分不开是哪一段造成的。
## 这次排掉的是什么,所以先查什么
这次先排掉的是进程状态,重启前后 502 的比例没有变化,后端日志里也没有异常栈。再排掉的是等待时间,timeout 那一行对应的是 504,和 502 不在一条线上。剩下的只有复用,池里的连接比后端多活 58 秒,那 58 秒里写进去的请求都撞在一条死连接上。处理动作是把上游块的 keepalive_timeout 压到 1 秒,比 gunicorn 的 2 秒短一格,502 从每小时几十条降到零。再遇到 nginx 502,先 grep 一次 upstream 那一行,看它是 timeout 还是 prematurely closed,两个词指向两条不同的路。