DevOps知识中心
DevOps知识中心

如何诊断和解决 Nginx 502 错误网关错误

遇到 Nginx 502 错误网关错误？本综合指南将引导您诊断和解决此问题。了解如何解释 Nginx 错误日志、验证上游服务器状态，以及排除常见的根本原因，如配置错误的代理设置、PHP-FPM 问题、资源耗尽和防火墙阻止。通过实用的示例和分步解决方案，您将能迅速确定根本原因并恢复您的网络服务，确保流畅运行和最少的停机时间。

49 浏览量

如何诊断和解决 Nginx 502 Bad Gateway 错误

Nginx 是一个强大且流行的 Web 服务器和反向代理，常用于提供静态内容、负载均衡流量以及将请求转发到各种上游应用服务器，如 PHP-FPM、Node.js、Python Gunicorn 或 Apache Tomcat。当 Nginx 在与其中一个上游服务器通信时遇到问题，它通常会返回一个“502 Bad Gateway”错误。

本文提供了一个全面、分步的指南，用于理解、诊断和解决 Nginx 502 Bad Gateway 错误。我们将探讨常见原因，为您提供使用命令行工具进行实用故障排除的技术，并提供可操作的解决方案，以使您的 Web 服务快速恢复联机。无论您是系统管理员、开发人员，还是管理自己的服务器，本指南都将帮助您有效解决最常见的 Nginx 错误之一。

理解 Nginx 502 Bad Gateway 错误

A 502 Bad Gateway 错误表明 Nginx（作为反向代理）从上游服务器接收到了无效的响应。这意味着 Nginx 成功连接到了上游服务器，但收到了无响应、不完整的响应，或者它无法理解的响应。关键在于，问题不在于 Nginx 本身，而在于 Nginx 试图通信的服务。

常见的上游服务器包括：

  • PHP-FPM：用于 PHP 应用程序（例如 WordPress、Laravel）。
  • Gunicorn/uWSGI：用于 Python 应用程序（例如 Django、Flask）。
  • Node.js：用于 JavaScript 应用程序。
  • Apache Tomcat：用于 Java 应用程序。
  • 其他 Web 服务器：例如提供特定内容的 Apache HTTP Server。

The 502 错误是您的应用程序后端未正确运行或 Nginx 无法访问它的一个关键指标。

分步诊断

解决 502 错误的诀窍在于系统化的诊断。从最可能的原因开始，逐步深入调查。

1. 首先检查 Nginx 错误日志

您的 Nginx 错误日志是信息的主要来源。它们通常包含有关 Nginx 为什么无法与上游服务器通信的具体详细信息。

  • 位置：通常位于 /var/log/nginx/error.log。
  • 命令：使用 tail -f 在尝试重现错误时实时监控日志。
tail -f /var/log/nginx/error.log

要查找的内容：
* connect() failed (111: Connection refused)：表示上游服务器未在指定的地址/端口上侦听，或者防火墙正在阻止连接。
* upstream timed out：上游服务器响应时间过长。
* upstream prematurely closed connection：上游服务器在发送完整响应之前关闭了连接。
* no live upstreams while connecting to upstream：Nginx 找不到任何已配置的可用上游服务器。

2. 验证上游服务器状态

从 Nginx 错误日志中获得线索后，检查您的上游应用程序服务器的状态。

  • 对于 PHP-FPM：

    bash systemctl status phpX.X-fpm # 将 X.X 替换为您的 PHP 版本，例如 php7.4-fpm sudo service phpX.X-fpm status

  • 对于 Node.js/Python/其他自定义应用：
    检查进程是否正在运行。

    bash ps aux | grep node ps aux | grep gunicorn
    如果使用像 PM2 (Node.js) 或 Supervisor (通用) 这样的进程管理器，请检查其状态。

    bash pm2 status sudo supervisorctl status

如果服务未运行，请尝试启动它并检查其自身的日志以查找错误。

systemctl start phpX.X-fpm
# 或者
sudo service phpX.X-fpm start

3. 检查到上游的网络连通性

确保 Nginx 能够通过配置的端口或套接字路径到达上游服务器。

  • 对于 TCP/IP 连接（例如 127.0.0.1:8000）：
    使用 telnet 或 nc (netcat) 从 Nginx 服务器测试端口连通性。

    bash telnet 127.0.0.1 8000 nc -vz 127.0.0.1 8000
    成功的连接应显示 Connected to 127.0.0.1. 或 succeeded!。如果它挂起或显示 Connection refused，则上游服务未侦听或防火墙正在阻止它。

  • 对于 Unix 套接字（例如 unix:/run/php/phpX.X-fpm.sock）：
    验证套接字文件是否存在且具有正确的权限。

    bash ls -l /run/php/phpX.X-fpm.sock
    Nginx 应具有对该套接字文件的读/写权限。Nginx 用户（例如 www-data）需要是拥有该套接字的组的一部分（例如 www-data 或 php-fpm）。

常见原因和解决方案

根据您的诊断步骤，以下是 502 错误的常见原因以及如何解决它们。

1. 上游服务器未运行或崩溃

原因： Nginx 试图代理到的应用程序（例如 PHP-FPM、Gunicorn、Node.js 应用）未运行或已崩溃。

解决方案：启动或重启上游服务。

# PHP-FPM 示例
systemctl start phpX.X-fpm
# 如果它已经在运行，并且您怀疑它已崩溃，请重启它：
systemctl restart phpX.X-fpm

# 对于自定义应用程序，请使用其特定的启动/重启命令

提示：确保您的上游服务配置为在系统启动时自动启动。对于 systemd 服务，请使用 systemctl enable phpX.X-fpm。

2. 上游服务器过载/资源耗尽

原因：上游服务器不堪重负，内存、CPU 耗尽，或达到进程限制，导致其停止响应或拒绝新连接。

症状：Nginx 错误日志可能会间歇性地显示 connection refused 或 upstream timed out，尤其是在负载下。系统监控工具 (top, htop, free -h) 显示高资源使用率。

解决方案：

  • 对于 PHP-FPM：调整其配置文件（例如 /etc/php/X.X/fpm/pool.d/www.conf）中的 PHP-FPM 池设置。

    • pm.max_children：可以同时存在的最大子进程数。
    • pm.start_servers：启动时创建的子进程数。
    • pm.min_spare_servers, pm.max_spare_servers：控制保留多少空闲子进程。

    ini ; 动态进程管理示例 pm = dynamic pm.max_children = 50 pm.start_servers = 10 pm.min_spare_servers = 5 pm.max_spare_servers = 20
    * 如果脚本耗尽内存，请增加 php.ini 中的 memory_limit。
    * 对于其他应用程序：增加工作进程、线程的数量，或在可能的情况下分配更多内存。监控应用程序的具体指标。
    * Nginx 超时：在 Nginx 配置中增加 proxy_connect_timeout、proxy_send_timeout 和 proxy_read_timeout 指令，但请注意，如果后端确实遇到困难，这只会延迟错误。

    nginx http { ... proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; ... }

3. Nginx 中上游配置不正确

原因：Nginx 配置为连接到错误的上游服务器 IP 地址、端口或 Unix 套接字路径。

症状：请求后，Nginx 错误日志立即显示 connect() failed (111: Connection refused)。

解决方案：仔细检查您的 Nginx server 块配置（/etc/nginx/sites-available/your_site.conf）。

  • 对于 HTTP/HTTPS 上游：

    nginx location /app { proxy_pass http://127.0.0.1:8000; # 确保 IP 和端口正确 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }

  • 对于通过 Unix 套接字的 PHP-FPM：

    nginx location ~ \.php$ { fastcgi_pass unix:/run/php/phpX.X-fpm.sock; # 验证此路径与 PHP-FPM 配置完全匹配 fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; }

  • 对于通过 TCP/IP 的 PHP-FPM：

    nginx location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; # 验证 IP 和端口 fastcgi_index index.php; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; }

进行更改后，请始终测试您的 Nginx 配置并重新加载/重启 Nginx：

nginx -t
systemctl reload nginx # 如果 -t 显示需要，则重启

4. PHP-FPM request_terminate_timeout 超时

原因：PHP 脚本的执行时间超过了 PHP-FPM 中 request_terminate_timeout 的设置。Nginx 等待响应，但 PHP-FPM 终止了脚本，导致 Nginx 接收到不完整的响应。

症状：Nginx 错误日志可能会显示 upstream timed out 或 script timed out。PHP-FPM 日志可能会显示 child XX exited on signal 9 (SIGKILL)。

解决方案：
* 增加 request_terminate_timeout：在您的 PHP-FPM 池配置（www.conf）中，找到并调整此指令。将其设置为 0 会禁用超时，但这通常不被推荐，因为长时间运行的脚本可能会占用资源。

```ini
request_terminate_timeout = 300 # 增加到 5 分钟 (300 秒)
```

  • 在 Nginx 中增加 fastcgi_read_timeout：此 Nginx 超时应等于或大于 request_terminate_timeout。

    nginx location ~ \.php$ { ... fastcgi_read_timeout 300s; # 必须 >= PHP-FPM 的 request_terminate_timeout ... }

警告：虽然增加超时可以解决 502 错误，但它可能会掩盖潜在的性能问题。最长期的解决方案是优化缓慢的 PHP 脚本。

5. 防火墙问题

原因：防火墙（无论是 Nginx 服务器上还是上游服务器上，如果它们是分开的）正在阻止到上游端口或套接字的连接。

解决方案：
* 检查防火墙状态：

```bash
sudo ufw status # 对于 UFW (Ubuntu/Debian)
sudo firewall-cmd --list-all # 对于 firewalld (CentOS/RHEL)
sudo iptables -L # 对于 iptables
```

  • 打开必要的端口：确保 Nginx 用于连接到上游的端口（例如，TCP/IP 上的 PHP-FPM 的 9000）已打开。

    bash sudo ufw allow from 127.0.0.1 to any port 9000 # 允许 localhost 连接到 9000 sudo firewall-cmd --permanent --add-port=9000/tcp # 对于 firewalld sudo firewall-cmd --reload
    * 为了测试目的，仅在受控环境中暂时禁用防火墙，然后重新启用并正确配置它。

6. SELinux 或 AppArmor 的干扰

原因：安全增强功能，如 SELinux (在 RHEL/CentOS 上) 或 AppArmor (在 Ubuntu/Debian 上)，可能会阻止 Nginx 访问上游套接字或建立网络连接，即使文件权限和防火墙配置正确。

症状：日志可能会显示 permission denied 或类似消息，尤其是在 /var/log/audit/audit.log 中 (对于 SELinux)。

解决方案：
* 检查 audit.log：

```bash
sudo grep nginx /var/log/audit/audit.log
```
  • 暂时将 SELinux 设置为宽容模式：sudo setenforce 0。如果错误解决，则 SELinux 是罪魁祸首。然后您需要生成并应用适当的 SELinux 策略（例如 audit2allow）。请记住将其设置回强制模式（sudo setenforce 1）。
  • 检查 AppArmor 状态：sudo aa-status。如果 AppArmor 处于活动状态，您可能需要调整 Nginx 配置文件。

7. 大的请求/响应体 (代理缓冲)

原因：Nginx 的默认代理缓冲设置可能对于非常大的请求体或响应体来说太小，导致连接过早关闭。

症状：Nginx 错误日志可能会显示 upstream prematurely closed connection while reading response header from upstream 或 upstream prematurely closed connection while reading response body from upstream。

解决方案：在 http、server 或 location 块中调整 Nginx 代理缓冲指令。

http {
    ...
    proxy_buffer_size   128k; # 响应第一部分缓冲器的大小
    proxy_buffers   4 256k; # 剩余响应的缓冲器数量和大小
    proxy_busy_buffers_size   256k; # 忙碌缓冲器最大大小
    proxy_temp_file_write_size 256k; # 缓冲溢出时写入临时文件的大小
    ...
}

注意：这些设置会消耗更多内存。请根据服务器资源和应用程序响应的典型大小谨慎调整它们。

一般故障排除提示

  • 审阅所有相关日志：除了 Nginx 错误日志外，还要检查 Nginx 访问日志、上游应用程序日志 (PHP-FPM、Gunicorn、Node.js 应用日志) 和系统日志 (/var/log/syslog, dmesg)。
  • 重启 Nginx：在任何配置更改后，始终重启 Nginx 以确保它们生效：systemctl restart nginx。
  • 测试 Nginx 配置：在重启之前，验证 Nginx 配置的语法：nginx -t。
  • 隔离问题：尝试绕过 Nginx 并直接访问上游应用程序。例如，如果您的 Node.js 应用在 localhost:3000 上，请从服务器命令行使用 curl http://localhost:3000。如果这也失败，问题绝对出在您的应用程序，而不是 Nginx。
  • 检查磁盘空间：磁盘已满可能会阻止应用程序写入临时文件或日志，从而导致崩溃或故障。使用 df -h 检查磁盘使用情况。

结论

Nginx 502 Bad Gateway 错误很常见，但几乎总是指向 Nginx 试图连接的后端应用程序存在问题，而不是 Nginx 本身。通过系统地检查 Nginx 错误日志、验证上游服务器状态、确认网络连通性，然后解决常见的配置或资源问题，您可以有效地诊断和解决这些问题。

请记住，以有条理的方式进行故障排除，从最基本的检查开始，然后逐步深入。在进行任何更改后，请始终测试您的 Nginx 配置，并监控应用程序和服务器的运行状况，以防止将来发生。有了这些策略，您将有能力使您的服务保持顺畅运行。