修复 Nginx 502 Bad Gateway 错误：分步指南
通过检查配置、上游服务健康状态、日志、套接字、Docker 网络和超时症状，追踪 Nginx 502 错误。
修复 Nginx 502 Bad Gateway 错误：分步指南
修复 Nginx 502 Bad Gateway 错误首先要理解 Nginx 通常是信使，而非故障的原始来源。502 表示 Nginx 尝试与上游服务通信但未获得有效响应。
该上游服务可能是 Node.js 应用、PHP-FPM、Gunicorn、Puma、容器或其他 HTTP 服务器。你的任务是找到交接失败的位置。
Nginx 中 502 Bad Gateway 的含义
Nginx 通常位于应用服务器之前。它接受公共流量、处理 TLS、提供静态文件，并将动态请求转发到上游。
当上游连接失败或返回 Nginx 无法使用的内容时，就会出现 502。常见原因包括：
- 应用进程已停止。
- Nginx 指向错误的端口或套接字。
- Unix 套接字权限不正确。
- 上游服务在请求期间崩溃。
- 防火墙或容器网络阻止连接。
- 上游发送无效的 HTTP 响应。
从失败的确切请求路径开始。如果只有 /api 返回 502 但静态页面正常加载，则静态文件服务正常，代理或应用后端可能是问题所在。如果每个页面都失败，则问题可能更广泛，涉及 Nginx、DNS 或上游可用性。
第 1 步：检查 Nginx 状态和配置
首先确认 Nginx 正在运行：
systemctl status nginx
然后测试配置：
nginx -t
如果配置测试失败，先修复它再追踪应用程序。Nginx 可能仍在运行旧配置，或者在重新加载时失败。
配置测试成功后，重新加载 Nginx：
systemctl reload nginx
不要在繁忙的服务器上盲目重启，除非你了解影响。配置更改后重新加载通常就足够了，且破坏性较小。
接下来，检查活动的 server 块。查找 proxy_pass、fastcgi_pass 或 uwsgi_pass。典型的反向代理可能包含：
location / {
proxy_pass http://127.0.0.1:3000;
}
这意味着 Nginx 期望本地端口 3000 上有一个应用程序。如果应用程序实际监听 3001，或者仅在 Docker 网络内部，Nginx 将失败。
有关更多命令式检查，请参阅 Nginx 配置测试命令。
第 2 步：验证上游服务
现在直接从 Nginx 主机测试上游。如果 Nginx 代理到 127.0.0.1:3000，运行：
curl -i http://127.0.0.1:3000/
如果失败，问题不在于浏览器或公共 DNS。Nginx 无法访问后端，因为后端已关闭、在其他地方监听或拒绝请求。
检查应用程序进程：
ss -ltnp
查找预期的端口。如果服务使用 Unix 套接字，检查套接字路径：
ls -l /run/app/app.sock
Nginx 工作进程用户必须能够访问该套接字。在许多 Linux 系统上，Nginx 以 www-data、nginx 或特定服务用户身份运行。如果套接字由其他用户拥有且未按需设置为组可读或可写，Nginx 可能会记录权限错误并返回 502。
对于 PHP-FPM 设置，确认池正在运行：
systemctl status php-fpm
服务名称可能包含版本号，例如 php8.2-fpm，具体取决于发行版。
第 3 步：读取 Nginx 错误日志
Nginx 错误日志通常会告诉你遇到的是哪种故障模式。常见的日志消息包括：
connect() failed (111: Connection refused) while connecting to upstream
这意味着 Nginx 到达了主机，但该端口上没有进程接受连接。
upstream timed out while reading response header from upstream
这意味着 Nginx 已连接，但后端未及时响应。
permission denied while connecting to upstream
这通常指向 Unix 套接字权限或安全控制（如 SELinux）。
使用以下命令检查最近的错误：
tail -n 100 /var/log/nginx/error.log
在基于 systemd 的系统上，你还可以检查：
journalctl -u nginx -n 100
将日志中的时间戳与浏览器请求的时间匹配。这可以避免你追踪已不再相关的旧错误。
有关更深入的日志工作流程，请参阅 分析 Nginx 错误日志。
第 4 步：修复最常见的根本原因
一旦知道故障模式，应用与之匹配的最小修复。
如果应用程序未运行，启动或重启应用程序服务：
systemctl restart your-app
然后在使用 Nginx 测试之前，先用 curl 测试上游。
如果 Nginx 指向错误的端口，更新 proxy_pass 目标并重新加载 Nginx。确保你的应用程序和 Nginx 在 IPv4 与 IPv6 上也保持一致。监听 127.0.0.1 的应用程序与仅监听 ::1 的应用程序不同。
如果涉及 Docker，检查 Nginx 是在主机上运行还是在容器内运行。容器内的 127.0.0.1 指向该容器，而不是主机。你可能需要 Docker 服务名称、桥接网络或已发布的端口。
如果上游超时，检查应用程序日志。后端可能卡在数据库查询、外部 API 调用或启动工作上。提高 Nginx 超时时间可以掩盖症状，但无法修复损坏或过载的应用程序。
何时寻求专业帮助
当 502 错误影响生产环境，且在检查日志、上游状态和最近部署后原因仍不明显时，请咨询高级工程师或托管服务提供商。如果问题涉及负载均衡器、容器编排、SELinux 策略或高流量超时调优，也应寻求帮助。
对于生产系统，避免重复的随机重启。它们可能会清除证据，使故障更难理解。
502 Bad Gateway 错误是可修复的，只要你按顺序追踪请求路径。确认 Nginx 有效，直接测试上游，读取确切的错误日志行，并应用与故障匹配的修复。这种方法比盲目更改超时或重启服务更快、更安全。