Ubuntu 上 PHP-FPM 故障排查清单
遇到 PHP-FPM 罢工，网站报 502 或 504？别慌，这就像服务器在“闹脾气”。按照下面这份清单，从基础到进阶，一步步把它“哄”好。记住，排查的核心思路永远是：先确认服务活着，再检查沟通渠道，最后分析内部问题。
一 快速定位服务与连通性
第一步，也是最直接的：确认 PHP-FPM 这个“工人”是否在岗，以及它是否在正确的位置待命。
- 确认服务状态与版本：先看看服务是不是真的跑起来了。记得把命令里的版本号（如 8.1）换成你实际使用的版本（7.4、8.2 等）。
- 查看状态：
sudo systemctl status php8.1-fpm。如果看到“active (running)”，恭喜，服务在跑。如果是“inactive”或“failed”，那就得往下看了。 - 启动/重启：
sudo systemctl restart php8.1-fpm。重启是解决很多“玄学”问题的第一选择。 - 开机自启：
sudo systemctl enable php8.1-fpm，确保服务器重启后它能自动回来上班。
- 查看状态：
- 检查进程与监听：服务状态正常，不代表它真的在“听”。
- 进程是否存在：
pgrep php-fpm，有数字 PID 返回就说明进程在。 - 监听端口或套接字：
ss -plnt | grep php或netstat -plnt | grep php。这能告诉你 PHP-FPM 是在监听一个网络端口（如 9000），还是一个 Unix 套接字文件。 - 套接字文件是否存在：如果配置用的是套接字，用
ls -l /run/php/php8.1-fpm.sock检查这个“通信管道”文件是否被创建了。
- 进程是否存在：
- 如果上面都显示服务不存在，那很可能是没安装或者被误删了。直接安装对应版本：
sudo apt-get install php8.1-fpm。 - 走完这一步，你就能快速判断 PHP-FPM 是“死是活”，有没有在“正确的位置”待命，以及是不是压根儿就没装。
二 配置与权限核对
服务活着，但 Nginx 和 PHP-FPM 可能“对不上暗号”。这往往是 502 错误的根源。你需要确保两边的“接头”配置一模一样。
- 核对 PHP-FPM 池配置：编辑
/etc/php/8.1/fpm/pool.d/www.conf（路径可能因版本而异）。- 确认监听地址：找到
listen这一行。它要么是 TCP 端口（如listen = 127.0.0.1:9000），要么是 Unix 套接字路径（如listen = /run/php/php8.1-fpm.sock）。记下这个值，必须和 Nginx 配置里的一致。 - 套接字权限：如果用的是 Unix 套接字，权限是关键。确保以下三行设置正确，通常要和 Nginx 的工作进程用户（常见是 www-data）保持一致：
listen.owner = www-datalisten.group = www-datalisten.mode = 0660（这个权限设置很关键，决定了 Nginx 能否读写这个套接字文件）
- 确认监听地址：找到
- 核对 Web 服务器转发配置：以 Nginx 为例，找到你的站点配置文件。
- Nginx 示例：在 location ~ \.php$ 段里，找到
fastcgi_pass指令。- 如果 PHP-FPM 用 TCP：
fastcgi_pass 127.0.0.1:9000; - 如果 PHP-FPM 用套接字：
fastcgi_pass unix:/run/php/php8.1-fpm.sock;
listen设置完全对应！ - 如果 PHP-FPM 用 TCP：
- 修改后，先做语法检查：
sudo nginx -t，确认无误后再优雅重载配置：sudo systemctl reload nginx。
- Nginx 示例：在 location ~ \.php$ 段里，找到
- 重要：任何配置修改后，别忘了重启 PHP-FPM 让配置生效：
sudo systemctl restart php8.1-fpm。 - 可以说，绝大部分的 502/504 错误，都逃不开监听地址不匹配、套接字文件权限错误或者进程根本没启动这几个原因。仔细核对这一步，能解决大部分问题。
三 日志分析与慢查询定位
如果配置都对，但问题依旧，那么日志就是你的“破案指南”。它会告诉你到底哪里出了岔子。
- 查看 PHP-FPM 日志：首先找到日志文件在哪（不同系统或安装方式路径可能不同）。
- 常见路径：
/var/log/php8.1-fpm.log、/var/log/php-fpm.log、/var/log/php-fpm/error.log。 - 实时查看：
sudo tail -f /var/log/php8.1-fpm.log，然后尝试访问网站，观察实时输出的错误信息。
- 常见路径：
- 查看 Web 服务器错误日志：以 Nginx 为例，
sudo tail -f /var/log/nginx/error.log。这里面的信息往往更直接。- 典型线索：
- 出现
connect() failed (111: Connection refused)→ 这基本指向 PHP-FPM 没运行，或者监听的端口不对。 - 出现
No such file or directory→ 这通常意味着 Nginx 配置的 Unix 套接字路径根本不存在。
- 出现
- 典型线索：
- 开启与查看慢日志：针对 504 超时错误，慢日志是定位性能瓶颈的神器。
- 在
www.conf中启用：slowlog = /var/log/php-fpm/slow.log（指定慢日志路径）request_slowlog_timeout = 5s（定义“慢”的阈值，比如超过5秒的请求就记录）
- 启用并重启服务后，通过
sudo tail -f /var/log/php-fpm/slow.log分析是哪个脚本执行过慢。
- 在
- 调整日志级别与输出：如果默认日志信息不够，可以在
www.conf的池配置里调整：php_admin_flag[log_errors] = onphp_admin_value[error_log] = /var/log/php-fpm/custom_error.log- 修改后同样需要重启 PHP-FPM。
- 日志不会说谎。配置解析失败、权限拒绝、连接被拒、脚本执行超时……这些问题的根因，往往都能在日志里找到直白的描述。
四 常见故障场景与修复要点
结合前面的检查，我们可以对几种典型故障做个快速归因和修复。
- 服务无法启动或启动后立即退出
- 诊断：使用
systemctl status php8.1-fpm看简要状态，再用journalctl -xe查看详细的系统日志。 - 常见原因：池配置文件缺失（报错“No pool defined”）、配置文件有语法错误、关键目录权限不对。
- 修复：确保
/etc/php/8.1/fpm/pool.d/目录下存在有效的 .conf 文件（如默认的 www.conf）。用php-fpm8.1 -t测试配置语法，修正后重启。
- 诊断：使用
- 502 Bad Gateway
- 快速判定：Nginx 本身能访问（静态文件可能正常），但一旦需要 PHP 处理，就报 502。这说明 Nginx 到 PHP-FPM 的“转发”链路断了。
- 处理：严格核对第二部分“配置与权限核对”的所有项目。重点检查套接字文件的权限是否为 0660，属主是否为 www-data。同时结合 PHP-FPM 和 Nginx 的错误日志交叉分析。
- 504 Gateway Timeout
- 含义：PHP-FPM 进程还在，但处理请求超时了。Nginx 等不及了。
- 处理：立即开启并分析慢日志（见第三部分），定位具体是哪个脚本或函数耗时。适当调大
request_terminate_timeout（PHP-FPM 的全局超时设置）或 Nginx 的fastcgi_read_timeout。同时检查 PHP 脚本依赖的数据库、Redis、外部 API 等服务是否响应缓慢。
- 进程耗尽或频繁崩溃
- 现象：网站在访问高峰期频繁出现 502/504，查看 PHP-FPM 日志可能有进程“exited on signal”之类的记录。
- 处理：这通常是资源规划问题。需要编辑
www.conf，调整进程管理参数：pm.max_children：最大子进程数。这是上限，设置过高会耗尽内存。pm.start_servers：启动时的子进程数。pm.min_spare_servers/pm.max_spare_servers：空闲进程的最小和最大数量。
五 进阶诊断命令
对于一些更隐蔽、更棘手的问题，下面这些命令能帮你深入系统层面进行诊断。
- 跟踪系统调用：
sudo strace -f -ff -t -d -p。这个命令可以跟踪 PHP-FPM 进程的所有系统调用，对于诊断启动失败、文件权限问题、运行时阻塞等有奇效。 - 查看监听情况：再次确认监听状态，
ss -plnt | grep php或netstat -plnt | grep php。 - 检查套接字与权限：
ls -l /run/php/php8.1-fpm.sock，确保文件存在且权限正确。 - 检查安全模块拦截：如果系统启用了 AppArmor 或 SELinux，它们可能会阻止 PHP-FPM 的某些操作。可以尝试查看安全日志：
dmesg | grep apparmor或查看对应的审计日志。 - 动态查看服务日志：
journalctl -u php8.1-fpm -f，这是一个集中、动态查看服务相关日志的好方法。 - 这些进阶命令，就像给你的排查工具箱里添上了“显微镜”和“听诊器”，适用于定位那些难以复现的启动失败、权限拒绝、连接异常与运行时阻塞问题。
