Nginx 502 Bad Gateway 排错:从上游到配置的五步定位法
Nginx 502 Bad Gateway 是反向代理场景最常见的报错之一:客户端看到 502,说明 Nginx 已经收到了请求,但在与上游(upstream)通信时出了问题。502 本身不告诉你上游是谁、错在哪一环,所以排错的关键是分层定位:先确认是谁返回了 502,再沿着“上游存活 → 网络连通 → 协议与超时 → 配置”逐层收窄。
第一步:看日志,确认 502 的来源
先看 Nginx 的 error_log,重点关注 upstream 相关行:
2026/11/19 10:00:00 [error] 1234#0: *56 connect() failed (111: Connection refused) while connecting to upstream, client: 10.0.0.5, server: example.com, upstream: "127.0.0.1:8080"
这一行直接给出了上游地址和失败原因。常见的几种:Connection refused 表示上游端口没在监听;Connection timed out 表示网络不通或上游无响应;no live upstreams 表示 upstream 组里所有节点都被标记为不可用。同时对照 access_log 里 502 对应的请求路径,确认是哪个 location、哪个 upstream。
第二步:确认上游进程是否真的在跑
到上游机器上检查进程和监听端口:
ps -ef | grep java
ss -tlnp | grep 8080
curl -v http://127.0.0.1:8080/health
如果进程不存在,先看应用自己的日志:是不是启动失败、端口被占用、内存不足被 OOM Killer 杀掉了。如果进程在但端口没监听,可能是应用绑定了错误的地址(比如只绑了 127.0.0.1,而 Nginx 通过内网 IP 访问),或者启动尚未完成。本地 curl 能通而 Nginx 不通时,重点怀疑网络与防火墙。
第三步:检查网络与防火墙
Nginx 与上游不在同一台机器时,逐跳验证:ping 上游 IP、telnet 上游端口、检查安全组与主机防火墙是否放行。云上常见坑是:安全组只放行了 80/443,忘记放行上游业务端口;或者上游服务重启后 IP 变了,而 Nginx 的 upstream 还是旧地址。把 upstream 写成域名时,还要确认 Nginx 启动后 DNS 解析是否刷新——Nginx 只在启动或 reload 时解析一次域名,IP 变更后需要 reload。
第四步:核对超时与缓冲配置
如果上游偶发 502、且错误是 upstream timed out 或 upstream sent too big header,问题多在超时与缓冲。检查这几项:
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_buffer_size 8k;
proxy_buffers 8 16k;
上游接口偶尔慢查询超过 proxy_read_timeout 时,Nginx 会直接返回 502,这时应该优化上游接口或适当放宽超时,而不是一味加大——超时放得太大,故障时会拖垮 Nginx 的连接池。响应头过大时则要调大 proxy_buffer_size。
第五步:检查 upstream 健康状态与配置细节
执行 nginx -t 验证配置语法,再 nginx -s reload 让配置生效。检查 upstream 块里有没有把节点写错端口、weight 配成 0、或者 backup 节点被误当成主节点。开启了 proxy_next_upstream 时,Nginx 会在上游出错后尝试下一个节点,重试耗尽后才返回 502,这会让日志里出现多次 upstream 记录,读日志时不要只看最后一行。
收尾:一份可复用的检查清单
按“日志定来源 → 进程查存活 → 网络验连通 → 超时核配置 → reload 再验证”的顺序走一遍,大多数 502 都能在十分钟内定位。定位后顺手做两件事:一是把关键接口的健康检查与告警补上,二是把 proxy_read_timeout 等参数和本次根因写进运维文档。下次再看到 502,先看 error_log 里的 upstream,再动手,少走很多弯路。
- 点赞
- 收藏
- 关注作者
评论(0)