Laravel Octane 中 Docker 容器停止后 MySQL 连接未释放问题解析

问题背景

在使用 Laravel Octane 配合 Docker 部署时，开发者发现当 Docker 容器停止后，MySQL 连接并未被正确释放。这会导致随着容器多次重启，MySQL 的连接数逐渐耗尽，最终影响系统正常运行。

问题分析

Octane 使用 Swoole 作为底层服务器时，会保持长连接以提高性能。然而，这种设计在容器化环境中会带来以下问题：

1. 容器生命周期管理：当 Docker 容器被停止时，默认情况下 Octane 进程不会收到终止信号，导致 MySQL 连接保持
2. 连接数累积：每次容器重启都会建立新连接，而旧连接未被释放
3. 信号处理不足：Octane 默认只处理 SIGINT 和 SIGTERM 信号，而容器环境可能发送其他信号

解决方案

方案一：Docker 优雅终止脚本

在 Docker 容器中添加信号处理脚本，确保容器停止时能正确关闭 Octane：

#!/bin/bash

_term() {
  echo "正在优雅停止 Laravel Octane..."
  php artisan octane:stop
  exit 0
}

trap _term SIGTERM

php artisan octane:start --workers=2 --task-workers=2 --host=0.0.0.0 &

pid=$!
wait $pid

方案二：扩展 Octane 信号处理

修改 Octane 源码，增加对 SIGHUP 信号的处理：

public function getSubscribedSignals() : array
{
    return [ SIGINT, SIGTERM, SIGHUP ];
}

方案三：配置调整

虽然尝试设置 Swoole 的 daemonize 模式为 0 未能解决问题，但在某些场景下可以配合其他配置使用：

'swoole' => [
    'mode' => SWOOLE_BASE,
    'options' => [
        'daemonize' => 0
    ]
],

最佳实践建议

1. 生产环境部署：推荐使用方案一和方案二结合的方式
2. Kubernetes 环境：配置 preStop 钩子执行优雅终止
3. 连接池管理：考虑实现连接健康检查和自动回收机制
4. 监控告警：设置 MySQL 连接数监控，及时发现异常

技术原理深入

Octane 的长连接机制设计初衷是为了提高性能，但在容器化环境中需要特别注意：

1. 进程模型：Octane 主进程管理多个 worker 进程，每个 worker 独立维护数据库连接
2. 信号传播：容器发送的信号需要正确传播到所有子进程
3. 资源清理：完善的资源清理机制是容器友好应用的关键

通过理解这些底层原理，开发者可以更好地设计适合容器环境的 Laravel 应用架构。