Hyperf配置多Redis集群实例方法

Hyperf虽支持多Redis集群实例，但严禁在同一个连接池中混入不同逻辑集群的节点——因为Redis Cluster客户端依赖统一的slot映射机制，跨集群混配会导致MOVED/ASK路由错误甚至连接失败；正确做法是为每个独立集群（如缓存、会话）定义专属连接池（如cache_cluster、session_cluster），在redis.php中分别配置其nodes和pool参数，并通过显式指定poolName或封装专用Redis子类来精准调用，从而实现安全、隔离、可维护的多集群协同。

Hyperf 支持多个 Redis 集群实例，但 redis.php 配置文件本身不支持「为同一个连接池配置多个集群」——每个命名连接池（如 default、cache、queue）只能对应一种模式（单机 / Sentinel / Cluster），且 Cluster 模式下所有节点必须属于**同一个 Redis Cluster 逻辑集群**。

为什么不能在同一个 pool 里混写不同集群的 nodes？

Redis Cluster 客户端（如 phpredis 或 predis）启动时会向任一 seed 节点发起 CLUSTER SLOTS 请求，自动发现整个集群的 slot 分布和节点拓扑。如果你把两个物理上互不隶属的集群节点（比如 A 集群的 192.168.1.10:7001 和 B 集群的 192.168.1.20:7001）都塞进 nodes 数组，客户端会尝试用同一套 slot 映射去路由所有 key，必然导致 MOVED 或 ASK 错误，甚至连接失败。

正确做法：为每个独立集群定义单独的连接池

你需要在 config/autoload/redis.php 中为每个 Redis Cluster 实例声明一个独立的配置项，例如：

'cache_cluster' => [
    'cluster' => [
        'enable' => true,
        'nodes' => [
            ['host' => '192.168.1.10', 'port' => 7001],
            ['host' => '192.168.1.10', 'port' => 7002],
            ['host' => '192.168.1.11', 'port' => 7001],
        ],
        'read_timeout' => 2.0,
        'compression' => false,
    ],
    'pool' => [
        'min_connections' => 3,
        'max_connections' => 20,
    ],
],
'session_cluster' => [
    'cluster' => [
        'enable' => true,
        'nodes' => [
            ['host' => '192.168.1.20', 'port' => 7001],
            ['host' => '192.168.1.20', 'port' => 7002],
            ['host' => '192.168.1.21', 'port' => 7001],
        ],
    ],
    'pool' => [
        'min_connections' => 2,
        'max_connections' => 10,
    ],
],

这样就定义了两个完全隔离的集群连接池：cache_cluster 和 session_cluster。

如何在代码中使用指定集群？

Hyperf 的 Hyperf\Redis\Redis 类默认绑定 default 池。要使用其他集群，必须显式指定池名：

• 通过依赖注入容器获取：$this->container->get(\Hyperf\Redis\Redis::class)->setPoolName('cache_cluster')
• 更推荐：封装专用类，重写 $poolName 属性

例如：

use Hyperf\Redis\Redis;

class CacheClusterRedis extends Redis
{
    protected $poolName = 'cache_cluster';
}

然后在服务中注入它：

#[Inject]
protected CacheClusterRedis $cacheRedis;

public function doSomething()
{
    $this->cacheRedis->set('foo', 'bar');
}

容易踩的坑

以下问题在多集群场景下高频出现：

• RedisCluster::connect(): php_network_getaddresses: getaddrinfo failed：某个 nodes 条目 DNS 不通或端口被防火墙拦截，建议只填 1–2 个高可用 seed 节点，而非全部；
• 用了 mget 却返回 false 或抛异常：没加 Hash Tag（如 {user:123}:profile），导致 key 落在不同节点 —— 这跟“多个集群”无关，但常被误认为是配置问题；
• 环境变量覆盖出错：若用 env('REDIS_CLUSTER_ENABLE') 控制开关，确保每个池的 cluster.enable 是独立判断的，不要全局共用一个开关；
• 连接池复用混乱：多个集群共用同一份 pool 配置参数（如 max_connections）没问题，但切勿复用 context 或 ssl 配置，不同集群可能 TLS 版本或 CA 不同。

真正需要区分的是集群归属，而不是“在同一个池里堆更多节点”。每个逻辑集群，就是一份独立的 nodes + 独立的 poolName。

到这里，我们也就讲完了《Hyperf配置多Redis集群实例方法》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！