PHP-FPM在Ubuntu上的错误排查技巧

PHP-FPM 在 Ubuntu 上的错误排查技巧

一 快速定位与基础检查

• 确认服务状态与进程：使用命令查看 PHP-FPM 是否运行、是否崩溃或反复重启，例如：sudo systemctl status php7.4-fpm；如未运行，尝试 sudo systemctl start php7.4-fpm。用 pgrep php7.4-fpm 检查是否存在 worker 进程。
• 核对监听地址与端口/套接字：若为 TCP 监听，用 ss -lntp | grep php 或 netstat -plnt | grep php 确认端口占用；若为 Unix 套接字，检查文件是否存在与权限：ls -l /var/run/php/php7.4-fpm.sock。
• 查看主进程日志：第一时间阅读 PHP-FPM 日志（路径因版本与发行版不同，常见为 /var/log/php7.4-fpm.log 或 /var/log/php-fpm.log / error.log），用 sudo tail -f /var/log/php7.4-fpm.log 实时跟踪。
• 配置语法与目录：检查配置语法 sudo php-fpm7.4 -t；主配置通常在 /etc/php/7.4/fpm/php-fpm.conf，池配置在 /etc/php/7.4/fpm/pool.d/www.conf。
• 变更后重启并观察：sudo systemctl restart php7.4-fpm，再次查看状态与日志确认恢复。

二 日志与常见错误模式

• 定位日志文件与级别：PHP-FPM 错误日志常见路径为 /var/log/php-fpm/error.log 或 /var/log/php7.x-fpm.log；也可在 pool.d/www.conf 中通过 php_admin_value[error_log] 自定义路径，用 php_admin_flag[log_errors] on 开启日志，catch_workers_output yes 捕获脚本输出。
• 分析要点：优先查找带时间戳的 ERROR/ALERT 行，关注 listen（地址/权限）、user/group（运行身份）、pm.max_children（进程耗尽）、以及文件/目录 权限 报错。
• 慢日志定位性能瓶颈：在 www.conf 启用 slowlog = /var/log/php-fpm/slow.log 与 request_slowlog_timeout = 5s，用 sudo tail -f /var/log/php-fpm/slow.log 找出耗时函数与文件。
• Web 服务器错误日志：同时查看 Nginx 或 Apache 的错误日志（如 /var/log/nginx/error.log 或 /var/log/apache2/error.log），许多 FastCGI 转发失败会在这里体现。
• 运行时错误定位：若 PHP 错误日志 单独配置（如 /var/log/php_errors.log 或 php.ini 的 error_log），用 tail -f 与 grep 检索 Fatal/Parse/Notice 等关键字。

三 与 Web 服务器集成的关键检查

• 核对 FastCGI 转发地址：确保与 PHP-FPM 的 listen 一致。
  • Nginx 常见：fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; 或 fastcgi_pass 127.0.0.1:9000;。
  • Apache 常见：ProxyPassMatch ^/(.*\.php)$ fcgi://127.0.0.1:9000/var/www/html/$1。
• 权限与属主：若使用 Unix 套接字，确保 listen.owner / listen.group 与 Nginx/Apache 运行用户一致（常见为 www-data），目录与文件权限建议 755/644，代码目录属主可设为 www-data:www-data。
• 重载服务：修改 Nginx/Apache 或 PHP-FPM 配置后，分别执行 sudo systemctl reload nginx/apache2 与 sudo systemctl restart php7.4-fpm。

四 高频场景与修复动作

• 服务无法启动：执行 sudo systemctl status php7.4-fpm 查看原因；用 sudo php-fpm7.4 -t 检查语法；查看 PHP-FPM 日志 与 系统日志（journalctl -u php7.4-fpm -xe）定位配置/权限/资源问题；修复后 sudo systemctl restart php7.4-fpm。
• 端口或套接字冲突：若配置为 TCP 端口，用 ss -lntp | grep <port> 检查占用并释放或更换端口；若为 Unix 套接字，确认路径、权限与属主正确，必要时删除陈旧套接字文件后重启。
• 权限被拒绝：核对 listen.owner/listen.group、应用目录属主与权限；必要时执行 sudo chown -R www-data:www-data /var/www/html 与 sudo chmod -R 755 /var/www/html。
• 进程耗尽或 502/504：在 www.conf 调整 pm.max_children / pm.start_servers / pm.min_spare_servers / pm.max_spare_servers；开启 慢日志 找出慢脚本；检查后端服务（如数据库）是否可达与响应缓慢。
• 资源不足：用 free -m、df -h 检查 内存/磁盘，避免因 OOM 或磁盘写满导致 PHP-FPM 异常。

五 进阶调试命令与脚本

• 跟踪系统调用定位卡点：获取 PHP-FPM worker PID 后执行 sudo strace -f -ff -t -d -p <PID>，观察 accept/read/write/connect 等系统调用是否阻塞。
• 验证配置语法与包含路径：sudo php-fpm7.4 -t；按需查看 php.ini 与 pool.d/www.conf 的包含关系与生效值。
• 快速查看监听与进程：ss -lntp | grep php、pgrep php7.4-fpm、ls -l /var/run/php/php7.4-fpm.sock。
• 启用与观察状态页（可选）：在 www.conf 配置 pm.status_path = /status，并通过 Nginx/Apache 对该路径做访问控制后访问，观察 pool、processes、queue 等关键指标。