hyperf 3.1.66 起支持连接池全量刷新,通过销毁空闲连接并批量重建实现“焕然一新”,仅适用于 hyperf/database 和 hyperf/redis;可通过调用 $pool->refresh() 或配置 refresh_interval 定时触发,日志与统计可验证生效。

Hyperf 3.1 中连接池全量刷新功能用于解决连接池长期运行后因连接老化、服务端重启或网络抖动导致的 stale connection 问题,避免请求偶发失败却难以定位。
什么是连接池全量刷新
全量刷新指在不中断服务的前提下,主动销毁当前池中所有空闲连接,并触发新连接的批量重建,使整个连接池“焕然一新”。它不是逐个替换,而是原子性切换——旧连接在 release 后不再复用,新连接从重建队列中供给。
该机制自 v3.1.66 起正式支持,仅对 hyperf/database 和 hyperf/redis 的连接池生效,hyperf/http-client 需依赖 pool.max_idle_time 触发自然淘汰,不支持主动全刷。
触发全量刷新的两种方式
方法一:调用 Pool 对象的 refresh() 方法(推荐)
第一步:从容器中获取对应连接池实例。例如 MySQL 池名为 'mysql',执行:$pool = $container->get(\Hyperf\Pool\SimplePool::class)->getPool('mysql');
第二步:直接调用 $pool->refresh()。这会立即标记所有空闲连接为“待销毁”,并在下次 acquire 时优先创建新连接。注意:正在被使用的连接不受影响,仍会正常归还;刷新过程无锁阻塞,协程安全。
方法二:配置定时自动刷新(适用于稳定性要求高的场景)
在 config/autoload/pool.php 中为指定池添加 refresh_interval 字段:
'mysql' => [ 'refresh_interval' => 3600 // 单位:秒,表示每小时全刷一次 ]
【必须确保 pool 组件版本 ≥ v3.1.66】,低版本该配置会被忽略且无任何报错提示。
验证刷新是否生效
启用 DEBUG 日志级别后,在日志中搜索关键词 Pool refreshed,每触发一次全量刷新,都会输出一行带时间戳和池名的日志。
观察连接池统计:在任意协程内调用 $pool->getStats(),对比刷新前后的 create_count 值应明显上升,idle_num 在刷新后短暂归零再缓慢回升。
数据库端执行 SHOW PROCESSLIST,可见旧连接的 Time 字段持续增长直至超时断开,新连接的 Time 从 0 开始计数——这说明连接已实际重建而非复用。











