FrankenPHP 中 Worker 脚本优雅关闭问题分析与解决方案

问题背景

在 PHP 应用服务器 FrankenPHP 中，当进行优雅关闭（通过 SIGTERM 信号或管理 API）时，虽然正在处理的请求能够正常完成，但 Worker 脚本本身却无法优雅关闭。这导致开发者无法在 Worker 停止时执行必要的清理任务，如发送遥测数据等。

问题现象

通过一个简单的测试脚本可以重现这个问题：

<?php
ignore_user_abort(true);

$log_file = dirname(__DIR__).'/storage/logs/worker.log';
file_put_contents($log_file, "Starting worker\n", FILE_APPEND);

// 请求处理器
$handler = static function () use($log_file) {
    if (str_contains($_SERVER['REQUEST_URI'], 'slow')) {
        sleep(10);
        file_put_contents($log_file, "Slow response done\n", FILE_APPEND);
    } else {
        file_put_contents($log_file, "Normal response done\n", FILE_APPEND);
    }
    echo 'Done';
};

$maxRequests = (int)($_SERVER['MAX_REQUESTS'] ?? 0);
for ($nbRequests = 0; !$maxRequests || $nbRequests < $maxRequests; ++$nbRequests) {
    $keepRunning = \frankenphp_handle_request($handler);
    file_put_contents($log_file, "Request processed. Keep running: $keepRunning\n", FILE_APPEND);
    gc_collect_cycles();
    if (!$keepRunning) break;
}

file_put_contents($log_file, "Worker stopped - Cleaning up\n", FILE_APPEND);

当前行为

在慢请求期间触发优雅关闭时，日志输出可能如下：

Starting worker
Normal response done
Request processed. Keep running: 1
Normal response done
Request processed. Keep running: 1
Slow response done              # 正在处理的请求完成
Request processed. Keep running: 1
[在此处无限挂起 - 或线程被杀死]

预期行为

正确的日志输出应该是：

Starting worker
Normal response done
Request processed. Keep running: 1
Normal response done
Request processed. Keep running: 1
Slow response done 
Request processed. Keep running: 1
Worker stopped - Cleaning up

只有在脚本执行完毕后，pthread 才应该被终止。

技术分析

问题根源

通过分析 FrankenPHP 的源代码，发现问题可能出在以下几个地方：

1. 关闭流程时序问题：在 Shutdown() 函数中，drainWorkers() 和 drainThreads() 的执行顺序可能导致竞争条件。

2. 信号处理不完整：当 workersDone 通道关闭时，go_frankenphp_worker_handle_request_start 中的 select 语句应该触发并返回 false 给 frankenphp_handle_request_function，从而中断循环。但实际观察发现这部分代码并未执行。

3. 线程终止过早：drainThreads() 函数关闭 done 通道后，go_handle_request 会返回 false，导致 C 代码调用 ts_free_thread，这可能过早终止了线程，而没有给 PHP 脚本足够的时间完成清理工作。

关键代码路径

1. 关闭流程入口：

func Shutdown() {
    drainWorkers()
    drainThreads()
    metrics.Shutdown()
    requestChan = nil
    
    if EmbeddedAppPath != "" {
        _ = os.RemoveAll(EmbeddedAppPath)
    }
    
    logger.Debug("FrankenPHP shut down")
}

2. Worker 请求处理循环：

select {
case <-workersDone:
    if c := logger.Check(zapcore.DebugLevel, "shutting down"); c != nil {
        c.Write(zap.String("worker", thread.worker.fileName))
    }
    thread.worker = nil
    C.frankenphp_reset_opcache()
    return C.bool(false)
case r = <-thread.worker.requestChan:
case r = <-thread.requestChan:
}

3. 线程终止逻辑：

static void *php_thread(void *arg) {
    // ...
    while (go_handle_request(thread_index)) {
    }
    go_frankenphp_release_known_variable_keys(thread_index);
    #ifdef ZTS
    ts_free_thread();
    #endif
    return NULL;
}

解决方案

根据问题分析，需要从以下几个方面进行修复：

1. 调整关闭时序：确保 Worker 脚本有足够时间完成清理工作后再终止线程。

2. 完善信号处理：确保关闭信号能够正确传递到所有 Worker 线程。

3. 优化线程管理：避免过早释放线程资源，确保 PHP 脚本能够完整执行清理代码。

技术影响

这个问题的修复将带来以下改进：

1. 可靠的清理操作：开发者可以依赖 Worker 脚本的清理阶段执行关键操作，如数据持久化、资源释放等。

2. 更优雅的关闭流程：整个关闭过程更加可控和可预测，符合现代应用服务器的行为预期。

3. 更好的开发者体验：开发者不再需要寻找变通方案来处理资源清理问题。

最佳实践建议

在使用 FrankenPHP 的 Worker 模式时，建议：

1. 明确区分请求处理和清理逻辑：将关键资源的管理放在 Worker 脚本的主循环之外。

2. 设置适当的超时：为清理操作设置合理的时间限制，避免因清理时间过长影响关闭流程。

3. 记录关键事件：在 Worker 脚本的关键节点添加日志，便于问题排查。

4. 测试关闭行为：在开发环境中充分测试各种关闭场景，确保应用行为符合预期。

总结

FrankenPHP 的 Worker 脚本优雅关闭问题是一个典型的资源生命周期管理挑战。通过深入分析其内部机制，我们不仅找到了问题的根源，也提出了系统性的解决方案。这类问题的解决不仅提升了 FrankenPHP 的可靠性，也为其他类似架构的应用服务器提供了有价值的参考。