Swoole信号中断处理与排查指南

本文深入剖析了Swoole协程环境下信号处理失效的根本原因——Swoole启动时主动屏蔽所有线程信号（swSignal_none），导致PHP原生pcntl_signal完全失灵；明确指出唯一可靠方案是在Server启动前使用Swoole\Process::signal注册非阻塞、无协程调用的纯同步回调，并通过Channel将信号事件安全“转发”至协程逻辑，配合严谨的优雅退出链（状态标记→停止accept→等待协程自然结束→onWorkerStop清理资源），避免请求堆积、数据丢失和资源泄漏等线上高频事故。

协程中直接注册 pcntl_signal 会失效，必须用 Swoole\Process::signal 或 swSignal_add 底层接口——因为 Swoole 主线程已屏蔽所有信号，只允许自己接管。

为什么 pcntl_signal 在 Swoole 协程里不触发？

不是你代码写错了，是 Swoole 启动时就调用了 swSignal_none()，把所有信号对全部线程（包括 Worker）都 SIG_BLOCK 了。此时 pcntl_signal 注册的处理器根本收不到信号，系统调用被内核丢弃。

• 现象：发 kill -SIGTERM {pid}，进程没反应，日志无输出，协程照常运行
• 本质：信号只送达主线程（Manager/Master），Worker 进程默认忽略；而 pcntl_signal 是 PHP 用户层注册，无法穿透 Swoole 的信号拦截层
• 验证方式：用 strace -p {pid} -e trace=rt_sigaction,rt_sigprocmask 可看到信号被阻塞，且无你的回调地址

该用哪个函数注册信号处理器？

只认 Swoole\Process::signal ——它内部调用 swSignal_add，把回调写进全局 signals[] 数组，并通过 sigaction 绑定到主线程。这是唯一能生效的路径。

• 必须在 Swoole\Server 启动前注册，否则可能错过首次信号
• 回调函数必须是**非阻塞、无协程 API 调用**的纯同步逻辑（比如不能写 Swoole\Coroutine::sleep() 或 $server->shutdown()）
• 常见误用：Swoole\Coroutine::create 里调用 Swoole\Process::signal ——错，必须在主协程/主线程上下文注册
• 示例正确写法：

Swoole\Process::signal(SIGTERM, function () {
    echo "SIGTERM received\n";
    // 仅标记退出状态，不执行耗时操作
    SwooleG::set(['shutdown' => true]);
});
$server->start();

如何安全地把信号通知传给协程业务逻辑？

信号回调本身不能进协程，但你可以用 Swoole\Coroutine\Channel 把事件“转发”出去，让主协程或专用协程消费。

• 不要在信号回调里调用 $server->shutdown() 或 Swoole\Event::exit() ——它们会强制中断事件循环，导致连接未清理完就退出
• 推荐模式：信号回调只向 Channel 写入一个标识，主循环定期 pop 检查，再执行优雅关闭流程
• 注意 Channel 容量设为 1 即可，防止重复信号堆积（SIGTERM 多发一次也没意义）
• Worker 进程不处理信号，只响应 Manager 进程的 kill 指令；所以信号注册只需在 Master 进程做一次

优雅退出时最容易漏掉的三件事

信号收到 ≠ 服务安全退出。大量线上事故源于“以为关了，其实卡在半路”。

• 忘记调用 $server->shutdown()：新连接仍可接入，老请求却不再被处理，造成请求堆积或超时
• 未等待活跃协程自然结束：比如正在写 Redis、上传文件、发 HTTP 请求的协程，直接退出会导致数据丢失或资源泄漏
• 忽略 onWorkerStop 回调里的清理：数据库连接、Redis 连接池、临时文件、共享内存等，得在这里显式 close() 或 unset()

真正可靠的退出链是：信号 → 标记状态 → 主循环停止 accept → 等待 onReceive/onMessage 协程自然返回 → 触发 onWorkerStop → 进程退出。中间任何一环跳过，都算“非优雅”。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~