Redis Cluster 客户端遇到 CROSSSLOT 时如何重构 key

在 Redis Cluster 中执行 MGET、事务或 Lua 脚本时，如果一次请求涉及的 key 不在同一个 hash slot，客户端通常会收到 CROSSSLOT Keys in request don't hash to the same slot。这不是把客户端重试几次就能解决的网络问题，而是多键操作与分片边界发生了冲突。

官方文档：https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/

为什么多键命令会触发 CROSSSLOT

Redis Cluster 的基本分片计算可以理解为 CRC16(key) mod 16384。普通 key 的完整字符串参与计算，因此 user:1001:profile 和 order:1001:summary 即使包含同一个数字，也不保证落在同一槽。

而 MGET、涉及多个 key 的事务，以及需要同时访问多个 key 的 Lua 脚本，都必须能由同一个负责节点完成。客户端的集群路由只能把请求送到正确节点，不能把一条跨槽的多键语义拆成一个原子操作，所以最终会看到 CROSSSLOT。

先用 CLUSTER KEYSLOT 找到真正不一致的 key

排查时先把报错中的 key 集合完整列出来，再逐个计算 slot。不要先改客户端参数，也不要因为两个 key 都以 user 开头就认为它们相邻。

# 分别查看参与多键命令的 key 所在槽位
redis-cli -c -h 127.0.0.1 -p 7000 CLUSTER KEYSLOT "user:1001:profile"
redis-cli -c -h 127.0.0.1 -p 7000 CLUSTER KEYSLOT "order:1001:summary"

# 使用 hash tag 的候选 key；这里只对花括号内的 1001 计算
redis-cli -c -h 127.0.0.1 -p 7000 CLUSTER KEYSLOT "user:{1001}:profile"
redis-cli -c -h 127.0.0.1 -p 7000 CLUSTER KEYSLOT "order:{1001}:summary"

前两条返回不同数字，就能解释原来的 CROSSSLOT；后两条返回相同数字，说明 key 设计满足同槽条件。这个命令只查询槽位，不会创建或修改 key，适合在测试环境先核对命名方案。

用 hash tag 重构同一业务对象的 key

Redis Cluster 的 hash tag 规则是：key 中出现成对花括号时，只把第一对花括号之间的内容作为哈希输入。因此可以把“同一次多键操作必须一起读取”的业务标识放进去：

// Go 示例：让同一用户的相关 key 共享 hash tag
func userKeys(id string) (string, string) {
	// id 是业务对象标识；花括号内的内容决定 Redis Cluster 槽位
	profile := "user:{" + id + "}:profile"
	orders := "user:{" + id + "}:orders"
	// 两个 key 可用于同槽的 MGET、事务或 Lua 场景
	return profile, orders
}

命名时要把 tag 设为稳定且有业务意义的粒度，例如用户 ID、购物车 ID或租户 ID。不要把固定字符串写成 {all}，否则大量对象会被压进一个槽，分片虽然“看起来”解决了，却换成热点和容量失衡。

迁移与复查时别把所有 key 都强行共槽

如果线上已经存在旧 key，先让生成器支持新旧格式，再安排双读或按对象渐进迁移；确认新格式可读后再删除旧 key。迁移期间不要只验证单个 GET，还要复查真实的 MGET、事务和脚本调用。

最后用 CLUSTER KEYSLOT 固化一组代表性 key 的检查清单，并把 key 生成器、迁移脚本和 Lua 参数放在同一份约定里。若业务本来就允许跨对象查询，优先拆解命令或改变数据模型，不要把整个集群压到一个槽位。

常见问题

只给 key 加上相同前缀，能避免 CROSSSLOT 吗？

不能。没有 hash tag 时，完整 key 都参与哈希；只有花括号内的共享内容才会触发特殊规则。

hash tag 越短越好吗？

不一定。应优先选择稳定、基数合适的业务 ID；固定 tag 会制造热点，过于分散又无法支持需要同槽的多键操作。

客户端开启集群模式后还需要改 key 吗？

需要。集群客户端负责路由和重定向处理，不能改变多键命令必须同槽的约束；key 设计仍是应用责任。