Web 服务器与网关 / 技术文章
Nginx 502 和 504 为什么要分开排查
Nginx 出现 502 或 504,适合 Linux 运维、SRE 和负责线上部署的后端工程师使用。关键不是背状态码,而是判断请求卡在哪个阶段:读完后可以结合错误日志、连接检查和上游响应时间,区分“上游连接失败”和“上游响应超时”,避免两种故障使用同一套排查方法。
502 和 504 分别说明什么
502 Bad Gateway 通常表示 Nginx 作为网关访问上游时,没有得到可作为有效网关响应处理的结果,常见于连接被拒绝、连接被重置、上游返回异常响应等场景。
504 Gateway Timeout 更强调时间:Nginx 已经向上游发起请求,但在规定时间内没有等到需要的响应。也就是说,504 的核心线索通常是“等不到”,而 502 更值得先检查“连不上或返回异常”。
排查时不要把状态码直接等同于某一个根因。502 可能来自上游进程未监听端口,也可能来自连接建立后被关闭;504 也不一定是应用代码慢,还可能是网络链路、数据库调用或其他下游依赖拖住了请求。
先看 Nginx 错误日志
第一步优先确认 Nginx 自己观察到了什么,而不是立即重启应用。典型配置和检查命令如下:
server {
listen 80;
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_connect_timeout 3s;
proxy_read_timeout 30s;
}
}sudo tail -n 100 /var/log/nginx/error.log
sudo ss -lntp | grep ':8080'
curl -v --max-time 5 http://127.0.0.1:8080/health预期结果:日志应出现具体的 upstream 错误;ss 可以确认 8080 是否存在监听;curl 可以验证绕过 Nginx 后上游是否能够直接返回响应。
看到 connect() failed (111: Connection refused) 时,应优先检查上游进程、监听地址和端口。看到 upstream timed out 时,则应继续定位请求在哪个等待阶段消耗了时间。
502 优先查连接和上游进程
502 排查可以沿着“域名解析或 upstream 配置 → 网络连接 → 上游监听 → 上游进程 → 响应是否合法”的顺序收缩范围。
如果 Nginx 配置的 upstream 是 127.0.0.1:8080,但应用只监听了其他端口,Nginx 建立连接时就会失败。另一个常见问题是应用只监听 127.0.0.1,而 Nginx 运行在另一台机器,此时即使应用本机正常,远程连接仍然失败。
还要区分“端口不通”和“连接后立即被关闭”。前者更像监听、端口或网络问题,后者则需要检查应用启动状态、崩溃日志、连接数耗尽以及协议响应是否完整。
可以直接在 Nginx 所在机器执行:
nc -vz 127.0.0.1 8080
curl -sv --max-time 5 http://127.0.0.1:8080/health预期输出:nc 成功表示 TCP 连接至少能够建立;curl 能返回 HTTP 状态码,则说明应用端口不仅监听,而且已经能处理请求。若这里已经失败,不必继续从 Nginx 路由规则入手,应先处理上游本身。
504 优先查等待发生在哪里
504 的关键问题不是“服务是不是启动了”,而是“请求为什么没有在超时时间内完成”。应用进程可能完全正常,只是某个接口在高峰期执行了慢 SQL、等待下游 HTTP、争抢连接池,或者因为线程与协程资源不足而迟迟无法返回。
排查时可以先比较三段时间:Nginx 收到请求后的总耗时、Nginx 等待上游响应的时间、应用内部真正执行请求的时间。若应用日志显示请求只用了几百毫秒,但 Nginx 等待明显更久,应继续检查网络或连接建立过程;若应用本身就持续几十秒,则应转向数据库、缓存、RPC 或线程池等下游依赖。
例如可以临时从应用机器发起同一接口请求:
curl -sS -o /dev/null -w 'connect=%{time_connect} start=%{time_starttransfer} total=%{time_total}\n' \
--max-time 40 http://127.0.0.1:8080/api/data预期结果:若 total 接近 Nginx 的 proxy_read_timeout,而应用最终可以返回,说明需要重点检查超时阈值与接口耗时;若请求本身持续卡住,则继续向应用内部和下游依赖追踪。
不要只靠调大超时时间
遇到 504 时直接把 proxy_read_timeout 从几十秒改成几分钟,只能改变 Nginx 等待的上限,并不会让慢请求真正变快,还可能让连接占用时间更长,放大并发压力。
同样,502 发生时反复执行 nginx -s reload 或重启应用,也可能暂时掩盖问题,却不会回答“为什么连接失败”。正确做法是先保存故障现场:错误日志、请求时间、upstream 地址、应用日志以及相关依赖的指标,然后再做配置或进程变更。
一套可重复的排查路径
可以把状态码作为分流信号,而不是最终答案。
Nginx 返回 502/504
|
+-- 502 --> 查 upstream 错误日志
| |
| +-- refused/reset --> 查监听、进程、网络
| +-- 异常响应 --> 查应用协议和进程状态
|
+-- 504 --> 查 upstream 超时位置
|
+-- 应用本身很慢 --> 查 SQL/RPC/线程池等依赖
+-- 应用很快 --> 查连接、网络与 Nginx 超时配置最终判断时,可以记住两个问题:502 先问“连接或响应哪里出了问题”,504 先问“时间花在哪里了”。先确认故障边界,再决定是查进程、端口、网络、应用还是下游依赖,排查路径会比单纯围绕状态码猜原因更稳定。