📚 课程目录第2章集群搭建与初始化实战

2. 集群搭建与初始化实战

Redis Cluster 的搭建并不依赖额外中间件，核心工具就藏在 redis-cli 里。本节以三主三从、共 6 个节点为例，完整走一遍从配置文件准备、节点启动、集群创建到槽位与握手验证的过程。示例使用 7000～7005 六个端口，部署在同一台机器的不同端口上，便于教学观察；生产环境应分散到不同物理机或容器，并保证每个主节点至少有一个从节点位于不同故障域。

一、准备节点配置

集群模式必须显式开启，且每个节点要有独立的端口、数据目录和集群配置文件。下面给出 7000 端口的配置样例，其余节点只需替换端口号：

# redis-7000.conf
port 7000
cluster-enabled yes
cluster-config-file nodes-7000.conf
cluster-node-timeout 15000
appendonly yes
dir /data/redis/7000
daemonize yes
protected-mode no
bind 0.0.0.0

其中 cluster-enabled yes 是集群开关，cluster-config-file 由 Redis 自动维护，记录本节点看到的集群拓扑、槽位归属和纪元信息，不要手工编辑。cluster-node-timeout 决定节点失联多久被判定为疑似下线，示例取 15 秒，网络抖动较大的环境可适当调大。六个节点依次启动：

for p in 7000 7001 7002 7003 7004 7005; do
  redis-server /etc/redis/redis-$p.conf
done
redis-cli -p 7000 cluster info

此时每个节点都是独立的单机实例，cluster_state 显示 fail，cluster_known_nodes 为 1，说明集群尚未形成，节点之间还没有握手。

二、执行 cluster create

集群创建由 redis-cli --cluster create 完成，它负责节点握手、槽位划分和主从指派三件事。命令格式为“主机:端口”列表，并用 --cluster-replicas 1 指定每个主节点配一个从节点：

redis-cli --cluster create \
  127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 \
  127.0.0.1:7003 127.0.0.1:7004 127.0.0.1:7005 \
  --cluster-replicas 1

执行后工具会打印一份分配预案，形如：

Master[0] -> Slots 0 - 5460
Master[1] -> Slots 5461 - 10922
Master[2] -> Slots 10923 - 16383
Adding replica 127.0.0.1:7004 to 127.0.0.1:7000
Adding replica 127.0.0.1:7005 to 127.0.0.1:7001
Adding replica 127.0.0.1:7003 to 127.0.0.1:7002

这里有一个容易踩坑的规则：命令中前 N 个地址被视为主节点，后 N 个被视为从节点，从节点按顺序分配给主节点。因此地址顺序不能随意打乱，否则主从对应关系会与预期不符。确认预案无误后输入 yes，工具开始执行 CLUSTER MEET 握手、CLUSTER ADDSLOTS 分配槽位、CLUSTER REPLICATE 建立复制，最后输出 [OK] All 16384 slots covered，表示 16384 个槽位全部有主。

若提示 Not all 16384 slots are covered，说明有槽位未分配，通常是节点数不足或地址列表有误；若提示节点已有数据，需先清空数据目录再重建。

三、验证槽位分配与节点握手

创建完成后，用 cluster info 看整体状态，用 cluster nodes 看每个节点的角色、槽位区间和连接状态：

redis-cli -p 7000 cluster info
redis-cli -p 7000 cluster nodes

cluster info 中应看到 cluster_state:ok、cluster_slots_assigned:16384、cluster_known_nodes:6、cluster_size:3。cluster nodes 每行格式为“节点ID IP:端口标志主节点ID 时间戳纪元连接状态槽位”，主节点标志为 master 并带槽位区间，从节点标志为 slave 并指向其主节点ID，连接状态应为 connected。若某行显示 disconnected 或 handshake，说明握手未完成，需检查端口连通性与 cluster-node-timeout。

槽位是否真正生效，最直接的验证是写入一个键并观察重定向。集群客户端在收到 MOVED 后会自动跳转，而单机模式下的 redis-cli 需要加 -c 才会跟随重定向：

redis-cli -c -p 7000 set user:1001 alice
redis-cli -c -p 7000 get user:1001
redis-cli -p 7000 cluster keyslot user:1001

cluster keyslot 返回该键所属槽位，例如返回 12345，则它应由负责 10923–16383 区间的 7002 节点处理。若在 7000 上执行 set 时看到 MOVED 12345 127.0.0.1:7002，正说明槽位路由按预期工作。还可以用 redis-cli --cluster check 127.0.0.1:7000 做一次全量体检，它会列出每个主节点的槽位覆盖、从节点数量和键分布，是排查槽位缺口与主从不匹配的高效手段。

四、常见初始化问题与判断依据

初始化阶段的问题大多集中在三类。第一类是握手失败：cluster nodes 中出现 handshake 状态，通常是节点间端口不通，或 bind 与防火墙限制了集群总线端口（业务端口 + 10000，如 7000 对应 17000）。第二类是槽位未全覆盖：cluster info 中 cluster_slots_assigned 小于 16384，集群状态为 fail，此时任何写入都会返回 CLUSTERDOWN Hash slot not served，需要用 --cluster addslots 或 --cluster fix 补齐。第三类是主从错配：从节点挂到了非预期的主节点上，可用 CLUSTER REPLICATE <node-id> 在目标从节点上重新指定。

判断集群是否真正可用，建议按以下顺序核对：cluster_state 是否为 ok；cluster_slots_assigned 是否为 16384；cluster_known_nodes 是否为 6；每个主节点是否都有且仅有一个从节点；cluster nodes 中所有连接状态是否为 connected。五项全部满足，才算完成一次合格的集群初始化。此后才适合进入槽位迁移、扩缩容与故障转移等后续操作。