Nginx 502 Bad Gateway：从上游进程到超时配置排查

适用范围与前提

适用于 Linux 上代理 HTTP/HTTPS 上游的 Nginx；FastCGI 与 gRPC 的配置项不同。

先确认上游地址、服务负责人及失败路径，并取得代理日志读取权限。nginx -T 可能显示敏感配置。

常见症状

• 浏览器或负载均衡返回 502
• error.log 中出现 connect() failed、upstream timed out 或 connection refused
• 单个路径或全部接口受影响

1. 先缩小影响范围

从 Nginx 所在主机请求 upstream 的健康检查或目标端口。若只有一台后端异常，先从 upstream 列表中摘流量；若全部异常，优先检查共享依赖和最近的发布变更。

curl -sv http://127.0.0.1:8080/health
ss -lntp | grep 8080
tail -n 100 /var/log/nginx/error.log

2. 区分连接失败与响应超时

connection refused 通常表示未监听、进程退出、地址错误或主动拒绝。超时日志须区分 while connecting 与 while reading；前者未必建立 TCP，后者是在等待上游数据。网关超时常表现为 504，不要仅凭超时字样当作 502 或盲目延长超时。

grep -E "connect|upstream timed out" /var/log/nginx/error.log | tail -n 30
systemctl status your-app.service --no-pager

3. 检查代理协议与上游地址

核对 proxy_pass 的协议、路径拼接和 upstream DNS 解析。HTTPS upstream 还要确认 SNI、证书链和 proxy_ssl_server_name。容器环境中应从 Nginx 容器内部验证 DNS 与网络连通性。

nginx -T | sed -n "/proxy_pass/p"
getent hosts backend.internal

解读证据

说明性诊断案例

以下假设案例用于解释推理，并非客户真实事故，也不代表已在你的技术环境中测试。

应用发布后代理返回 502，日志指向 127.0.0.1:8080，但应用改为监听 8081。延长超时无法修复地址不一致。对照部署约定与实际监听，恢复经过确认的地址或应用设置，再通过代理验证同一请求。

验证恢复

• 通过正式域名复测原失败路径，同时检查状态码与响应内容，不能只测无关的 /health。
• 在具有代表性的流量下观察所有后端的错误与延迟；单次成功可能只命中了健康节点。

回滚与停止条件

修改前保存原代理配置；nginx -t 失败时不要重载。重载后错误上升则恢复原配置并重新校验，但不要把已知故障后端重新接入。