Swoole中max_wait_time对平滑重启的影响

max_wait_time 这个参数，很多人第一反应是“给 Worker 一个宽限期，等它处理完手头的事再退出”。但它的真实定位其实是安全兜底阈值：一旦旧 Worker 在该时间内没自行结束，主进程会发 SIGKILL 强制终止。注意，它只在 reload_async=true 时才参与流程，而且设置时必须大于业务中最长单次请求耗时（包括下游超时），同时最好和 Nginx 的超时配置对齐。

max_wait_time 不是“等待多久就停”，而是“最多等多久才强制杀”

这里想强调一个核心区别：max_wait_time 不是“等多久就自动停止”，而是“最多等多久，等不到就强制杀”。一旦强杀，正在执行的协程、未完成的异步 I/O、未返回的 task 结果都会丢失——代价可不小。

所以设置时，这个值必须大于业务中最长单次请求耗时，否则可能打断正常请求；但也不能设得过大，否则重启卡住，影响发布节奏。

• HTTP 场景建议设为 10～30 秒，同时确保 Nginx 的 proxy_read_timeout 也匹配
• 定时任务（Crontab）或队列消费者场景，得考虑最长任务执行时间——比如一个导出任务跑 5 分钟，max_wait_time 至少得设 300
• Hyperf 项目中要特别注意：只有配置了 reload_async => true，这个参数才真的干活，否则设了也白搭，照样立即终止

不配 reload_async 时，max_wait_time 形同虚设

reload_async 是决定平滑重启机制是否启动的开关。如果它是 false（默认值），那收到 SIGUSR1 后，Swoole 会直接终止 Worker，max_wait_time 根本不参与——旧进程里所有未完成的协程、go 启动的任务、defer 注册的清理逻辑，统统丢弃。只有在 reload_async => true 下，Swoole 才会先 fork 新 Worker，再通知旧 Worker 进入“拒绝新请求 + 等待存量任务结束”状态，同时启动 max_wait_time 倒计时。

• Hyperf 的 server.php 中要显式加上：'reload_async' => true
• 原生 Swoole 在 $server->set() 时也必须包含该键
• 检查是否真的生效：重启后看看日志里有没有 worker exit gracefully 类提示，而不是简单的 worker exit

max_wait_time 和 max_request 共同决定 Worker 生命周期

max_request 控制每个 Worker 处理多少请求后主动退出（防内存泄漏），而 max_wait_time 控制它退出时能拖多久。两者作用阶段不同，但常常一起出现。当 max_request 触发主动退出流程时，同样会尊重 max_wait_time（前提是 reload_async 开启）。举个例子：如果 max_request = 1000，但某 Worker 在第 999 个请求时开始处理一个 60 秒的长任务，且 max_wait_time = 30，那它会在 30 秒后被强杀，第 1000 次请求永远无法达到。所以生产环境建议把 max_request 设高些（如 5000），靠 max_wait_time 和信号控制更可控的重启时机。

验证 max_wait_time 是否真起作用，别只看进程 PID 变了

光用 ps aux | grep php 看到 Worker PID 刷新了，并不能说明是平滑重启——完全可能是暴力重启。真正验证得看行为：

• 在请求入口加日志：echo "start: " . microtime(true) . " pid:" . getmypid() . PHP_EOL;，然后发起一个长 sleep 请求（如 usleep(2000000)）
• 发 kill -USR1 $master_pid，观察该请求是否完整返回（而非 502 或中断）
• 查错误日志里有没有 coroutine was destroyed 或 task timeout 类报错
• Hyperf 用户可监听 OnWorkerStop 事件，在里面打点记录退出时间，对比 max_wait_time 是否被遵守

最后提醒一点：开发环境本地测试时请求通常很短，max_wait_time 看起来总是能等完，但一上生产，遇到慢查询或外部依赖超时，问题立马暴露出来。所以生产环境的配置一定要经过压力测试验证。