排查 502 / 504:从 nginx 到后端的三层定位
502 与 504 的区别、五个高频原因、逐层排查命令,以及临时与根治两套方案。
502 和 504 是运维最常遇到的错误,但原因完全不同:502 是「后端没响应或响应非法」,504 是「后端超时」。
先分清
| 状态码 | 含义 | 典型原因 |
|---|---|---|
| 502 Bad Gateway | 上游无响应/连接被拒 | php-fpm 没起、socket 路径错、进程打满 |
| 504 Gateway Timeout | 上游超时 | 慢查询、外部 API 阻塞、大文件处理 |
五层定位法
第 1 层:看错误日志
tail -100 /www/wwwlogs/example.com.error.log
关键词:
connect() to unix:/tmp/php-cgi-74.sock failed→ socket 不存在或权限不对upstream timed out→ 504,后端太慢no live upstreams→ 后端全部不可用SSL_do_handshake() failed→ 反代到 HTTPS 上游的证书问题
第 2 层:确认后端进程
ps aux | grep php-fpm | head
systemctl status php-fpm
ss -lntp | grep 9000
php-fpm 没起,最常见的原因是配置语法错误或端口/socket 冲突。
第 3 层:确认监听方式一致
nginx 配的是 unix:/tmp/php-cgi-74.sock,php-fpm 却在监听 127.0.0.1:9000,必然 502。两边必须一致。
第 4 层:权限
nginx worker 用户(通常 www)需要对 socket 有读写权限。改了 listen.owner 没重启 php-fpm,权限不生效。
第 5 层:资源
free -m
df -h
dmesg | tail -20 # 看是否 OOM
内存打满时内核会杀进程,php-fpm 被杀后 nginx 就 502。
502 的五个高频原因
- php-fpm 进程池打满(
pm.max_children太小,请求排队后被拒) - socket 路径或端口不匹配
- PHP 脚本 fatal error 导致 worker 异常退出
open_basedir限制导致文件读取失败- 磁盘满,无法写临时文件
504 的四个高频原因
- 数据库慢查询(没索引、全表扫描)
- 外部 API 无超时,一直等
- 大文件上传/导出,超过
fastcgi_read_timeout - 反代后端处理时间超过
proxy_read_timeout
临时与根治
临时:调大超时,先恢复访问。
fastcgi_read_timeout 120s;
proxy_read_timeout 120s;
根治:找出为什么慢。开慢查询日志:
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;
调大超时只是把错误推迟。如果 504 出现在每分钟固定时刻,八成是定时任务在跑重查询。
预防
- php-fpm 进程池按内存算:
pm.max_children = 可用内存 / 单进程内存 - 所有外部请求设超时(curl 的
CURLOPT_TIMEOUT) - 监控 502/504 的比例,超过 0.5% 就告警
- 静态资源不经过 PHP,nginx 直接服务
相关:日志分析。