Redis 集群节点状态 fail 报错 CLUSTER_FAIL 如何修复

Redis 集群出现 cluster_state:fail 通常是因为槽位分配不完整或超过半数主节点不可用。修复核心是恢复槽位覆盖或重启可用节点，操作前需确认数据备份状态以防丢失。

先说结论：Redis 集群报错 CLUSTER_FAIL 意味着集群不可用，必须通过修复槽位分配或恢复节点通信来解决。

命令速用版

以下命令用于快速诊断和尝试自动修复，需在任意可用节点执行：

redis-cli `--cluster` check 127.0.0.1:7001

redis-cli `--cluster` fix 127.0.0.1:7001

redis-cli -h 127.0.0.1 -p 7001 cluster info

集群状态 fail 的根本原因是槽位映射不完整或多数派主节点丢失。Redis 集群默认要求 16384 个槽位全部指派给在线节点，且超过半数主节点存活才能提供服务。

常见触发场景包括节点宕机后槽位未迁移、网络分区导致节点被标记为 fail、或配置文件 IP 变更导致节点无法握手。当 cluster_slots_assigned 小于 16384 时，集群会拒绝写入请求以保护数据一致性。

步骤 1：诊断槽位状态

登录任意节点执行 cluster info，观察 cluster_slots_assigned 数值。若数值小于 16384，说明存在未分配槽位。

步骤 2：尝试自动修复

使用集群修复工具自动补全槽位。命令：redis-cli `--cluster` fix <host>:<port>。该工具会检测槽位缺口并尝试从现有节点迁移槽位。

步骤 3：处理宕机节点

若节点无法恢复，需从集群元数据中移除。使用 CLUSTER FORGET <node-id> 命令在所有存活节点上执行，清除故障节点记录。

步骤 4：重新分配槽位

若自动修复失败，需手动分配。使用 CLUSTER ADDSLOTS <slot> 将未分配的槽位指派给存活主节点。操作前务必确认目标节点数据为空或已同步。

步骤 5：极端情况重置

若集群配置严重混乱，可停止所有节点，删除 nodes.conf 文件，重新初始化集群。此操作风险极高，仅在有备份且无法修复时使用。

执行 cluster info 命令，确认 cluster_state 显示为 ok。检查 cluster_slots_ok 数值是否等于 16384。使用客户端执行 set/get 命令，确认不再返回 CLUSTERDOWN 错误。

查看日志文件 redis.log，确认不再出现 Cluster state changed: fail 或 Connection refused 相关报错。

IP 地址变更未更新：节点重启后 IP 变化但未更新 cluster-announce-ip 配置，导致其他节点无法连接。需修改配置文件并重启。

多数派主节点丢失：若超过半数主节点宕机，集群无法选举新主，此时修复单个节点无效，需恢复足够数量的主节点。

nodes.conf 文件残留：故障节点重启后若保留旧的 nodes.conf，可能携带错误的集群拓扑信息。重置前建议备份并清理该文件。

不会直接丢失，但无法写入。若强制重置集群且无备份，未持久化的数据可能丢失。

无法规避，必须修复集群状态。客户端可配置重试机制，但服务端必须恢复 slot 覆盖。

自动修复通常不需要停机。若需删除节点或重置配置，则涉及重启服务，会产生短暂中断。