笙亿网络策划

Redis 集群槽位分配不均导致 CLUSTER_SLOT 报错，该怎么排查？

约 5 分钟读完 1 阅
文章导读
Redis 集群槽位分配不均导致 CLUSTER_SLOT 或 CLUSTERDOWN 报错，核心原因是 16384 个哈希槽未完全覆盖或指向失效节点。排查首选 redis-cli `--cluster` check 检查槽位分布，若发现空缺需通过 reshard 迁移或 ADDSLOTS 补全，确保所有槽位由在线主节点负责。
📋 目录
  1. 壹 命令速用版
  2. 贰 为什么会这样
  3. 叁 分步处理
  4. 肆 怎么验证是否生效
  5. 伍 常见坑
  6. 陆 常见问题
  7. 柒 参考来源
A A

Redis 集群槽位分配不均导致 CLUSTER_SLOT 或 CLUSTERDOWN 报错，核心原因是 16384 个哈希槽未完全覆盖或指向失效节点。排查首选 redis-cli `--cluster` check 检查槽位分布，若发现空缺需通过 reshard 迁移或 ADDSLOTS 补全，确保所有槽位由在线主节点负责。

先说结论：槽位分配不均必须修复，否则集群无法写入且可能触发内存溢出。

  • 先确认：使用 cluster slots 配合 awk 计算槽位总数是否等于 16384
  • 先处理：槽位空缺用 CLUSTER ADDSLOTS 补全，分布不均用 reshard 迁移
  • 再验证：执行 cluster info 确认 cluster_state 变为 ok 且无 CLUSTERDOWN 报错

命令速用版

以下命令用于快速检查槽位覆盖情况和节点状态，需在任一集群节点执行：

redis-cli `--cluster` check 127.0.0.1:6379
redis-cli -c -h 127.0.0.1 -p 6379 cluster slots
awk '{sum += $2-$1+1} END {print sum}' slots.txt

若需自动平衡槽位，使用官方推荐工具：

redis-cli `--cluster` rebalance 127.0.0.1:6379 `--threshold` 5

为什么会这样

Redis 集群依赖 16384 个哈希槽全覆盖来路由请求，任何槽位空缺或指向故障节点都会触发集群保护机制。槽位分配不均本质是集群元数据与实际节点负载不匹配，常见于扩容缩容中断、节点故障替换未重平衡或手动迁移操作失误。当槽位未被任何在线主节点负责时，集群状态会变为 fail，客户端写入请求会被拒绝并返回 CLUSTERDOWN 错误。

分步处理

第一步：检查槽位覆盖完整性

Redis 集群槽位分配不均导致 CLUSTER_SLOT 报错，该怎么排查？

连接任一节点执行 cluster slots，将输出保存为 slots.txt。使用 awk 命令计算槽位总数，结果必须为 16384。若小于该值，说明存在未分配槽位；若发现某段槽位指向状态为 fail 的节点，需先清理失效节点记录。

第二步：清理失效节点记忆

若槽位指向已下线节点，在所有存活节点上执行 CLUSTER FORGET {node_id} 清除对故障节点的记忆。确保目标接收节点状态为 myself,master 且网络连通，避免槽位分配给不可用节点。

第三步：补全或迁移槽位

对于未分配的空缺槽位，连上目标节点分批执行 CLUSTER ADDSLOTS，单次不宜超过 1000 个槽以防协议解析失败。对于分布不均但覆盖完整的场景，使用 redis-cli `--cluster` reshard 交互式迁移槽位，或 `--cluster` rebalance 自动平衡。迁移时需指定目标节点 ID 和源节点 ID，确认 plan 无误后再执行。

Redis 集群槽位分配不均导致 CLUSTER_SLOT 报错，该怎么排查？

怎么验证是否生效

操作完成后，再次执行 cluster info 检查 cluster_state 字段，必须显示为 ok。使用 cluster slots 确认所有槽位段均指向状态正常的主节点 IP。客户端测试写入 key，确认不再返回 MOVED 重定向错误或 CLUSTERDOWN 异常。若使用 Java 客户端，检查连接池是否已刷新 slot 映射缓存。

常见坑

客户端缓存未刷新是迁移后仍报错的主因，Lettuce 或 Redisson 等客户端需等待连接池轮换或手动 reloadPartitions。CLUSTER ADDSLOTS 单次输入过多槽位会导致静默失败，务必分批执行。reshard 迁移过程中会产生 ASK 响应，仅 MOVED 响应才会触发客户端永久更新路由表，测试时需注意区分。新加入的空 master 节点若未显式指定 `--cluster-use-empty-masters` 参数，rebalance 命令可能不会分配槽位给它。

常见问题

CLUSTERDOWN Hash slot not served 怎么解决？

该错误表示特定槽位无主节点负责，需检查 cluster slots 输出是否有未分配段，并用 ADDSLOTS 补全或 reshard 迁移。

槽位迁移后客户端为什么还连错节点？

客户端本地缓存了旧的 slot-node 映射，需等待连接自然过期或调用刷新接口，redis-cli -c 因每次新建连接可立即生效。

ERR Slot 0 is already busy 如何处理？

表示槽位冲突，通常需清空槽位配置，执行 flushall 和 cluster reset 硬重置集群状态后重新分配。

参考来源

  • 【Redis 分布式缓存实战】第 11 章 集群核心问题深度解决
  • 如何解决因 Redis 集群中某些节点 Slot 槽位未完全分配干净导致整个集群处于 Fail 状态
  • 如何解决 Redis Cluster 集群模式下槽位分布不均_利用 reshard 指令重新分配 16384 个槽位
  • Redis 怎样排查 Cluster down 异常_检查所有 16384 个 Slot 是否被正确分配并分配到了在线节点
  • Redis 中集群配置错误的报错与解决方案