Hyperf集群多库配置核心是语义化连接名、独立连接池调优、显式运行时切换。需为MySQL 8.0/5.7/PostgreSQL等不同协议版本分别定义user_db/log_db/report_db，各自配置适配max_connections与options，并通过Db::connection()或模型$connection显式指定，禁用隐式fallback和跨库JOIN。
Hyperf 在集群环境下配置多数据库连接，核心不是“部署多个实例”，而是让每个服务节点能稳定、隔离、可扩展地访问多个数据源。关键在配置结构清晰、连接池适配运行时环境、切换逻辑明确，避免跨库 JOIN 或隐式 fallback。
一、按语义定义独立连接名
在 config/autoload/databases.php 中，每个数据库连接必须有唯一且带业务含义的 name，例如：
- user_db：主用户库（MySQL 8.0，RDS）
- log_db：日志中心（MySQL 5.7，自建）
- report_db：报表系统（PostgreSQL 14）
禁止使用 db1、slave 这类无上下文命名。不同版本或协议的数据库必须拆成独立连接，不能共用一个连接池 —— MySQL 8.0 的 caching_sha2_password 和 5.7 的认证方式不兼容，混用会导致 handshake 失败。
二、为每个连接显式配置 pool 参数
集群中各数据库实例承载力不同，连接池需按实际调优，不能复用默认值。例如：
- MySQL 5.7 实例
max_connections = 200→ 对应连接池设'max_connections' => 150 - PostgreSQL 14 云实例内存充足 → 可设
'max_connections' => 200 - Swow 环境下必须删除旧
pool一级配置，改用 Swow 专用结构：'heartbeat' => true、'check_interval' => 3000（单位毫秒）
同时补全驱动级选项，比如 MySQL 8.0 加：'options' => [PDO::ATTR_EMULATE_PREPARES => false]；5.7 则建议设为 true。
三、运行时切换要显式、可控、可验证
避免依赖注解或 DI 自动绑定，优先使用以下方式：
- Query Builder：
Db::connection('log_db')->table('error_logs')->where('created_at', '>', now())->get() - Eloquent 模型内指定：
protected $connection = 'user_db'; - 事务内锁定连接：
Db::connection('report_db')->transaction(fn () => {...});
不推荐通过 @Connection 注解切换，易被继承覆盖或上下文干扰；也不建议修改全局默认连接，会污染其他协程。
四、集群场景下的注意事项
多节点部署时，还需关注三点：
-
配置一致性：所有节点的
databases.php必须完全一致，建议通过配置中心（如 Nacos）下发或 CI/CD 构建时注入 -
连接健康检查：启用
heartbeat并设置合理check_interval，避免节点因网络抖动长期持有失效连接 - 故障隔离：某个库不可用时，不应导致整个服务崩溃。可在 DAO 层封装 fallback 逻辑，比如日志库写入失败时降级为本地文件暂存
跨库 JOIN 不支持，需要关联数据时，应通过应用层两次查询 + 内存组装，或引入消息队列异步同步宽表。
