Redis Cluster 多键命令为什么报 CROSSSLOT

在 Redis Cluster 中，下面这类多键命令很容易遇到 CROSSSLOT Keys in request don't hash to the same slot：

# 两个键没有共享 hash tag，可能被分配到不同槽位
redis-cli -c MGET user:1001:name user:1001:level

这不是普通的 MOVED 重定向。MOVED 表示客户端访问了错误节点，客户端通常可以根据槽位信息重发；CROSSSLOT 表示同一条多键命令中的键跨越了不同槽位，当前节点不能把它们当成一个原子多键操作处理。

官方地址：https://redis.io/

解决思路很明确：先用 CLUSTER KEYSLOT 比较实际槽位，再给必须一起访问的键加入相同的 hash tag，例如 user:{1001}:name 和 user:{1001}:level。Redis Cluster 会对首个有效花括号中的内容计算槽位。

先区分 CROSSSLOT 与 MOVED

Redis Cluster 把键空间划分为 16384 个 hash slot。单键命令只需要找到目标键所在的槽位；多键命令则要求参与命令的键属于同一个槽位，否则节点没有办法在集群拓扑下完成这条多键操作。

因此，看到错误时先不要急着修改客户端重试。可以先按下面的判断表区分原因：

用 CLUSTER KEYSLOT 找出冲突键

排查的第一步是把命令中的每个键单独交给 Redis 计算槽位。下面的输出是假定示例，用来说明阅读方法，不是本机运行截图：

# 分别计算两个键的槽位，输出不相同就说明它们不能直接组成多键命令
redis-cli -c CLUSTER KEYSLOT user:1001:name
redis-cli -c CLUSTER KEYSLOT user:1001:level

# 改造后再次比较，两个键共享 {1001} 标签
redis-cli -c CLUSTER KEYSLOT user:{1001}:name
redis-cli -c CLUSTER KEYSLOT user:{1001}:level

前两个结果不必记住具体数字，只要不同就足以解释 CROSSSLOT。后两个结果应当相同，因为参与计算的有效内容都是 1001。在应用日志中，建议把多键命令的键列表和客户端计算出的槽位一起记录，定位会比只记录异常字符串更快。

用 hash tag 重新设计键名

hash tag 的作用不是给键增加业务字段，而是指定一段稳定的槽位计算输入。围绕同一个用户、订单或购物车组织的键，可以把业务标识放到花括号内：

# 同一用户的相关键共享标签，适合需要多键访问的场景
user:{1001}:profile
user:{1001}:quota
user:{1001}:sessions

# 另一个用户使用不同标签，避免所有用户挤到同一槽位
user:{1002}:profile

这样设计后，类似 MGET、DEL 或 Lua 脚本中涉及这些键的多键操作才有机会落在同一槽位。标签应当来自真正的业务聚合边界：需要一起读取或一起变更的键放在同一标签下，不需要协同的键不要为了“方便”全部使用同一个标签。

四个容易忽略的 hash tag 边界

1. 空花括号不会形成有效标签

foo{}{bar} 会按完整键计算，因为第一对花括号中间没有字符。不要把空标签当作共享槽位的写法。

2. 只取首个有效花括号

花括号很多时，Redis 使用第一个 { 以及其右侧第一个 } 之间的非空内容。键名最好只保留一段明确的标签，避免读者和维护者误判。

3. 标签过于集中会形成热点

如果把所有订单都写成 order:{all}:...，相关多键命令确实容易同槽，但大量读写也会集中到一个槽位和一个主节点。标签应按业务聚合粒度选择，例如使用用户 ID、订单 ID，而不是固定常量。

4. 迁移不等于可以跨槽

扩容、缩容或 resharding 会移动槽位归属，但不会改变“多键命令需要同槽”的约束。先解决键名的槽位关系，再处理拓扑变化；不要把 CROSSSLOT 当成集群正在迁移的证据。

排查清单与常见问题

1. 列出这条多键命令实际使用的全部键。
2. 对每个键执行 CLUSTER KEYSLOT 并比较结果。
3. 确认客户端使用的是 Cluster 连接模式，而不是把集群当单机连接。
4. 只为确实需要共同访问的键增加同一 hash tag。
5. 检查标签是否为空、是否误用了固定常量、是否制造了热点。

Q：客户端开启 Cluster 模式后还会有 CROSSSLOT 吗？
会。Cluster 模式能处理节点路由和重定向，但不会替应用把不同槽位的多键操作合并成一个原子操作。

Q：把两个键改成相同前缀就能同槽吗？
不能保证。普通前缀仍然会参与完整键名的哈希；需要共同槽位时，应明确使用相同的非空 hash tag。

Q：所有键都加同一个标签是不是最简单？
通常不是。它会牺牲槽位分布和横向吞吐，正确做法是让标签对应真实的业务聚合边界。

总结一下：CROSSSLOT 的关键不是重试次数，而是多键命令的槽位关系。用 CLUSTER KEYSLOT 找到差异，再用按业务对象划分的 hash tag 重新设计键名，最后检查热点和迁移边界，就能把问题从“偶发报错”还原成可解释的键空间设计问题。