Ubuntu 上 PHP-FPM 错误日志分析与排查
一 定位日志文件与快速查看
- 常见路径与命令
- PHP-FPM 主错误日志：/var/log/php-fpm.log 或 /var/log/php/{version}-fpm.log
- 进程池日志（Pool）：/var/log/php-fpm/www-error.log 或 /var/log/php-fpm/error.log
- FPM 访问日志（若有）：/var/log/php-fpm/access.log 或 www.access.log
- 系统服务日志：journalctl -u php{version}-fpm
- 快速查看与过滤
- 实时查看：sudo tail -f /var/log/php/7.4-fpm.log
- 关键字过滤：sudo grep -i “error|warning” /var/log/php/7.4-fpm.log
- 版本占位符：将 {version} 替换为你的实际版本，如 7.4、8.1、8.3。
二 配置与日志级别要点
- 主要配置位置
- FPM 全局：/etc/php/{version}/fpm/php-fpm.conf
- 进程池：/etc/php/{version}/fpm/pool.d/www.conf
- 常用参数与作用
- error_log：指定 FPM 错误日志路径
- log_level：日志级别（如 notice、warning、error），生产建议不低于 notice
- catch_workers_output：是否捕获子进程输出到 FPM 日志
- php_admin_value[error_log] / php_admin_flag[log_errors]：在 pool 内为 PHP 脚本指定错误日志与开启日志
- request_slowlog_timeout + slowlog：开启慢日志，定位耗时脚本
- 修改后务必测试并重启
- 语法检查：sudo php-fpm**{version}** -t
- 重启服务：sudo systemctl restart php**{version}**-fpm
三 常见错误模式与对应处理
- 502 Bad Gateway
- 现象：Nginx/Apache 与 PHP-FPM 通信失败
- 处置：检查服务是否运行（systemctl status）、确认 listen 地址/端口或 .sock 与 Web 配置一致、查看 FPM 与系统日志定位启动或权限问题
- 504 Gateway Timeout
- 现象：脚本执行超时或进程不足
- 处置：适当提高 request_terminate_timeout（或 PHP 的 max_execution_time）、提升 pm.max_children、优化慢查询与阻塞调用
- “Primary script unknown”
- 现象：脚本路径未正确传递
- 处置：Nginx 配置中确保 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; 且 root 路径正确
- 进程池耗尽（pm.max_children reached）
- 现象：并发超过进程上限
- 处置：依据内存与负载调优 pm.max_children / pm.start_servers / pm.min_spare_servers / pm.max_spare_servers，或优化应用
- 权限拒绝（Permission denied / EACCES）
- 现象：FPM 用户无权访问目录/文件/套接字
- 处置：核对 user/group、listen.owner/group/mode，修正目录属主与权限
- 内存耗尽（Allowed memory exhausted）
- 现象：脚本超出内存上限
- 处置：提升 memory_limit，优化代码与数据处理
- FPM 无法启动
- 现象：配置错误或端口/套接字冲突
- 处置：php-fpm -t 检查语法，排查端口占用（netstat -tulnp | grep 9000）或套接字权限/路径
四 高效排查命令清单
- 服务与系统日志
- 查看状态与最近日志：systemctl status php**{version}-fpm；journalctl -u php{version}**-fpm -n 50 --no-pager
- 配置与语法
- 测试配置：php-fpm**{version}** -t
- 资源与连通
- 端口占用：ss -lntp | grep 9000 或 netstat -tulnp | grep 9000
- 套接字检查：ls -l /run/php/php**{version}**-fpm.sock
- 日志检索与分析
- 实时跟踪：tail -f /var/log/php/{version}-fpm.log
- 错误/警告聚合：grep -Ei “error|warning” /var/log/php/{version}-fpm.log | tail -n 100
- PHP 层错误位置：grep -i “error_log” /etc/php/{version}/fpm/php.ini；或在 CLI 用 php -i | grep “Loaded Configuration File” 定位 php.ini
五 日志管理与性能优化
- 日志轮转
- 建议通过 logrotate 管理日志，示例（/etc/logrotate.d/php-fpm）：
- /var/log/php-fpm/*.log {
- daily
- missingok
- rotate 7
- compress
- delaycompress
- notifempty
- create 0644 root root
- }
- 慢日志
- 在 www.conf 中开启：request_slowlog_timeout = 5s；slowlog = /var/log/php-fpm/www-slow.log，用于定位耗时脚本与瓶颈
- 日志级别
- 生产环境建议 log_level = notice，在问题排查期可临时提升到 warning/error 以减少 I/O 干扰
