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

2025-05-29 09:45:52作者：蔡怀权

问题背景

在 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 的源代码，发现问题可能出在以下几个地方：

关闭流程时序问题：在 Shutdown() 函数中，drainWorkers() 和 drainThreads() 的执行顺序可能导致竞争条件。
信号处理不完整：当 workersDone 通道关闭时，go_frankenphp_worker_handle_request_start 中的 select 语句应该触发并返回 false 给 frankenphp_handle_request_function，从而中断循环。但实际观察发现这部分代码并未执行。
线程终止过早：drainThreads() 函数关闭 done 通道后，go_handle_request 会返回 false，导致 C 代码调用 ts_free_thread，这可能过早终止了线程，而没有给 PHP 脚本足够的时间完成清理工作。

关键代码路径

关闭流程入口：

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

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:
}

线程终止逻辑：

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;
}