Debian 上 PHP 超时的定位与解决
先排个雷：在 Debian 上遇到 PHP 超时，别急着往代码里加 set_time_limit()，得先搞清楚到底是谁截断了请求。不同运行模式、不同层级的超时策略，背后各有各的规矩，搞混了可能折腾半天都无效。
一、先快速定位一下超时到底从哪来的
- 先看 PHP 层有没有限制。在 Web 环境里临时输出一下 ini_get('max_execution_time')，默认常见值是 30 秒。CLI 模式则通常是 0，没有限制。
- 确认运行模式：是 mod_php（Apache）、PHP-FPM + Nginx，还是直接跑 CLI？不同模式超时的触发点完全不同。
- 再检查网关层：如果是 PHP-FPM，得看 request_terminate_timeout 的值；Nginx 那边要看 fastcgi_read_timeout；Apache 则关注 Timeout 指令。
- 这里有个容易被忽略的细节：max_execution_time 和 set_time_limit() 只统计脚本自身的执行时间，系统调用、流操作、数据库查询这些是不算进去的。所以哪怕 PHP 层没超时，网关层也可能提前把你断了。
二、按运行模式调整配置
- 通用 PHP 层（php.ini 或代码里动态设置）
调整 PHP 本身的执行时间限制，有两个途径：一是直接修改 php.ini，把 max_execution_time = 30 改成更大的值，比如 300 秒，或者设为 0（不推荐生产环境）；二是用代码动态设置，在脚本开头调用 set_time_limit(300) 或者 ini_set('max_execution_time', 300)。每次调用 set_time_limit() 都会重置计时器，这个细节用起来很方便。修改 php.ini 后需要重启 Apache/Nginx/PHP-FPM，CLI 则不需要重启。 - PHP-FPM + Nginx
这个组合里，FPM 和 Nginx 各管各的超时。FPM 层在 php-fpm.conf 或 pool.d/www.conf 里设置 request_terminate_timeout = 300，单位支持秒、分、小时、天，0 表示关闭。Nginx 层则在 server 或 location ~ .php$ 里设置 fastcgi_read_timeout 300s;。一个操作建议：让 max_execution_time ≤ request_terminate_timeout，这样 PHP 层结束后 FPM 不会空等。 - Apache（mod_php）
调整 Timeout 300 或更大值，同时确保 max_execution_time 与之匹配。两个参数最好保持一致，否则容易出奇怪的问题。 - CLI
默认没有执行时间限制。如果需要限制，可以在脚本里用 set_time_limit(180)，或者在命令行动态指定：php -d max_execution_time=180 script.php。
三、常见场景与推荐配置
| 场景 | 需要调整的指令 | 建议值/做法 |
|---|---|---|
| 普通 Web 接口 | max_execution_time；Nginx fastcgi_read_timeout | 接口应在 1–2 分钟内完成；必要时将两者调至 120–300s |
| 大文件导入/导出、耗时任务 | max_execution_time；request_terminate_timeout；fastcgi_read_timeout | 建议 300–600s；更优方案是改为异步任务 |
| 后台计划任务 | CLI 无需设置；如需限制可用 set_time_limit | 直接 CLI 执行，避免 Web 超时 |
| 实时流式或大响应 | max_execution_time；request_terminate_timeout | 适当增大；若仍受限，考虑分块输出或异步处理 |
- 重要提示：正常接口响应时间不应超过 1–2 分钟。如果任务确实需要更久，优先考虑异步处理+队列+回调，而不是一味提高超时阈值。
四、稳妥的长期方案与最佳实践
- 异步化长任务：把耗时操作丢进队列里，比如用 Beanstalkd、RabbitMQ 或 Redis Queue，让 Worker 后台慢慢处理。Web 端只管提交任务和拿到任务 ID，后续靠轮询或回调来获取结果。这样 Web 请求就可以快速返回，不会被拖住。
- 任务拆分与断点续传：把大任务拆成小批次，每个批次完成后记录进度。这样即使失败，也可以从断点继续，而不是重新来过。
- 优化代码与资源：用缓存、优化算法和 SQL、减少阻塞 I/O，从根源上降低执行时间。很多时候，超时只是表象，真正的问题是代码效率太低。
- 超时兜底：为外部调用设置连接超时和读取超时。比如 cURL 的 CURLOPT_CONNECTTIMEOUT 和 CURLOPT_TIMEOUT，避免被第三方拖垮。
- 监控与告警：记录执行时长、失败率和超时分布情况。设置熔断和限流，防止一个慢请求引发雪崩效应。
五、安全与风险提示
- 把 max_execution_time 或 request_terminate_timeout 设为 0（无限制），存在资源耗尽和服务稳定性风险。生产环境一定要谨慎评估，优先采用异步方案。
- 调整 Nginx/Apache/FPM 超时之后，务必进行压测和监控，确认不会引发级联超时或进程堆积。有时候一个参数调大了，反而会掩盖更深层的问题。
