---

解决 Nginx 502 Bad Gateway 故障：完整指南

引言

在运维 Web 服务时，Nginx 502 Bad Gateway 是一个非常常见且令人头疼的错误。它表示 Nginx 作为反向代理或网关，未能从上游服务器（例如 PHP-FPM、Gunicorn、uWSGI、Tomcat 等应用服务器）获得有效响应。简而言之，Nginx 成功地将请求发送给了上游服务器，但上游服务器却未能及时或正确地处理请求并返回结果，导致 Nginx 无法完成客户端请求。

解决 502 错误需要系统性的排查方法，因为它可能由多种原因引起，包括上游服务未运行、配置错误、资源耗尽、网络问题甚至应用程序本身的缺陷。本文将提供一个完整的指南，详细阐述 Nginx 502 Bad Gateway 故障的排查步骤、常见原因及解决方案，并分享一些预防措施，帮助您快速定位并解决问题。

一、理解 502 Bad Gateway

首先，我们来深入理解 502 错误发生的机制。Nginx 通常作为前端的 Web 服务器，接收客户端的 HTTP 请求。当请求需要动态内容时，N它会将请求转发给一个或多个后端应用服务器处理。这个后端应用服务器就是“上游服务器”（Upstream Server）。Nginx 502 错误意味着：

1. Nginx 正常运行：它成功接收了客户端请求。
2. Nginx 尝试连接上游服务器：它按照配置将请求转发了出去。
3. 上游服务器未能提供有效响应：
   • 上游服务器可能根本就没有运行。
   • 上游服务器可能运行了，但因过载、崩溃或配置错误而无法处理请求。
   • 上游服务器可能处理了请求，但在规定时间内未能返回响应（超时）。
   • 上游服务器可能返回了无效或无法识别的响应。

因此，解决 502 问题的核心在于诊断出上游服务器为什么未能响应，以及 Nginx 与上游服务器之间的通信是否顺畅。

二、排查准备与常用工具

在开始排查之前，请确保您具备以下权限和工具：

• SSH 访问权限：能够登录到 Nginx 和应用服务器所在的机器。
• sudo 权限：用于执行需要管理员权限的命令。
• 文本编辑器：如 vi、nano，用于查看和修改配置文件。
• 常用 Linux 命令：
  • tail -f：实时查看日志文件。
  • grep：在日志或文件中搜索特定字符串。
  • systemctl 或 service：管理系统服务（启动、停止、重启、查看状态）。
  • ps aux：查看正在运行的进程。
  • netstat -tulnp 或 ss -tulnp：查看网络连接和监听端口。
  • top 或 htop：监控系统资源（CPU、内存、进程）。
  • df -h：查看磁盘空间使用情况。
  • free -h：查看内存使用情况。
  • nginx -t：测试 Nginx 配置文件的语法。
  • curl 或 telnet：测试网络连通性。

三、系统性排查步骤

解决 502 错误需要一个系统性的、由外到内的排查流程。

步骤 1：检查 Nginx 错误日志（首要任务）

Nginx 错误日志是诊断 502 问题的最关键信息源。它会记录 Nginx 在尝试与上游服务器通信时遇到的具体问题。

• Nginx 错误日志路径：通常位于 /var/log/nginx/error.log。具体路径可能在 nginx.conf 中定义，查找 error_log 指令。
• 查看命令：sudo tail -f /var/log/nginx/error.log 或 sudo cat /var/log/nginx/error.log | grep "502"。

常见错误信息及含义：

• connect() failed (111: Connection refused) while connecting to upstream：

  • 含义：Nginx 尝试连接上游服务器的 IP 地址和端口时，被拒绝了连接。这通常意味着上游服务器没有运行，或者上游服务器正在监听不同的 IP/端口，或者防火墙阻止了连接。
  • 解决方向：检查上游服务状态、配置和防火墙。

• upstream prematurely closed connection while reading response header from upstream：

  • 含义：Nginx 成功连接到了上游服务器，但在读取响应头时，上游服务器意外地关闭了连接。这通常表示上游服务器在处理请求时崩溃、超时或内部错误。
  • 解决方向：检查上游服务日志、资源使用情况、超时设置和应用程序代码。

• No such file or directory while connecting to upstream：

  • 含义：如果 Nginx 配置使用 Unix socket 连接上游服务（如 PHP-FPM），但指定的 socket 文件不存在或路径错误。
  • 解决方向：检查上游服务配置中 socket 路径，Nginx 配置中 fastcgi_pass 或 proxy_pass 的 socket 路径，并确认 socket 文件是否存在及权限。

• recv() failed (104: Connection reset by peer) while reading response header from upstream：

  • 含义：与 prematurely closed connection 类似，表示连接被上游服务器重置。可能原因与上一个相同。
  • 解决方向：同上。

• upstream timed out (110: Connection timed out) while connecting to upstream：

  • 含义：Nginx 尝试连接上游服务器，但在预设的连接超时时间内未能建立连接。
  • 解决方向：检查网络连通性、上游服务是否响应缓慢、Nginx 的 proxy_connect_timeout。

• client intended to send too large body：

  • 含义：客户端上传的文件大小超过了 Nginx 的 client_max_body_size 限制。
  • 解决方向：增加 client_max_body_size。

步骤 2：检查上游服务状态和日志

根据 Nginx 错误日志的指引，下一步是直接检查上游应用服务器。

以 PHP-FPM 为例：

1. 检查 PHP-FPM 服务状态：

   • sudo systemctl status php-fpm (或 php7.4-fpm 等，取决于版本和系统)
   • sudo service php-fpm status (旧系统)
   • ps aux | grep php-fpm (确认进程是否存在)

   如果服务未运行，尝试启动它：sudo systemctl start php-fpm。如果启动失败，查看 PHP-FPM 的启动日志。

2. 检查 PHP-FPM 错误日志：

   • 路径：通常位于 /var/log/php-fpm/www-error.log 或 /var/log/php-fpm/error.log。具体路径可在 php-fpm.d/www.conf（或您的 pool 配置文件）中查找 php_admin_value[error_log]。
   • 查看命令：sudo tail -f /var/log/php-fpm/www-error.log。

   重点关注：
   * 内存耗尽错误：Allowed memory size of xxx bytes exhausted。
   * 致命错误/解析错误：Fatal error、Parse error。
   * 最大执行时间超时：Maximum execution time of N seconds exceeded。
   * 进程池子进程过多/过少：WARNING: [pool www] server reached pm.max_children setting。
   * PHP 应用程序本身的错误：如数据库连接失败、文件不存在等。

对于其他应用服务器（如 Gunicorn/uWSGI for Python, Node.js, Tomcat for Java）：

• 检查服务状态：使用 systemctl status <your_app_service> 或 ps aux | grep <your_app_process>。
• 检查应用日志：根据您的应用配置，查找其 stdout/stderr 日志或自定义日志文件。这些日志会记录应用内部的错误、崩溃信息等。

步骤 3：检查 Nginx 和上游服务配置

确保 Nginx 和上游服务的配置互相匹配且正确。

3.1 Nginx 配置检查

• Nginx 主配置文件：/etc/nginx/nginx.conf

• 站点配置文件：通常在 /etc/nginx/conf.d/ 或 /etc/nginx/sites-enabled/ 下。

• 验证 Nginx 配置文件语法：sudo nginx -t。如果存在语法错误，根据提示修正。

• proxy_pass 或 fastcgi_pass 指令：

  • 确认 Nginx 配置中 proxy_pass (通用代理) 或 fastcgi_pass (PHP-FPM) 指向的 IP/端口或 Unix socket 路径是正确的，并且与上游服务的监听地址一致。
  • 例如 PHP-FPM：
    nginx
# Nginx 站点配置
location ~ \.php$ {
fastcgi_pass unix:/run/php/php7.4-fpm.sock; # 或 127.0.0.1:9000
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
    请确保 fastcgi_pass 后面的地址（socket 或 IP:Port）与 PHP-FPM 实际监听的地址完全匹配。

• 超时设置：如果上游服务器处理请求时间过长，Nginx 可能会超时并返回 502。

  • proxy_connect_timeout：Nginx 等待与上游服务器建立连接的超时时间。
  • proxy_send_timeout：Nginx 等待上游服务器发送请求的超时时间。
  • proxy_read_timeout：Nginx 等待上游服务器发送响应的超时时间。
  • fastcgi_connect_timeout、fastcgi_send_timeout、fastcgi_read_timeout：针对 PHP-FPM 的类似设置。

  默认值通常是 60s。如果您的应用需要更长时间来处理请求，可以适当增加这些值，但也要警惕长时间超时可能带来的资源占用问题。

  “`nginx

  示例：增加超时时间

  http {
  …
  proxy_connect_timeout 75s;
  proxy_send_timeout 75s;
  proxy_read_timeout 75s;
  # 或针对 fastcgi
  fastcgi_connect_timeout 75s;
  fastcgi_send_timeout 75s;
  fastcgi_read_timeout 75s;
  …
  }
  ``
4. **缓冲区设置**：
* **proxy_buffer_size**, **proxy_buffers**, **proxy_busy_buffers_size**：这些设置影响 Nginx 如何处理来自上游的响应。如果上游返回的数据量很大，而缓冲区设置过小，也可能导致问题。
* **client_max_body_size`**：如果客户端上传文件过大，可能导致 502。

  “`nginx

  示例：增加缓冲区大小和客户端主体大小

  http {
  …
  client_max_body_size 20M; # 允许上传最大 20MB 文件
  proxy_buffer_size 128k;
  proxy_buffers 4 256k;
  proxy_busy_buffers_size 256k;
  …
  }
  “`

3.2 上游服务配置检查（以 PHP-FPM 为例）

• PHP-FPM 配置文件：通常在 /etc/php-fpm.d/www.conf (或 pool.d 下的其他文件)。

• 监听地址 (listen)：

  • 确认 listen 指令的值与 Nginx fastcgi_pass 中的值完全匹配。
  • 如果 Nginx 使用 Unix socket (unix:/path/to/socket.sock)，PHP-FPM 也要配置为监听相同的 socket：listen = /run/php/php7.4-fpm.sock。
  • 如果 Nginx 使用 TCP 端口 (127.0.0.1:9000)，PHP-FPM 也要配置为监听相同的端口：listen = 127.0.0.1:9000。

• 进程管理 (pm settings)：

  • pm = dynamic：动态管理进程。
  • pm.max_children：最大子进程数。如果请求量很大，这个值可能不够，导致 PHP-FPM 无法处理新请求。
  • pm.start_servers：启动时创建的子进程数。
  • pm.min_spare_servers：最小空闲子进程数。
  • pm.max_spare_servers：最大空闲子进程数。

  问题：当 pm.max_children 过低，所有子进程都在忙碌时，新请求将排队甚至被拒绝，Nginx 会超时。
  解决：根据服务器的内存和 CPU 情况，适当增加这些值。一个粗略的计算方法是：可用内存 / 每个 PHP 进程所需内存 ≈ pm.max_children。

• 请求执行时间限制 (request_terminate_timeout)：

  • 此设置在 PHP-FPM 级别控制单个请求的最大执行时间。如果 PHP 脚本执行时间超过此值，PHP-FPM 将终止该进程。
  • request_terminate_timeout = 60s (默认 0 表示不限制)。
  • 注意：此值应小于或等于 Nginx 的 fastcgi_read_timeout，否则可能出现 Nginx 超时（504）或 PHP-FPM 终止进程（502）的竞争情况。

• PHP 内存限制 (memory_limit)：

  • 在 php.ini (或通过 php_admin_value[memory_limit] 在 FPM 配置中设置)。如果 PHP 脚本耗尽了分配的内存，会导致错误并可能导致 502。

修改配置后，务必重启相应的服务：sudo systemctl restart nginx 和 sudo systemctl restart php-fpm。

步骤 4：检查系统资源

资源耗尽是导致上游服务崩溃或无法响应的常见原因。

1. CPU 使用率：

   • top 或 htop：查看 CPU 使用率。
   • 如果 CPU 持续在 100% 左右，可能表明应用程序或数据库负载过高，导致响应缓慢或无响应。

2. 内存使用率：

   • free -h：查看内存使用情况。
   • top 或 htop：查看各进程的内存占用。
   • 如果物理内存耗尽，系统可能会开始使用 SWAP 交换空间，这会导致性能急剧下降。
   • OOM Killer (Out Of Memory Killer)：当系统内存严重不足时，Linux 内核会启动 OOM Killer 随机杀死一些进程以释放内存。您可以在 dmesg 或 /var/log/syslog 中查找 OOM 相关信息：sudo dmesg | grep -i oom。如果您的 PHP-FPM 或其他应用进程被 OOM Killer 杀死，就会导致 502。

3. 磁盘空间：

   • df -h：检查磁盘空间使用情况。
   • 如果磁盘空间不足，应用程序可能无法写入日志、会话文件或临时文件，从而导致故障。

4. 文件描述符限制：

   • ulimit -n：查看当前用户的文件描述符限制。
   • ulimit -a：查看所有限制。
   • 如果应用程序打开的文件（包括网络连接）数量超过了系统或进程的限制，它可能无法处理新的连接，导致 502。
   • 您可以在 /etc/security/limits.conf 中修改系统级别的限制，或在服务启动脚本中为特定服务设置。

解决方案：
* 优化应用程序：减少 CPU 和内存消耗。
* 增加服务器资源：升级 CPU、内存或磁盘空间。
* 负载均衡：将流量分散到多个后端服务器。
* 调整进程数：根据资源情况合理配置 PHP-FPM 或其他应用的工作进程数。

步骤 5：检查网络连通性与防火墙

如果 Nginx 和上游服务位于不同的服务器上，或者即使在同一台服务器上使用 TCP 端口通信，网络问题也可能导致 502。

1. 测试网络连通性：

   • 从 Nginx 所在的服务器，尝试连接上游服务器的 IP 和端口。
   • 使用 telnet：telnet <上游IP> <上游端口> (例如 telnet 127.0.0.1 9000)
     • 如果显示 Connected，说明连接成功。
     • 如果显示 Connection refused，说明上游服务未在此端口监听，或者防火墙阻止了连接。
     • 如果显示 Connection timed out，说明网络不通或防火墙阻止了连接。
   • 使用 nc (netcat)：nc -vz <上游IP> <上游端口>
   • 使用 curl：curl -v <上游IP>:<上游端口> (如果上游是 HTTP 服务)

2. 检查上游服务器监听端口：

   • 在上游服务器上，使用 sudo ss -tulnp 或 sudo netstat -tulnp，确认上游服务正在监听正确的 IP 地址和端口。
   • 例如，对于 PHP-FPM，确认 0.0.0.0:9000 或 127.0.0.1:9000 正在监听。

3. 检查防火墙：

   • Nginx 服务器和上游服务器：检查两台机器上的防火墙规则。
   • UFW (Ubuntu/Debian)：sudo ufw status。确保允许 Nginx 访问上游服务所需的端口。
   • FirewallD (CentOS/RHEL)：sudo firewall-cmd --list-all。
   • SELinux/AppArmor：如果启用了这些安全模块，它们可能会阻止 Nginx 与上游服务通信。查看它们的日志（如 /var/log/audit/audit.log 对于 SELinux）是否有拒绝连接的记录。可以尝试临时禁用（sudo setenforce 0）来测试是否是其引起的问题，但请注意安全风险。

步骤 6：特殊情况和高级排查

1. SELinux/AppArmor 阻碍：

   • 如果您的系统启用了 SELinux 或 AppArmor，并且配置不当，它们可能会阻止 Nginx 连接到上游服务器的 Unix socket 或 TCP 端口。
   • SELinux：查看 /var/log/audit/audit.log 文件，搜索 denied 关键字。可以尝试临时禁用 sudo setenforce 0 进行测试。如果问题解决，则需要创建适当的 SELinux 策略。
   • AppArmor：查看 /var/log/syslog 或 dmesg。

2. 内核参数调优：

   • 对于高并发场景，系统默认的 TCP/IP 堆栈参数可能不足，例如 net.core.somaxconn (监听队列的最大长度)。如果此值过低，在高并发下可能会导致连接被拒绝。
   • 修改 /etc/sysctl.conf 并执行 sudo sysctl -p 使其生效。

3. 反向代理链问题：

   • 如果您的架构中存在多层代理（例如：CDN -> Nginx -> 应用服务器），那么 502 错误可能发生在任何一个环节。排查时应从最外层向内层逐级检查。

4. 上游服务启动脚本问题：

   • 确保您的应用服务启动脚本（例如 systemd 单元文件）是正确的，并且服务在启动后确实在监听期望的地址。

5. DDos 攻击或异常流量：

   • 大量的无效请求或攻击流量可能会迅速耗尽服务器资源，导致正常请求无法被处理，从而引发 502。
   • 检查 Nginx 访问日志 (/var/log/nginx/access.log)，查看是否有异常大量的请求来自特定 IP 或请求特定路径。

四、常见应用程序特定问题与解决方案

虽然上述步骤是通用的，但针对不同的上游应用，可能存在一些特定的常见问题。

1. PHP-FPM

• pm.max_children 过低：导致进程池耗尽。调高此值并增加服务器内存。
• request_terminate_timeout 过低或 max_execution_time (php.ini) 过低：PHP 脚本在执行完毕前被终止。增加这些值。
• memory_limit (php.ini) 过低：PHP 脚本因内存不足而崩溃。增加此值。
• 慢日志 (request_slowlog_timeout)：开启慢日志有助于找出执行缓慢的 PHP 脚本。
  • 在 www.conf 中设置：request_slowlog_timeout = 5s 和 slowlog = /var/log/php-fpm/www-slow.log。
• 错误日志未开启：确保 php_admin_value[error_log] 和 catch_workers_output 配置正确，以便捕获错误信息。

2. Python (Gunicorn/uWSGI)

• Worker 进程数不足：类似 PHP-FPM 的 pm.max_children。增加 workers 参数。
• Worker 超时：Gunicorn/uWSGI 自身的 timeout 参数。如果应用程序处理请求时间过长，worker 会被杀死。
• 内存泄漏：Python 应用本身的内存泄漏可能导致 worker 进程因内存耗尽而崩溃。
• listen 地址不匹配：Nginx 的 proxy_pass 需与 Gunicorn/uWSGI 的 bind 地址匹配。

3. Node.js

• 进程崩溃：Node.js 应用抛出未捕获的异常可能导致整个进程崩溃。使用 pm2 或 forever 等进程管理器来守护 Node.js 进程。
• 监听端口错误：确保 Node.js 应用监听的端口与 Nginx proxy_pass 中的端口一致。
• 阻塞 I/O 或 CPU 密集型任务：Node.js 是单线程的，长时间的阻塞操作会导致整个应用无法响应。考虑使用 worker_threads 或将计算密集型任务移至队列/其他服务。

4. Java (Tomcat/Jetty)

• 连接池耗尽：数据库连接池或线程池配置不当。
• 内存泄漏或 OOM：Java 应用程序的内存泄漏或堆空间不足。
• JSP/Servlet 错误：应用程序内部的异常。
• JVM 配置：Xmx (最大堆内存) 等参数设置不当。

五、预防措施

与其在 502 错误发生后才手忙脚乱地排查，不如采取积极的预防措施：

1. 完善监控体系：

   • 系统资源监控：CPU、内存、磁盘 I/O、网络流量。使用 Prometheus + Grafana、Zabbix、Nagios 等工具。
   • Nginx 监控：错误日志量、请求处理时间、连接数、活动连接数。
   • 应用服务监控：PHP-FPM 进程状态、Gunicorn/uWSGI worker 状态、应用日志中的错误数量。
   • 自定义报警：当特定错误日志出现或资源使用量超过阈值时，及时通知。

2. 合理规划资源：根据业务需求和预期的流量，为服务器和应用程序分配足够的 CPU、内存和磁盘空间。定期审查和调整。

3. 优化应用程序和数据库：

   • 代码优化：减少资源消耗、提高执行效率。
   • 数据库优化：索引、慢查询优化、连接池管理。
   • 缓存：使用 Redis、Memcached 等缓存系统减轻后端压力。

4. 配置最佳实践：

   • Nginx 和上游服务超时设置：合理配置 proxy_read_timeout、fastcgi_read_timeout 和应用程序内部的超时设置，使其相互协调。
   • 进程池设置：根据实际资源和负载调整 PHP-FPM 的 pm.max_children 或 Gunicorn 的 workers。
   • 错误日志级别：将 Nginx 错误日志级别设置为 error 或 warn 以记录重要信息，但避免 debug 级别产生过多的日志。

5. 定期更新和维护：

   • 及时更新 Nginx、PHP-FPM、Python 运行时、Node.js 运行时等组件，修复已知漏洞和 bug。
   • 定期清理旧日志文件，防止磁盘空间耗尽。

6. 使用负载均衡和高可用：

   • 将请求分发到多个后端服务器，提高服务的可伸缩性和容错性。
   • 通过冗余消除单点故障。

7. 自定义 502 错误页面：

   • 即使发生 502 错误，也可以向用户显示一个友好的、带有品牌信息的错误页面，而不是默认的 Nginx 错误页面。
   • 在 Nginx 配置中添加 error_page 502 /502.html;。

总结

Nginx 502 Bad Gateway 故障通常指向后端应用服务器的问题，或是 Nginx 与后端应用服务器之间的通信障碍。解决这类问题需要沉着冷静，遵循系统性的排查流程：

1. 从 Nginx 错误日志开始，它是最重要的线索。
2. 检查上游服务状态和日志，确定后端是否运行正常或存在内部错误。
3. 核对 Nginx 和上游服务的配置，确保它们互相匹配且无误。
4. 检查系统资源使用情况，防止资源耗尽导致服务崩溃。
5. 验证网络连通性和防火墙规则，确保通信路径畅通。
6. 考虑一些高级因素如 SELinux 或内核参数。

通过以上步骤，您应该能够有效地定位并解决绝大多数 Nginx 502 Bad Gateway 故障。同时，实施完善的监控和预防措施，是确保 Web 服务稳定运行的关键。希望这份完整指南能帮助您更好地应对和管理您的 Nginx 环境。