用 Nginx 做反向代理时,502 Bad Gateway 几乎是运维绕不开的一课。它的字面意思是"网关收到了上游(upstream)的无效响应",翻译成大白话就是:Nginx 把请求转给后端,但没能从后端拿到一个像样的答复。后端是 Tomcat、Spring Boot、PHP-FPM、Node 还是 Python 服务,都可能出现这种情况,而根因既可能在 Nginx 配置里,也可能在后端本身,甚至可能在更外面的负载均衡或 CDN 上。
这篇文章专门围绕"upstream"这条链路展开:先讲 Nginx 和上游之间一次请求到底经历了哪几个阶段,再逐个拆解 upstream 块、proxy_* 超时、proxy_next_upstream 故障转移、长连接复用这些配置项,最后给出一套从日志到实操的排查流程。文中涉及的超时时间、连接数都是常见经验值,请结合业务实测调整。
读完之后,你应该能看懂 error.log 里那条 upstream 报错到底在说什么,知道该改哪个指令、改多大,也明白哪些改动有风险、怎么回滚。因为改代理配置直接影响线上可用性,文中所有配置修改都会强调 nginx -t 校验和保留旧配置。
一、先把 upstream 链路拆开
一次反向代理请求,Nginx 和上游之间大致经过四步,每一步失败的表现不同:
- 建立连接:Nginx 向上游 IP:Port 发起 TCP 连接。连不上 → 502(
connection refused/no route to host)。 - 发送请求:把请求行、头、体发给上游。中途断开 → 502(
upstream prematurely closed connection)。 - 等待响应:等上游返回响应头和数据。等太久 → 504(
upstream timed out);上游返回畸形响应 → 502(upstream sent invalid header)。 - 读取响应体:把响应体读回并转发给客户端。上游中途断开 → 502。
理解这四步,就能把"502 还是 504"这件事看透:502 基本等于"连接或响应层面出问题",504 是"时间超了"。所以排查 502,重点在"连接是否建立、上游进程是否活着、响应是否合法"。
一个基础的反向代理配置长这样:
upstream backend {
server 127.0.0.1:8080;
server 127.0.0.1:8081;
}
server {
listen 80;
server_name www.example.com;
location / {
proxy_pass http://backend;
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;
}
}
二、upstream 块的关键参数
upstream 块定义后端服务器列表和调度策略,几个参数直接影响可用性:
| 指令 | 作用 | 常用取值(经验值) |
|---|---|---|
server |
定义后端节点 | IP:PORT,可加 weight、max_fails、fail_timeout |
weight |
权重 | 默认 1,按机器性能配比 |
max_fails |
失败几次判定不可用 | 默认 1,建议 2~3 |
fail_timeout |
判定不可用的观察窗口/摘除时长 | 默认 10s,可设 10~30s |
keepalive |
与上游保持的闲置长连接数 | 视并发,如 32~128 |
least_conn / ip_hash |
调度策略 | 长连接业务用 ip_hash,通用用默认轮询 |
upstream backend {
least_conn; # 按最少连接数调度
server 127.0.0.1:8080 weight=3 max_fails=3 fail_timeout=15s;
server 127.0.0.1:8081 weight=1 max_fails=3 fail_timeout=15s;
keepalive 64; # 保持 64 条到上游的空闲长连接
}
max_fails 与 fail_timeout 是 502 的"减震器":当某节点连续失败到 max_fails 次,Nginx 会在 fail_timeout 时间内把它摘掉,请求转给其他节点,用户就不一定看到 502。但要注意:如果只有一个 upstream 节点,摘掉就没得转,用户直接吃 502。所以生产环境建议至少两个实例。
这里有个容易误解的点:max_fails 默认值是 1,意味着一次失败就立刻摘除节点。听起来很"灵敏",但放在有瞬时抖动的网络上就过于激进了——后端偶尔一个慢请求触发超时,节点就被判定不可用,反而可能把健康节点也摘了,于是出现 no live upstreams 全线 502。所以生产环境通常把 max_fails 调到 2~3,fail_timeout 保持 10~30s(经验值),给后端一点容错的余地,同时又不至于让故障节点长期停留在池子里。
三、proxy 超时四件套
超时配置是 502/504 排查的核心。四个超时各管一段:
| 指令 | 管什么 | 默认值 | 经验取值 |
|---|---|---|---|
proxy_connect_timeout |
建立到上游的连接 | 60s | 3~5s |
proxy_send_timeout |
向上游发送请求 | 60s | 30~60s |
proxy_read_timeout |
等待上游响应 | 60s | 30~60s(慢接口可放宽) |
send_timeout |
向客户端发送响应 | 60s | 30~60s |
location /api/ {
proxy_pass http://backend;
proxy_connect_timeout 5s; # 连不上快速失败,别让用户干等
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2; # 最多重试 2 次
proxy_next_upstream_timeout 10s;
}
为什么 proxy_connect_timeout 建议调小到 3~5s? 如果后端宕了、端口没人监听,操作系统会很快返回"连接被拒",此时连接超时用不上;但如果后端机器网络不通(比如网络设备丢包)、SYN 得不到响应,连接会一直挂到 proxy_connect_timeout 才报错。把这个值设小,能让失败更快暴露、更快切换到其他节点,减少用户等待。默认 60s 太长,用户体验很差。
proxy_next_upstream 是故障转移的关键:它列出"遇到哪些情况就换下一个上游节点重试"。error 覆盖连接错误,timeout 覆盖超时,http_502/503/504 覆盖上游返回的错误码。重试要求请求幂等,对 POST 支付、下单这类非幂等请求要格外小心,重试可能导致重复提交,业务侧需要配合幂等设计。
四、几个高频 502 根因与对应处理
根因一:后端进程不在了。 看进程和端口:
sudo ss -lntp | grep 8080 # 端口在不在
ps -ef | grep -i java | grep -v grep
sudo journalctl -u myapp -n 100 --no-pager # 看服务日志(systemd 托管)
根因二:端口/地址写错。 后端实际监听 8081,Nginx 却写 8080。用 ss 对照 proxy_pass 逐字核对。
根因三:SELinux 拦截(RHEL 系)。 表现是 Nginx 能本地 curl 通但通过 Nginx 访问 502,且 audit.log 有 AVC 拒绝。处理:
# 查看最近被拒绝的记录
sudo ausearch -m avc -ts recent
# 允许 nginx/httpd 发起网络连接
sudo setsebool -P httpd_can_network_connect on
风险提示:不要用 setenforce 0 永久关闭 SELinux 来"解决"502,应通过布尔值或策略调整放行。若临时关闭排查,记得 setenforce 1 恢复。
根因四:上游响应头过大/不合法。 后端返回的超大头或畸形头会让 Nginx 报 upstream sent invalid header 或 upstream sent too big header。可适当调大缓冲:
proxy_buffer_size 16k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
根因五:keepalive 配置不当。 想让 Nginx 与上游复用长连接,除了 upstream 里写 keepalive 64,还必须同时设置:
upstream backend {
server 127.0.0.1:8080;
keepalive 64;
}
location / {
proxy_pass http://backend;
proxy_http_version 1.1; # 长连接需要 HTTP/1.1
proxy_set_header Connection ""; # 清掉 close,避免连接不复用
}
漏了后两条,keepalive 形同虚设,还会频繁建连,高并发下更容易出现 502。
五、一套可执行的排查流程
按顺序执行,基本能从"一片 502"收敛到具体原因:
# 1. 看 Nginx error.log,抓 upstream 报错原文
sudo tail -f /var/log/nginx/error.log
# 关键短语:
# connect() failed (111: Connection refused) -> 后端没监听/进程挂
# no live upstreams -> 所有节点都被摘除
# upstream prematurely closed connection -> 后端主动断开/崩溃
# upstream sent invalid header -> 响应头异常
# upstream timed out (110) -> 超时(更偏 504)
# 2. 从 Nginx 机器直接打后端,绕过代理验证
curl -v http://127.0.0.1:8080/health
curl -w "connect=%{time_connect} total=%{time_total}\n" -o /dev/null -s http://127.0.0.1:8080/
# 3. 看后端进程/端口/日志
sudo ss -lntp | grep 8080
sudo journalctl -u myapp -n 200 --no-pager
# 4. 多节点时确认存活节点数
# Nginx 不直接暴露 upstream 状态,可看错误日志里是否有 no live upstreams
改配置的标准动作:先备份 → 改 → nginx -t 校验 → nginx -s reload → 观察 error.log。回滚就是把 .bak 复制回去再 reload。
sudo cp /etc/nginx/conf.d/app.conf /etc/nginx/conf.d/app.conf.bak
sudo vim /etc/nginx/conf.d/app.conf
sudo nginx -t && sudo nginx -s reload
# 回滚:sudo cp /etc/nginx/conf.d/app.conf.bak /etc/nginx/conf.d/app.conf && sudo nginx -t && sudo nginx -s reload
发布期 502 的治理:应用停止/启动期间端口不可用,是 502 的高发时段。解决办法是优雅停机(处理完在途请求再退出)、多实例滚动发布,并在 Nginx 侧配 proxy_next_upstream 把请求导到健康节点,让用户在发布期间几乎无感。
六、监控与预防
光靠人肉看日志不够,建议给 upstream 健康状态加监控:Nginx 商业版有 upstream 状态页,开源版可以借助 nginx-prometheus-exporter 或直接采集 error.log 里的 upstream 错误做告警。经验做法是:
- 对
error.log里upstream关键字做计数告警,5 分钟内超过阈值(如 10 次,经验值)就提醒。 - 给每个后端实例配
upstream健康检查(max_fails/fail_timeout是内置的被动检查)。 - 后端服务增加
/health接口,配合负载均衡或编排平台做主动健康检查。
另外要提醒的是,502 的排查不能只盯 Nginx 一侧。如果 Nginx 前面还有一层云负载均衡或 CDN,它们自己也可能产生 502,且它们的错误日志往往不在你的服务器上。遇到"改了半天 Nginx 都没用"的情况,先确认 502 到底是哪一层返回的:用 curl -v 看响应里的 Server 头、看有没有 CDN 的特征头(如 Via、X-Cache),必要时直接绕开外层、用后端机器 IP 直连验证。只有先把"是谁在报 502"这件事钉死,后面的排查才不会做无用功。
常见问题
Q1:只有一台后端,出现 502 怎么快速定位?
先用 ss -lntp 确认后端端口在不在,再用 curl 直连后端。若直连不通,问题在后端;若直连通但 Nginx 报 502,重点看 SELinux、proxy_pass 地址和响应头大小。
Q2:proxy_connect_timeout 设多大合适?
经验上 3~5s。设太大会让网络不通的后端拖着用户等待,设太小在跨机房高延迟链路可能误判。内网同机建议 2~3s,跨机房可 5s 左右。
Q3:proxy_next_upstream 重试会导致订单重复吗?
可能。对非幂等请求(下单、支付)要谨慎开启重试,或让后端做幂等(唯一请求号去重),否则一次请求被重试两次可能产生两笔业务。
Q4:配了 keepalive 但连接还是不复用?
检查是否同时设置了 proxy_http_version 1.1 和 proxy_set_header Connection "",缺一个都会让长连接失效。
Q5:no live upstreams 是什么意思?
所有上游节点都被判定为不可用(失败次数达到 max_fails 被摘除)。此时要么后端全挂,要么 max_fails 设得太小、把健康节点也误摘了。
总结
- 502 的本质是 Nginx 无法从上游拿到有效响应,重点查"连接能否建立、后端进程是否存活、响应是否合法",与"等太久"的 504 区分开。
upstream块用max_fails/fail_timeout做被动摘除、keepalive复用长连接;后者必须配合proxy_http_version 1.1和清空Connection头才生效。- 超时四件套各管一段,
proxy_connect_timeout建议 3~5s(经验值)让故障快速暴露,proxy_read_timeout管等待上游响应。 proxy_next_upstream能自动故障转移,但重试仅适用于幂等请求,非幂等业务需配套幂等设计。- 排查按"看 error.log 的 upstream 原文 → 直连后端验证 → 查进程/端口/SELinux → 改配置先备份后
nginx -t再 reload"执行,最稳。
企业QQ咨询




