Nginx 502 Bad Gateway 的五个排查步骤:从 upstream 到超时配置
服务跑起来之后,最让人心慌的报错之一就是 502 Bad Gateway。页面刷不出来、接口调不通,偏偏 Nginx 的欢迎页又能正常打开。502 的意思是:Nginx 作为反向代理去请求后端(upstream)时,没有拿到一个有效的响应。也就是说,问题一般不在 Nginx 本身,而在 Nginx 和后端之间的链路上。
遇到 502 先别急着重启服务。按下面五个步骤由外到里查,大多数 502 都能在十分钟内定位。
一、先确认 Nginx 本身是不是活着
第一步永远是确认反向代理本身没问题:
systemctl status nginx --no-pager
curl -I http://127.0.0.1/
如果 systemctl 显示 active (running),并且本机 curl 能返回响应头,Nginx 就是正常的。反过来,如果 Nginx 没启动,先看启动报错:
nginx -t
journalctl -u nginx --no-pager -n 50
nginx -t 会检查配置文件语法,很多人改配置时少了分号或括号,Nginx 拒绝启动,重启后直接 502。确认配置无误再往下查。
二、直接访问后端,看它还活不活
502 最常见的原因其实是后端挂了:应用崩溃退出、监听端口变了、启动失败。跳过 Nginx,直接对后端发一个请求:
curl -v http://127.0.0.1:8000/health
如果后端直连也失败,问题就锁定在应用侧。接下来查三点:进程还在不在(ps -ef | grep 应用名)、端口还在监听吗(ss -tlnp | grep 8000)、应用日志最后一屏报了什么错。后端如果在启动时就崩溃,日志里一般能直接看到异常堆栈;如果端口被别的进程占了,换回正确端口或停掉占用的进程。
三、核对 proxy_pass 与端口有没有写错
后端明明活着却还报 502,就要看 Nginx 的转发配置。典型配置是这样的:
location /api/ {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
重点核对三处:proxy_pass 的地址和端口是不是和后端实际监听的一致;如果用了 upstream 块,名字有没有拼错;location 的路径拼写是否匹配。改完配置先做语法检查再重载:
cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
nginx -t && systemctl reload nginx
改配置前先备份是个好习惯,出问题能一秒回滚。注意 reload 是平滑重载,不会中断正在处理的请求。
四、看超时配置够不够用
如果 502 只在某些慢接口上出现,错误日志里写着 upstream timed out,那就是后端响应太慢,超过了 Nginx 的等待时间。常见默认值只有 60 秒,一些报表导出、大文件处理很容易超。相关配置在 location 里加:
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 120s;
三个参数各管一段:connect 是建立连接的等待时间,send 是发送请求的等待时间,read 是等后端返回的等待时间。临时调大超时可以先恢复服务,但根因还得回后端解决:慢查询加索引、接口加缓存、连接池打满就扩容。只调大超时不治理后端,502 迟早会回来。
五、把错误日志当作最后裁判
前四步还没定位,就回错误日志找原文:
tail -n 100 /var/log/nginx/error.log | grep -i upstream
再配一张速查表,对照日志关键字直接定性:
| 日志或现象 | 可能原因 | 处理 |
|---|---|---|
| connect() failed (111: Connection refused) | 后端没启动或端口不对 | 重启应用,核对监听端口 |
| upstream timed out | 后端响应慢,超出 read 超时 | 先调大超时,再优化后端 |
| no live upstreams | upstream 组里后端全挂 | 逐个检查后端健康状态 |
| 偶发 502,重启后恢复 | 后端重启或连接耗尽 | 查连接数与重启记录 |
同时看一眼访问日志里 502 出现的时间分布:集中在某个时段可能是定时任务拖垮了后端;均匀出现多半是配置或容量问题。
小结
502 的排查顺序可以浓缩成一句话:先看 Nginx 活没活,再直连后端活没活,然后核对 proxy_pass,最后看超时和错误日志。大多数 502 不是什么疑难杂症,而是后端挂了、端口写错、响应太慢这三类原因中的一种。按这个顺序查,配合错误日志原文定位,比反复重启省时间,也更接近根因。
- 点赞
- 收藏
- 关注作者
评论(0)