PHP-FPM在Linux中的错误处理机制

PHP-FPM 在 Linux 中的错误处理机制

一 核心机制与日志通道

• 错误日志与日志级别：在 [global] 段通过 error_log 指定主日志路径，通过 log_level（如 alert、error、warning、notice、debug）控制记录级别，便于在生产与排障间平衡。
• 进程异常自恢复：通过 emergency_restart_threshold 与 emergency_restart_interval 定义在短时间内出现 SIGSEGV/SIGBUS 等致命错误的子进程数量阈值，超过则触发“优雅重启”，降低故障扩散风险。
• 请求生命周期控制：用 request_terminate_timeout 强制终止超时请求（覆盖脚本层面的 max_execution_time 场景）；用 request_slowlog_timeout 与 slowlog 捕获执行过慢的请求并输出调用栈，定位性能瓶颈与卡点。
• 资源与系统限制：通过 rlimit_files、rlimit_core 等设置文件描述符与 core dump 上限，避免因资源耗尽导致级联失败。
• 进程模型与隔离：采用 pm=dynamic/static 管理子进程数量，支持多 pool 隔离不同站点/应用，减少相互影响。

二 配置方法与关键参数

• 主配置与进程池：主配置通常为 php-fpm.conf（含 [global] 与 include 语句），进程池配置位于 /etc/php/{version}/fpm/pool.d/*.conf（如 www.conf）。修改后先执行 php-fpm{version} -t 做语法校验，再重启服务。
• 日志与输出捕获：在 [www] 段可设置 catch_workers_output = yes 将子进程的标准输出/错误接入 FPM 日志；配合 php_admin_flag[log_errors] = on 与 php_admin_value[error_log] = /path 将脚本错误写入指定文件（php_admin_* 项不可被 ini_set 覆盖，适合生产环境）。
• 慢日志：开启 request_slowlog_timeout = 10s（按需调整）与 slowlog = /var/log/php-fpm/www-slow.log，对定位慢脚本与数据库/外部依赖瓶颈非常有效。
• 监听与权限：使用 listen = 127.0.0.1:9000 或 listen = /run/php/php{version}-fpm.sock；Unix socket 需设置 listen.owner / listen.group / listen.mode（如 0666）以确保 Nginx/Apache 与 FPM 进程可互通。
• 进程与稳定性：结合 pm.max_children / pm.start_servers / pm.min_spare_servers / pm.max_spare_servers 与 pm.max_requests（用于缓解第三方扩展内存泄漏）进行稳态调优。

三 常见错误场景与排查路径

• 启动失败：优先执行 php-fpm{version} -t 检查语法；查看 FPM 错误日志（如 /var/log/php{version}-fpm.log 或 /var/log/php-fpm.log）定位具体报错行；若提示进程已在运行或端口被占用，先 systemctl stop php{version}-fpm，必要时更换 listen 端口或 socket；修正后 systemctl start php{version}-fpm。
• 502/504 网关错误：多与 request_terminate_timeout、pm.max_children、后端响应慢或网络抖动相关；建议开启慢日志定位长耗时调用，并适当提升进程数与超时阈值，同时检查上游服务健康度。
• 脚本错误未写入：确认 catch_workers_output = yes、php_admin_flag[log_errors] = on 与 php_admin_value[error_log] 路径正确且 FPM 运行用户对日志目录具备写权限；必要时在 php.ini 中开启 log_errors = On 并配置 error_log。
• Socket 权限/路径问题：若使用 Unix socket，确保 listen.owner / group / mode 与 Nginx/Apache 运行用户匹配；socket 文件异常时可删除后 重启 FPM 重建。

四 监控与运维实践

• 运行状态与存活探测：启用 pm.status_path = /status 与 ping.path = /ping（返回 pong），结合监控系统或负载均衡器做存活与健康检查。
• 实时日志观测：使用 tail -f /var/log/php{version}-fpm.log、tail -f /var/log/php-fpm/www-slow.log 实时跟踪错误与慢请求，配合 grep/awk 做关键字告警与统计。
• 优雅变更与回滚：变更前 php-fpm{version} -t，变更中采用 reload（如 kill -USR2 ）实现无缝重载，出现异常可快速回滚配置并重启。

五 最小化可用配置示例

; /etc/php/8.1/fpm/pool.d/www.conf
[www]
listen = /run/php/php8.1-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

user = www-data
group = www-data

pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.max_requests = 1000

request_terminate_timeout = 30s
request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/www-slow.log

catch_workers_output = yes
php_admin_flag[log_errors] = on
php_admin_value[error_log] = /var/log/php-fpm/www-error.log

; 可选：状态与存活探测
pm.status_path = /status
ping.path = /ping
ping.response = pong

• 应用前执行：php-fpm8.1 -t && systemctl restart php8.1-fpm
• 注意：目录与日志文件需预先创建并对 www-data 可写，生产环境建议将 display_errors = Off。