PHP CLI 长任务如何用 pcntl_signal 优雅停止：信号处理与检查点设计

夜间批处理跑到一半时，部署系统发来 SIGTERM。直接杀掉 PHP CLI 进程，当前批次可能只写了一半；完全不响应，又会让旧进程拖住发布。更稳的做法是让 pcntl_signal 只记录“收到停止请求”，等当前任务回到检查点后再收尾退出。

优雅停止的关键不是立刻中断，而是把信号转成可观察的停止状态，并在每个批次边界决定提交、回滚和退出码。

长任务的瓶颈不在信号，而在退出边界

批处理通常由一个外层循环读取待处理 ID，再调用 processBatch 写入结果。问题是信号可能在数据库事务中间到达：如果回调里直接 exit，事务、临时文件和进度记录都没有统一收尾；如果完全忽略信号，进程只能等所有数据处理完。

因此这里把生命周期拆成三个节点：runBatch 负责一批业务动作，commit 负责提交当前批次，stopRequested 负责把停止意图带回主循环。信号处理只改变状态，不抢业务代码的控制权。

先把 SIGTERM 变成主循环能读懂的状态

下面的回调很短，故意不写日志文件、不发 SQL，也不直接退出进程。pcntl_async_signals(true) 让 PHP 在合适的执行点分发信号；在不支持异步分发的环境里，也可以在循环中显式调用 pcntl_signal_dispatch()。

这里的两个回调共享同一个 $stopRequested 引用。循环条件只阻止下一批开始，已经进入 runBatch 的批次仍会走到 commit。这就是第一个可验证的停止边界：日志里应能看到当前批次结束，而不是半条记录。

把检查点放在批次提交之后

仅检查外层 while 还不够。如果 nextBatch 一次返回很多条记录，停止请求会一直等到整批结束。工程上要把批次大小当成退出延迟的上限，并在提交后记录进度，再决定是否继续取数。

$processed = 0;
$stopRequested = false;

while (($batch = nextBatch()) !== null) {
    try {
        runBatch($batch);
        commit($batch);
        $processed += count($batch);
        saveCheckpoint($processed);
    } catch (Throwable $error) {
        rollback($batch);
        fwrite(STDERR, $error->getMessage() . PHP_EOL);
        exit(1);
    }

    if ($stopRequested) {
        fwrite(STDOUT, "stop requested after checkpoint" . PHP_EOL);
        break;
    }
}

exit(0);

停止请求发生在 commit 之前时，当前批次仍由异常处理决定回滚；发生在 saveCheckpoint 之后时，进程安全跳出，下一次启动可从已保存位置继续。不要把“收到信号”直接当作“当前批次失败”，两者是不同状态。

高并发部署时，批次大小决定收尾成本

长任务的吞吐和停止延迟互相牵制。批次太大，数据库事务更重，SIGTERM 到退出之间的窗口更长；批次太小，提交次数和日志量会上升。可以先从业务允许的恢复粒度出发，而不是先追求最大的批量值。

如果任务不能重复执行，就不能只保存一个整数进度；应把批次 ID、输入版本和提交结果一起写入可查询记录。信号处理解决的是退出协调，不会自动替你解决幂等。

测试时要验证状态变化，而不是只看进程消失

本地可以让脚本在每批之间短暂停留，再用 posix_kill 向目标 PID 发送 SIGTERM。验收重点有三个：当前批次是否完整结束、checkpoint 是否落在已提交数据之后、下一次启动是否跳过已完成批次。

$pid = getmypid();
// 测试脚本中由外部进程调用：posix_kill($pid, SIGTERM)
if ($stopRequested) {
    fwrite(STDOUT, "graceful stop" . PHP_EOL);
}

生产环境不要在信号回调里调用复杂依赖，也不要用 exit(0) 掩盖业务异常。真正的成功应同时满足：最后一批提交成功、进度记录可读、进程退出码符合调度约定。

相关问题

为什么不在 pcntl_signal 回调里直接 exit？

回调可能打断事务、文件写入或锁释放。把信号转成布尔状态，能让主流程在明确的检查点完成收尾。

SIGTERM 和 SIGINT 都要处理吗？

CLI 任务通常可以同时处理。SIGTERM 多由进程管理器发送，SIGINT 常见于终端中断；两者都应进入同一套安全退出路径。

pcntl_async_signals 是否替代了检查点？

不能。它只改变信号分发时机，批次提交、checkpoint、回滚和退出码仍需由业务代码明确实现。

小结

PHP CLI 长任务的优雅停止是一条调用链：SIGTERM 进入 pcntl_signal，回调设置 stopRequested，主循环完成当前批次并写下 checkpoint，最后用退出码把结果交给调度器。把这个边界做实，部署可以停止旧进程，数据也不会因为一次信号被切在半路。