Nginx 502 / 504 错误排查指南

502 Bad Gateway 常见原因

• 后端应用没有启动，Nginx 连接不上 upstream。
• proxy_pass 写错端口、协议或 socket 路径。
• 后端进程崩溃，返回了非法响应。
• PHP-FPM、Node、Java 服务重启中或权限不足。

504 Gateway Timeout 常见原因

• 后端接口执行太慢，超过 Nginx 代理超时时间。
• 数据库、第三方 API 或内网服务响应慢。
• 服务器负载过高，应用线程/连接池耗尽。
• 防火墙或网络策略让 Nginx 无法及时连接上游。

常用检查命令

systemctl status nginx
nginx -t
tail -n 100 /var/log/nginx/error.log
ss -lntp
curl -I http://127.0.0.1:后端端口

把 502 和 504 分开处理

经过 CDN 的场景请继续使用CDN 502 Bad Gateway 排查清单，不要一开始就扩大超时时间。

查看同一请求的完整证据链

sudo tail -f /var/log/nginx/error.log
sudo journalctl -u myapp -f
curl -sv --resolve example.com:443:源站IP https://example.com/ -o /dev/null

同时观察 Nginx 和应用日志，按时间戳对应同一次请求。--resolve 可在不修改公共 DNS 的情况下携带正确 Host 与 TLS SNI 访问指定源站。

十分钟内完成一次分层定位

1. 记录可复现入口。保存完整 URL、请求时间、状态码和是否经过 CDN。只有登录后出现时，还要区分公开页面与带 Cookie 的应用请求。
2. 确认 Nginx 自身正常。nginx -t 通过只代表配置语法正确，还要检查服务状态、80/443 监听以及对应虚拟主机是否命中。
3. 绕过代理访问上游。在 Nginx 所在机器直接请求 127.0.0.1:端口、Unix Socket 或容器服务名。若这里已经失败，先修应用，不要继续改 Nginx。
4. 对应同一次请求的日志。用时间戳或请求 ID 对齐 access.log、error.log 与应用日志，确认请求是在连接、发送、读取响应头还是处理业务时失败。
5. 修复后从外部复测。上游直连成功后，再经过 Nginx、CDN 和公开域名逐层测试，确认错误页不是中间缓存留下的旧响应。

容器与 Unix Socket 容易漏掉什么

容器里的 127.0.0.1 只指向当前容器，不一定是宿主机或另一个应用容器。Nginx 在宿主机、应用在 Docker 时，应使用明确发布的宿主端口或同一容器网络中的服务名，并确认应用监听 0.0.0.0 而不是只监听容器内回环地址。

使用 Unix Socket 时，文件存在不代表 Nginx 有权限连接。应沿目录逐级检查执行权限、Socket 所属用户组和服务重启后路径是否改变。把 Socket 临时改成全员可写会掩盖权限模型问题，不应作为长期修复。

namei -l /run/myapp/app.sock
sudo -u www-data curl --unix-socket /run/myapp/app.sock http://localhost/health
docker ps --format 'table {{.Names}}\t{{.Ports}}\t{{.Status}}'

什么时候才应该调整超时

只有应用在预期时间内确实可以完成任务，并且业务允许用户等待时，才考虑修改 proxy_connect_timeout、proxy_send_timeout 或 proxy_read_timeout。如果慢请求来自无索引 SQL、连接池耗尽、外部接口无超时或后台任务误放在同步请求里，扩大 Nginx 超时只会让更多连接长期占用。

调整前先记录应用 P50、P95、P99 耗时和最慢调用位置。长任务更适合进入队列并返回任务状态；健康检查接口应保持轻量，不能依赖全部下游服务都完成复杂查询。