Webman集成Eloquent需五步：一、模型显式指定$connection；二、仅onWorkerStart初始化Capsule并禁用持久连接；三、按表结构配置$timestamps及CREATED_AT/UPDATED_AT；四、跨库事务须手动两阶段提交；五、在composer.json注册appmodel命名空间并dump-autoload。
Webman 集成 Eloquent 不是“装了就能用”，核心障碍在连接生命周期与协程环境不兼容——直接 new Capsule 或在控制器里调用 DB::connection() 必然导致连接泄漏、事务失效或数据错乱。
模型必须显式指定 $connection 才能查对库
Webman 默认没有全局默认连接上下文，Eloquent 会 fallback 到 config/database.php 中的 default，但多库场景下极易走错。尤其当你有 mysql_primary 和 mysql_log 两个配置时，不声明就等于随机查库。
- 在模型类顶部添加
protected $connection = 'mysql_log'; - 确保
config/database.php的connections.mysql_log存在且字段完整（host、database、username、password） - 动态切换可用
User::on('mysql_primary')->find(1)，但注意：该写法每次都会新建连接实例，高并发下慎用 - 若使用
webman/database插件，其连接池机制要求$connection名必须与配置中键名完全一致，大小写敏感
onWorkerStart 是唯一安全的初始化时机
Eloquent 初始化必须绑定到 Worker 进程启动阶段，否则每个请求都执行 Capsule::bootEloquent() 会导致 PDO 句柄无限堆积，MySQL 报 Too many connections。
Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。
- 在
support/Bootstrap.php或独立启动器中，仅在onWorkerStart回调里调用一次Capsule::setAsGlobal() - 禁用持久连接：
'options' => [PDO::ATTR_PERSISTENT => false]，否则连接无法被协程调度器回收 - 不要在中间件、控制器或
onMessage中重复初始化 Capsule 实例 - 如果用了
illuminate/events，事件监听器也得手动注册进 Capsule，否则Model::created等静态事件不触发
时间戳字段必须与表结构严格对齐
$timestamps = true 不是可选项，而是开关——开就强制写 created_at/updated_at，关就彻底跳过。错配直接报 SQL 错误。
- 表里没有这两个字段？必须加
public $timestamps = false; - 字段名不是标准名？需同步改
const CREATED_AT = 'add_time';和const UPDATED_AT = 'edit_time'; - 用的是 MySQL 8+ 的
TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP？那 PHP 层就不该再写入，建议关掉$timestamps并靠数据库兜底 - 软删除字段
deleted_at同理：表里没这列，use SoftDeletes;就会炸
PHP 8.4+ 下必须绕过 webman/database 插件
截至 2026 年 5 月，webman/database v2.3.0 仍未适配 PHP 8.4 的反射变更，Capsule::bootEloquent() 会在 ConnectionResolver 内部抛出 ReflectionException。
- 删掉
config/bootstrap.php中插件自动注入的启动项 - 新建
app/init/EloquentInit.php，实现Webman\Bootstrap接口 - 在
start()里手动加载配置：$config = config('database.connections.mysql');，再传给Capsule::addConnection($config, 'mysql') - 务必检查
composer.json中illuminate/database版本是否 ≥ 10.42.0（该版本起修复了 PHP 8.4 的__set_state兼容问题）
最易被忽略的是连接复用边界：Eloquent 的 Connection 实例不是线程安全的，也不是协程安全的——它不感知 Fiber 切换。所以哪怕你用了 amphp/mysql 替换底层，也得确保每个协程拿到的是独占连接实例，而不是从 Worker 进程里共享一个。
