Nginx 502/504错误排查与解决

---

502 Bad Gateway表示Nginx收到了无效的上游响应（通常是PHP-FPM崩溃），504 Gateway Timeout表示上游处理超时。这两个错误是VPS建站中最常见的故障之一。

一、快速诊断

# 查看Nginx错误日志（最关键的一步）
tail -50 /var/log/nginx/error.log

# 常见错误信息：
# 502: "connect() failed (111: Connection refused) while connecting to upstream"
# 502: "recv() failed (104: Connection reset by peer)"
# 504: "upstream timed out (110: Connection timed out)"

二、502错误排查

2.1 PHP-FPM未运行

502最常见的原因是PHP-FPM服务停止了。

# 检查PHP-FPM状态
systemctl status php8.2-fpm

# 如果停止了，启动
systemctl start php8.2-fpm

# 查看为什么停止
journalctl -u php8.2-fpm -n 50

# 检查PHP-FPM日志
tail -50 /var/log/php8.2-fpm.log

2.2 PHP-FPM Socket路径不匹配

Nginx配置中的socket路径必须和PHP-FPM配置一致：

# Nginx中的配置
fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;

# 确认socket文件存在
ls -la /var/run/php/php8.2-fpm.sock

# 确认PHP-FPM的listen配置
grep "listen = " /etc/php/8.2/fpm/pool.d/www.conf
# 应该输出: listen = /var/run/php/php8.2-fpm.sock

2.3 PHP-FPM进程耗尽

所有PHP-FPM子进程都在忙，新请求无法处理：

# 查看PHP-FPM错误日志中是否有
# "server reached pm.max_children setting"

# 增加max_children（注意内存限制）
# /etc/php/8.2/fpm/pool.d/www.conf
pm = dynamic
pm.max_children = 10          # 根据内存适当增加
pm.start_servers = 3
pm.min_spare_servers = 2
pm.max_spare_servers = 5

systemctl restart php8.2-fpm

2.4 PHP脚本致命错误

# 查看PHP错误日志
tail -50 /var/log/php8.2-fpm.log

# 如果是WordPress，查看wp-content/debug.log
# 在wp-config.php中开启调试
# define('WP_DEBUG', true);
# define('WP_DEBUG_LOG', true);
# define('WP_DEBUG_DISPLAY', false);

三、504错误排查

3.1 PHP脚本执行超时

# 增加PHP最大执行时间
# /etc/php/8.2/fpm/php.ini
max_execution_time = 300

# PHP-FPM请求超时
# /etc/php/8.2/fpm/pool.d/www.conf
request_terminate_timeout = 300

3.2 Nginx upstream超时配置

# Nginx虚拟主机配置中添加
location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;

    # 增加超时时间
    fastcgi_connect_timeout 300;
    fastcgi_send_timeout 300;
    fastcgi_read_timeout 300;
}

# 如果使用proxy_pass反代
proxy_connect_timeout 300;
proxy_send_timeout 300;
proxy_read_timeout 300;

3.3 数据库查询慢导致超时

# 检查MySQL慢查询
mysql -u root -p -e "SHOW PROCESSLIST;"

# 开启慢查询日志
# /etc/mysql/mysql.conf.d/mysqld.cnf
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 2

四、Nginx缓冲区配置

当上游响应过大时，缓冲区不足也会导致502：

# /etc/nginx/nginx.conf 或虚拟主机配置
# FastCGI缓冲区
fastcgi_buffer_size 128k;
fastcgi_buffers 4 256k;
fastcgi_busy_buffers_size 256k;
fastcgi_temp_file_write_size 256k;

# Proxy缓冲区（反向代理场景）
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;

五、内存不足导致的502

内存耗尽时OOM Killer杀死PHP-FPM或MySQL，直接导致502：

# 检查是否有OOM事件
dmesg | grep -i "oom\|killed"

# 解决方案
# 1. 配置Swap：参考内存不足排查教程
# 2. 减少PHP-FPM进程数
# 3. 限制MySQL内存使用
# 4. 升级更大内存的VPS方案

内存优化详见VPS内存不足排查教程。

六、排查流程总结

Tip： 修改配置后记得重启服务：systemctl restart nginx php8.2-fpm。更多排查教程请查看新手教程。