3.1 Shard 的含义#

一个逻辑分片通常由：

• 一个负责槽位和读写的 master。
• 零个、一个或多个保存该 master 数据副本的 replica。

1
Shard = Master + Replicas

replica 默认不负责该分片的业务写入。master 故障后，合格 replica 可以通过集群选举被提升。

3.2 最小与推荐节点数#

Redis 官方文档指出：

• 正常工作的最小集群需要至少 3 个 master。
• 生产通常至少使用 3 master + 3 replica。

三个 master 的原因：

• 故障确认和 replica 提升需要 master 多数派参与。
• 两个 master 无法形成稳健的多数派容错结构。

六节点也不是所有生产系统的固定答案。实际副本数还取决于：

• 可用区数量。
• 允许的故障范围。
• 数据恢复目标。
• 内存成本。
• 跨可用区网络质量。

3.3 故障域部署#

生产建议：

• 同一 shard 的 master 与 replica 不部署在同一宿主机。
• replica 尽量位于不同机架或可用区。
• 不要把三个 master 全部放在同一故障域。
• 节点之间的客户端端口和 Cluster Bus 端口都必须互通。
• 客户端必须能访问集群通告出来的所有节点地址。

4.1 Key 绑定的是槽位，不是物理节点#

需要理解：

• key 经过哈希计算后属于某个 slot。
• slot 当前归某个 master 管理。
• 扩缩容时迁移的是 slot 及其 key。
• key 的 slot 通常不会变化，但 slot 的负责节点可以变化。

因此客户端维护的是：

1
slot → master 地址

而不是：

1
key → 永久固定节点

4.2 查看 key 的槽位#

1
CLUSTER KEYSLOT user:1001

示例：

1
CLUSTER KEYSLOT foo{order:1001}
2
CLUSTER KEYSLOT bar{order:1001}

两者使用相同 Hash Tag，返回相同 slot。

5.1 精确规则#

只有同时满足以下条件才使用 Hash Tag：

1. key 包含 {。
2. 在该 { 右侧存在 }。
3. 第一个匹配的 { 和其右侧第一个 } 之间至少有一个字符。

5.2 Hash Tag 的用途#

Hash Tag 主要用于：

• 让多 key 命令中的所有 key 位于同一槽位。
• 让 Lua 脚本或事务涉及的 key 位于同一槽位。
• 将同一业务聚合的相关数据放入同一个 shard。

示例：

1
MSET order:{1001}:status paid order:{1001}:amount 99
2
MGET order:{1001}:status order:{1001}:amount

5.3 Hash Tag 的风险#

Hash Tag 不是越多越好。设计不当会产生热点：

1
所有商品 key 都使用 {product}
2
                 ↓
3
所有商品落入同一个 slot
4
                 ↓
5
一个 master 承担绝大多数流量和内存

建议：

• Tag 颗粒度使用租户 ID、用户 ID、订单 ID 等业务聚合标识。
• 不要让所有业务 key 共享同一个 Tag。
• 在保证多 key 原子操作的同时保持槽位分布均衡。
• 监控 hot key、big key 和各 master 的内存、QPS 差异。

6.1 受影响的操作#

需要特别检查：

• MGET、MSET
• 集合的交、并、差运算
• RENAME、RENAMENX
• 事务 MULTI/EXEC
• Lua 脚本和 Redis Functions
• 涉及多个 key 的阻塞命令
• pipeline 中要求服务端原子或同节点执行的业务

有些客户端会把部分跨槽操作拆成多次单 key 请求并在客户端合并结果，但这会改变：

• 原子性。
• 网络开销。
• 错误语义。
• 返回时延。

不能因为客户端“能够执行”就假定它仍等同于单机上的一个原子命令。

6.2 Lua 脚本和事务#

脚本或事务所访问的 key 应：

• 在调用时显式声明。
• 全部属于同一槽位。
• 不要在脚本内部动态拼接并访问未知跨槽 key。

典型分布式锁的锁 key、状态 key 和 fencing token 如需同一脚本操作，应使用相同 Hash Tag。

7.1 Cluster Bus 用途#

• 节点握手和自动发现。
• PING/PONG 心跳。
• Gossip 故障信息传播。
• 槽位映射和配置纪元传播。
• master 故障确认。
• replica 选举与提升。
• Pub/Sub 和其他集群内部消息。

7.2 全连接拓扑#

集群节点之间维持全连接关系：

1
N 个节点中，每个节点维护到其他节点的连接。

业务客户端不应直接使用 Cluster Bus 协议；客户端只连接普通 Redis 数据端口。

7.3 防火墙要求#

每个节点至少需要：

• 客户端数据端口对客户端和集群节点开放。
• Cluster Bus 端口对其他集群节点开放。

如果只开放数据端口、不开放 Bus 端口：

• 单节点可能仍能被 redis-cli 连接。
• 但节点无法正常交换集群消息。
• 故障检测、槽位传播和故障转移会异常。

Cluster Bus 端口不应暴露到不可信公网。

8.1 Node ID#

每个 Cluster 节点都有持久化 Node ID，例如：

1
07c37dfeb235213a872192d90877d0cd55635b91

Node ID：

• 在节点首次启动时生成。
• 存储在集群配置文件中。
• 节点地址改变时通常仍保持不变。
• 用于复制关系、槽位归属和集群命令。

8.2 nodes.conf#

配置示例：

1
cluster-config-file nodes-7001.conf

该文件由 Redis 自动维护，保存：

• Node ID。
• 已知节点。
• master/replica 关系。
• 槽位归属。
• 配置纪元。
• 故障和迁槽状态。

注意：

• 不应手工编辑 nodes.conf。
• 每个 Redis 进程必须使用独立文件。
• 文件所在目录必须可写。
• 同一主机多个实例不能共用一个 nodes.conf。
• 删除或错误复制该文件可能改变节点身份并破坏拓扑。

8.3 configEpoch#

configEpoch 是槽位配置的逻辑版本：

• 故障转移会生成新的、递增且唯一的配置纪元。
• 如果多个节点声称拥有同一槽位，较新的配置纪元优先。
• 网络分区恢复后，旧节点会接受更新的槽位配置。

9.1 MOVED：永久槽位归属重定向#

客户端向错误节点发送：

1
GET order:1001

节点可能返回：

1
-MOVED 3999 192.168.150.102:7002

含义：

• key 属于 slot 3999。
• slot 3999 当前由 192.168.150.102:7002 负责。
• 客户端应向该节点重新发送命令。
• 客户端应更新本地槽位映射。

1
Client ──GET key──→ Node A
2
Client ←─MOVED──── Node A
3
Client ──GET key──→ Node B
4
Client ←─value──── Node B

9.2 ASK：迁槽期间的一次性重定向#

槽位正在从 A 迁移到 B 时，部分 key 已在 B，部分仍在 A。

源节点可能返回：

1
-ASK 3999 192.168.150.102:7002

客户端应：

1. 只把当前这一次命令发送到 B。
2. 先向 B 发送 ASKING。
3. 再发送原命令。
4. 不要立即永久修改本地 slot 映射。

1
Client ──GET key──→ Node A
2
Client ←──ASK───── Node A
3
Client ──ASKING──→ Node B
4
Client ──GET key──→ Node B
5
Client ←─value──── Node B

9.3 MOVED 与 ASK 对比#

9.4 redis-cli 的 -c#

普通连接：

1
redis-cli -p 7001

收到 MOVED 后只会显示错误。

Cluster 跟随重定向模式：

1
redis-cli -c -p 7001

-c 会帮助命令行客户端处理重定向。生产应用仍应使用真正支持 Redis Cluster 的客户端。

10.1 Seed 节点#

客户端配置中的节点列表是启动入口，不是静态完整拓扑。

建议：

• 配置多个位于不同故障域的 seed 节点。
• 不必在所有客户端中列出每一个节点，但不能只依赖一个节点。
• 客户端发现的节点地址必须从客户端网络可达。
• 故障转移和扩容后允许客户端刷新拓扑。

11.1 配置项说明#

11.2 不要照搬实验安全配置#

讲义实验中使用：

1
bind 0.0.0.0
2
protected-mode no

这只适合隔离实验环境。生产应：

• 绑定明确的内网地址。
• 保持保护机制。
• 配置 ACL 和强密码。
• 使用防火墙限制客户端端口。
• Cluster Bus 只允许集群节点访问。
• 跨不可信网络时启用 TLS。

14.1 CLUSTER INFO#

1
CLUSTER INFO

常见字段：

14.2 CLUSTER NODES#

1
CLUSTER NODES

每行包含：

1
node-id endpoint flags master-id ping-sent pong-recv config-epoch link-state slots

常见 flags：

14.3 CLUSTER SHARDS#

1
CLUSTER SHARDS

用于查看：

• shard 的槽位范围。
• master 节点。
• replica 节点。
• 节点 endpoint、角色和健康状态。

它比手工解析 CLUSTER NODES 更适合新客户端获取拓扑。

15.1 添加空节点#

1
redis-cli --cluster add-node \
2
  192.168.150.101:7004 \
3
  192.168.150.101:7001

参数含义：

• 第一个地址是新节点。
• 第二个地址是集群中任意一个可达的已有节点。

检查：

1
redis-cli -p 7001 CLUSTER NODES

此时 7004 通常是：

1
master，0 slots

15.2 迁移槽位#

交互式 reshard：

1
redis-cli --cluster reshard 192.168.150.101:7001

需要指定：

1. 迁移多少个槽位。
2. 接收槽位的新 master Node ID。
3. 从哪些源 master 迁移。

也可以在自动化中提供对应 --cluster-* 参数，但生产迁移前应先在目标版本的 redis-cli --cluster help 中确认语法。

15.3 槽位迁移的内部状态#

假设 slot 2765 从 A 迁移到 B：

1
1. B 将 2765 标记为 IMPORTING，来源 A
2
2. A 将 2765 标记为 MIGRATING，目标 B
3
3. 从 A 获取该槽位中的 key
4
4. 使用 MIGRATE 将 key 原子地移动到 B
5
5. B 成为 2765 的正式 owner
6
6. A 和其他 master 更新 slot 2765 的归属

底层涉及：

1
CLUSTER SETSLOT 2765 IMPORTING <source-node-id>
2
CLUSTER SETSLOT 2765 MIGRATING <target-node-id>
3
CLUSTER GETKEYSINSLOT 2765 100
4
MIGRATE ...
5
CLUSTER SETSLOT 2765 NODE <target-node-id>

通常应使用 redis-cli --cluster reshard，避免人工执行底层命令时顺序错误。

15.4 迁移期间的请求行为#

源节点 A：

• key 仍在 A：直接处理。
• key 已经迁走或新 key 不在 A：返回 ASK 到 B。

目标节点 B：

• 收到普通请求但尚未正式拥有槽位：通常返回 MOVED。
• 收到 ASKING 后的请求：允许处理该导入槽位的当前命令。

15.5 迁槽风险#

• big key 会延长单次迁移阻塞和网络传输时间。
• 热点槽位迁移时重定向和延迟可能增加。
• 多 key 命令在相关槽位迁移时可能返回 TRYAGAIN。
• 源和目标节点的内存峰值需要预留。
• 客户端必须正确支持 ASK。
• 迁移中断可能留下 MIGRATING/IMPORTING 状态。

迁移前应治理 big key，并在低峰期分批执行。

17.1 删除 replica#

1
redis-cli --cluster del-node \
2
  192.168.150.101:7001 \
3
  <replica-node-id>

17.2 删除 master#

master 必须先清空其槽位：

1. 将该 master 的所有槽位 reshard 到其他 master。
2. 确认它不再负责任何 slot。
3. 确认业务客户端拓扑已经刷新。
4. 再执行 del-node。

1
redis-cli --cluster del-node \
2
  192.168.150.101:7001 \
3
  <empty-master-node-id>

不能直接删除仍持有槽位的 master。

17.3 删除不可达故障节点#

故障节点不可连接时，普通 del-node 可能失败。可以根据实际版本和场景对每个节点执行：

1
CLUSTER FORGET <node-id>

或使用：

1
redis-cli --cluster call \
2
  192.168.150.101:7001 \
3
  CLUSTER FORGET <node-id>

执行前必须确认：

• 故障节点不会带着旧配置重新加入。
• 其槽位已经由新 master 正式接管。
• 集群中所有节点最终都忘记了该 Node ID。

19.1 PFAIL#

PFAIL 表示 Possible Failure：

某个节点根据自己的本地观察，认为另一个节点超过 cluster-node-timeout 没有正常响应。

1
单个节点的本地主观判断 → PFAIL

master 和 replica 都可以把其他节点标记为 PFAIL。

19.2 FAIL#

PFAIL 不足以触发 replica 提升。故障报告通过 Gossip 传播，当足够多的 master 在有效时间窗口内确认目标不可达时，目标进入 FAIL。

1
多数 master 的有效故障报告 → FAIL

19.3 与 Sentinel 的类比#

二者概念相似，但协议、角色和实现并不相同。

20.1 replica 参与提升的基本条件#

• 它的 master 已处于 FAIL。
• 原 master 负责至少一个槽位。
• replica 与 master 断链没有久到超过允许的新鲜度范围。
• replica 未被配置为禁止故障转移。
• 它能联系到足够 master 并获得选票。

20.2 数据更新程度与选举延迟#

同一 master 的多个 replica 会根据复制进度形成不同的选举延迟：

• offset 越新，通常越早尝试选举。
• offset 较旧，延迟更长。
• 最终只有一个 replica 获得多数 master 授权。

这与 Sentinel 中按 replica-priority → offset → run ID 选择候选节点的流程不同。

20.3 configEpoch 的作用#

新 master 获得新的配置纪元并广播：

• 自己现在负责原 master 的槽位。
• 其他节点采用更新的槽位配置。
• 旧 master 恢复后不能用旧配置夺回槽位。

21.1 cluster-require-full-coverage#

1
cluster-require-full-coverage yes

当任意槽位没有可用 owner 时，集群倾向停止接受查询，避免向客户端呈现不完整键空间。

设置为 no 时，仍有 owner 的槽位可以继续服务，但应用会得到“部分 key 可用、部分 key 不可用”的状态。

取舍：

不能只为了“高可用”就盲目改为 no，应根据业务是否能接受部分数据不可用来决定。

22.1 默认模式#

1
CLUSTER FAILOVER

简化流程：

1. replica 请求 master 暂停处理客户端写入。
2. master 把当前复制 offset 告诉 replica。
3. replica 等待自己追平该 offset。
4. replica 向其他 master 请求故障转移授权和新配置纪元。
5. replica 提升为 master 并广播配置。
6. 原 master 接受新配置并成为 replica。

默认模式最重视数据一致性，适合计划内切换。

22.2 FORCE#

1
CLUSTER FAILOVER FORCE

• 不与原 master 协调。
• 适用于原 master 无法访问，但集群仍可形成故障转移授权的情况。
• 仍需要 Cluster 的多数派授权。
• 可能丢失 replica 尚未收到的写入。

22.3 TAKEOVER#

1
CLUSTER FAILOVER TAKEOVER

• 跳过与原 master 的协调。
• 还绕过正常的集群多数派授权。
• 可能违反正常配置纪元和“最后一次故障转移获胜”的安全原则。
• 只应在明确理解网络分区和数据冲突风险时使用。

对比：

命令返回 OK 只表示故障转移已被调度，不等于已经成功。之后必须检查：

1
ROLE
2
INFO REPLICATION
3
CLUSTER NODES
4
CLUSTER SHARDS

24.1 少数派分区中的旧 master#

如果客户端仍能访问处于少数派网络中的旧 master，它可能在一段时间内接受写入。多数派一侧完成故障转移后，旧 master 恢复连接并采用新配置，少数派期间的独有写入可能丢失。

可以在所有可能成为 master 的节点配置：

1
min-replicas-to-write 1
2
min-replicas-max-lag 10

以限制无法连接足够 replica 的 master 继续写入的时间窗口。

代价是 replica 或网络异常时 master 可能拒绝写入。

24.2 WAIT#

关键写入可以评估：

1
SET order:{1001}:status paid
2
WAIT 1 1000

WAIT 能提高写入已经到达 replica 的概率，但不能：

• 将 Redis 变成强一致数据库。
• 保证写入已经按要求落盘。
• 替代 RDB、AOF 和独立备份。
• 消除网络分区中的全部数据丢失风险。

25.1 Cluster 不等于备份#

• 误删 key 会通过复制传播给 replica。
• 程序错误可以同时污染所有 shard。
• FLUSHALL、错误脚本或错误迁槽会影响整个集群。
• 多节点在线副本无法替代历史版本备份。

备份恢复必须考虑：

• 每个 shard 的备份时间点。
• 槽位映射和 Node ID。
• 恢复到新集群还是原集群。
• 跨 shard 数据的一致时间点。
• 恢复后的重新分片和客户端切换。

26.1 Seed 节点不必列出全部节点#

cluster.nodes 用于启动拓扑发现。客户端连接成功后会获取完整槽位和节点信息。

但建议至少配置多个不同故障域的可用入口。

26.2 Topology Refresh#

Lettuce 客户端应具备拓扑刷新能力：

• 启动时加载拓扑。
• 收到 MOVED 时刷新。
• 在故障转移和伸缩后更新连接。
• 可根据客户端版本配置周期刷新或自适应刷新。

具体属性名称和默认值随 Spring Boot / Lettuce 版本变化，应以项目依赖版本文档为准。

26.3 Replica 读取#

Lettuce 支持把部分读取路由到 replica，但要注意：

• 主从复制异步，可能读到旧数据。
• 写后立即读、锁、余额、库存等强时效业务应读 master。
• Cluster 的副本读取需要客户端支持并正确发送只读连接语义。
• replica 故障或提升后客户端必须刷新拓扑。

26.4 RedisTemplate 的集群操作#

1
ClusterOperations<String, Object> clusterOps =
2
        redisTemplate.opsForCluster();

集群级操作与普通 key 操作不同：

• 普通 key 命令由客户端按槽位路由。
• 查看所有节点、在指定节点执行命令等需要 Cluster API。
• 对单个节点执行 KEYS 只能看到该节点负责的数据。
• Spring Data Redis 的聚合集群操作可能向多个 master 并行发送命令，成本远高于单机命令。

27.1 只支持 DB 0#

Redis Cluster 不支持多个逻辑数据库：

1
SELECT 1

不可用于 Cluster。

业务隔离应使用：

• key 前缀。
• 不同集群。
• 不同 Redis 实例或托管数据库。
• ACL 权限。

27.2 KEYS 与 SCAN#

在某个节点执行：

1
KEYS *

只能看到该节点当前保存的 key，不等于整个集群。

全集群扫描需要：

1. 获取所有 master。
2. 分别对每个 master 使用 SCAN。
3. 聚合结果并处理拓扑变化。

生产中不要使用 KEYS * 扫描大型节点。

Redis 8.0 起，某些明确包含单槽 Hash Tag 的 glob pattern 可以只扫描对应槽位，但仍需以客户端和服务端实际版本行为为准。

27.3 Keyspace Notification#

keyspace notification 是节点本地事件，不会自动汇总整个 Cluster。监听随机单节点会漏掉其他 shard 的事件。

需要全集群事件时：

• 在所有 master 上建立订阅。
• 处理故障转移和拓扑刷新。
• 或使用更适合可靠事件传递的 Stream / 消息队列方案。

27.4 Pub/Sub#

传统 Pub/Sub 和分片 Pub/Sub 的传播范围及路由不同。高规模 Cluster 应根据 Redis 版本评估 Sharded Pub/Sub：

1
SSUBSCRIBE channel
2
SPUBLISH channel message

不要把普通 Pub/Sub 当作可靠消息队列。

集群状态#

1
CLUSTER INFO
2
CLUSTER NODES
3
CLUSTER SHARDS
4
CLUSTER LINKS
5
CLUSTER MYID

槽位与 key#

1
CLUSTER KEYSLOT <key>
2
CLUSTER COUNTKEYSINSLOT <slot>
3
CLUSTER GETKEYSINSLOT <slot> <count>

节点与复制#

1
CLUSTER REPLICAS <master-node-id>
2
CLUSTER REPLICATE <master-node-id>
3
ROLE
4
INFO REPLICATION

redis-cli 集群管理#

1
redis-cli --cluster help
2
redis-cli --cluster check <host:port>
3
redis-cli --cluster info <host:port>
4
redis-cli --cluster add-node <new> <existing>
5
redis-cli --cluster del-node <existing> <node-id>
6
redis-cli --cluster reshard <host:port>
7
redis-cli --cluster rebalance <host:port>
8
redis-cli --cluster fix <host:port>

--cluster fix 可能修改槽位状态和数据位置，执行前必须：

• 备份。
• 明确故障原因。
• 保存 CLUSTER NODES、CLUSTER INFO 和日志。
• 在可控窗口操作。