hyperf连接redis集群必须使用rediscluster而非redis，因hyperf/redis仅支持单机模式；多键操作需用{}哈希标签确保共槽，如{user:1001}:profile；前缀配置无效，须业务层显式控制标签。
Hyperf连接Redis集群必须用RedisCluster而非Redis
Hyperf默认的hyperf/redis组件只封装了单机Redis客户端，即使配置了多个节点地址，底层仍走单连接逻辑，无法识别集群拓扑和槽路由。直接注入Redis实例调用MSET或DEL多键命令时，请求会被随机发往某个节点，触发CROSSSLOT错误。
正确做法是跳过hyperf/redis的自动封装，手动注册RedisCluster实例：
- 确认已启用
phpredis扩展（php -m | grep redis需输出redis） - 在
config/autoload/redis.php中定义集群节点列表，如：'cluster_nodes' => ['127.0.0.1:7000', '127.0.0.1:7001', '127.0.0.1:7002'] - 创建自定义
RedisClusterFactory，在create()中初始化new RedisCluster(NULL, $nodes)，并设置OPT_READ_TIMEOUT和OPT_SERIALIZER - 通过
@Inject注入该工厂生成的RedisCluster实例，而非Redis
所有涉及多个key的操作必须保证共槽，{}哈希标签不是可选项
Redis集群强制要求MGET、MSET、DEL、RENAME等命令的所有key落在同一slot。CRC16计算时，{}之间的内容才是哈希输入——这是唯一可控的共槽手段。
比如用户资料与订单需批量读取，不能用user:1001:profile和user:1001:orders，而必须写成：
$redisCluster->mget(['{user:1001}:profile', '{user:1001}:orders']);
$redisCluster->rename('{user:1001}:temp', '{user:1001}:final');
常见踩坑点：
- 前缀带冒号但没包裹
{}，如user:1001:profile→ CRC16算的是整个字符串，不保证共槽 - 标签内含变量但未统一，如
{user:1001}和{user:1002}混用 → 实际分到不同slot - 业务层拼接key时漏掉
{}，尤其在DTO转key、缓存装饰器等间接场景
Hyperf里没法全局加{}前缀，必须在业务代码里显式控制
Hyperf的redis.prefix配置项只对单机模式生效，RedisCluster完全忽略该配置。试图在redis.php里配'prefix' => '{user}'不会影响任何key的哈希行为。
安全做法是封装一个带标签的Key生成器：
class ClusterKey
{
public static function user(string $id, string $suffix): string
{
return "{user:{$id}}:{$suffix}";
}
}
// 使用
$redisCluster->set(ClusterKey::user('1001', 'profile'), '...');
$redisCluster->mget([ClusterKey::user('1001', 'profile'), ClusterKey::user('1001', 'orders')]);
关键约束：
- 标签内容必须完全一致（大小写、空格、分隔符），
{user:1001}≠{User:1001} - 避免在标签里放动态值（如时间戳、随机数），否则失去共槽意义
- 已有数据迁移时，不能仅改应用层key，必须用
CLUSTER GETKEYSINSLOT+MIGRATE同步搬迁
别信“集群自动重试”，CROSSSLOT是设计限制，不是临时故障
有些开发者看到No more cluster retries错误就以为是网络抖动，加重试就能解决。但CROSSSLOT是Redis Cluster的硬性协议限制，跟网络无关——只要key不共槽，无论重试多少次、换哪个节点连，结果都是同一个错误。
验证是否真为共槽问题，最直接方式是进Redis CLI执行：
127.0.0.1:7000> cluster keyslot {user:1001}:profile
(integer) 12345
127.0.0.1:7000> cluster keyslot {user:1001}:orders
(integer) 12345
两个返回值不一致，说明标签没生效；一致但仍有CROSSSLOT，大概率是客户端没走RedisCluster实例，还在用普通Redis对象发请求。
