在 Redis 主从、Sentinel 或 Cluster 部署中完成一次可控的主节点切换，覆盖只读副本提升、客户端重连、脑裂隔离与数据丢失窗口核算

适用场景

• Sentinel 主从集群的计划内维护、主机更换、机房迁移，需要把主节点有序切到副本。
• 主节点宕机、网络分区或进程故障后的故障转移，需要判断哪台副本可以提升，以及可能丢失多少写入。
• Redis Cluster 中某个分片的主节点替换、副本提升、槽位归属变化，以及客户端槽位刷新。
• 切换演练、变更评审和值班交接，需要把判断依据、验证步骤与回滚边界写成清单。
• 不适用：单机无副本且数据可重建的纯缓存、可接受冷启动的临时实例。云托管 Redis 的故障转移通常由服务商控制，本流程用于验证、流量切换和回切，具体操作以厂商文档为准。

计划内切换应先冻结写入、等待复制追平并记录偏移，才可能把目标定为零丢失；故障转移发生在主节点不可用时，必须接受未复制写入的丢失，优先选择偏移最靠前的副本。自动故障转移时，Sentinel 依赖 Sentinel 多数派与 quorum，Cluster 依赖分片主节点多数派与槽位覆盖，两者判断条件不能混用；手工触发切换并不等于自动获得这些协调语义。

前置检查

1. 确认部署形态和实际拓扑，不要只看配置文件或监控面板。向节点查询角色、副本和槽位：

redis-cli -h <node> -p <port> INFO replication
redis-cli -h <node> -p <port> CLUSTER INFO
redis-cli -h <node> -p <port> CLUSTER NODES
redis-cli -h <sentinel> -p <sentinel-port> SENTINEL masters
redis-cli -h <sentinel> -p <sentinel-port> SENTINEL get-master-addr-by-name <master-name>

记录主节点 ID、副本地址、master_link_status、master_last_io_seconds_ago 和复制偏移。Cluster 还要记录槽位覆盖、每个主节点的槽区间、集群状态与 fail/pfail 标记。

2. 评估复制健康和数据边界。在主节点查看 master_repl_offset、connected_slaves 和复制积压，在副本查看 slave_repl_offset、slave_read_only 和最后通信时间：

redis-cli -h <master> -p <port> INFO replication
redis-cli -h <master> -p <port> INFO persistence

Redis 复制是异步的，主节点写入成功不等于副本已确认，要评估“已写入主节点、尚未传播到副本”的窗口。WAIT 只对当前连接此前的写入生效，不能提供事务式强一致。同时记录 RDB 最近保存时间、AOF 状态和磁盘余量，确认副本有可用持久化文件。

3. 检查脑裂防护。Sentinel 侧查看 quorum、down-after-milliseconds、failover-timeout、parallel-syncs，确认多数派健康。主从侧检查 min-replicas-to-write 与 min-replicas-max-lag 是否成对配置，它们不能替代网络隔离。Cluster 侧检查 cluster-node-timeout、cluster-require-full-coverage 和节点连通性，失去多数派时不要强行制造第二个主节点。

4. 盘点客户端和发现方式。列出使用 Sentinel 感知客户端、Cluster 槽位感知客户端、直连地址、VIP、DNS、代理或连接池的应用，确认客户端能订阅 +switch-master、处理 MOVED 和 ASK，重连超时合理。直连旧主节点且不会自动发现拓扑的客户端是双写和报错的主要来源，必须在窗口前改造或停止。

5. 准备隔离手段。故障转移前必须能迅速让旧主节点停止写入，例如撤销网络访问、摘除 VIP、关闭端口或停止进程。只设只读不够，已有连接和管理脚本仍可能写入；要同时排空连接池，确认没有绕过代理的写入方。

6. 备份与回滚材料。切换前对每个主节点做可验证的快照或 AOF 备份，保留配置、Sentinel 状态、Cluster 节点信息和当前偏移。旧主节点重新加入时会被配置为副本并按权威数据同步，未传播的写入可能被丢弃，必要时先留快照供核对。

7. 约定窗口、RPO/RTO 和验收标准。暂停批量写入、定时任务和数据迁移；通知业务方成功标准，例如关键 key 可读写、计数器不回退、会话仍有效。故障转移还要明确谁有权决定提升、谁负责隔离旧主节点、数据丢失如何说明。

操作步骤

1. 固定基线并冻结变更

记录主从和 Sentinel 状态，保存关键 key 的数量、类型、值和 TTL 样本。不要在生产使用 KEYS，优先用 INFO keyspace、DBSIZE 和有限模式的 SCAN：

redis-cli -h <master> -p <port> INFO all > /backup/redis-info-before.txt
redis-cli -h <master> -p <port> INFO keyspace > /backup/redis-keyspace-before.txt
redis-cli -h <master> -p <port> --scan --pattern 'order:*' | head -50 > /backup/redis-key-sample.txt

Cluster 要对每个主节点分别记录槽位、键数量和偏移。无法完全冻结写入时，至少把写入降到可控水平，并在验收时区分正常业务变化与切换丢失。

2. 计划内 Sentinel 切换

Sentinel 管理的集群优先通过 Sentinel 触发切换，而不是先在副本上手工执行 REPLICAOF NO ONE。但 SENTINEL FAILOVER 是把主节点当作失联来强制切换，不会替你暂停旧主写入或等待副本追平；计划内切换要先由应用侧冻结写入（或至少暂停非关键写入）、确认目标副本偏移已追平，并准备切断旧主的客户端入口，然后再触发：

# 只有在写入已冻结、副本偏移已追平后才执行；触发前后都要隔离旧主
redis-cli -h <sentinel> -p <sentinel-port> SENTINEL FAILOVER <master-name>
redis-cli -h <sentinel> -p <sentinel-port> SENTINEL get-master-addr-by-name <master-name>

持续观察 Sentinel 日志中的 +switch-master、+promoted-slave 事件和新主节点状态。切换期间写入可能短暂失败，应用应能重试；只读设置不能阻止旧主继续接收已有连接，必须同时撤销入口、VIP 或网络访问。状态未收敛时不要重复发起切换，否则会造成多次提升和反复全量同步。

3. Cluster 分片主节点切换

计划内替换主节点，优先在目标副本上执行 CLUSTER FAILOVER。默认模式会协调主节点暂停写入、副本追平后切换；FORCE 用于主节点不可达但仍有多数派的场景，可能丢失未同步写入；TAKEOVER 不经其他主节点同意，只用于接受脑裂和数据丢失的灾难恢复，不能当作常规手段：

redis-cli -h <replica> -p <port> CLUSTER FAILOVER
redis-cli -h <node> -p <port> CLUSTER INFO
redis-cli -h <node> -p <port> CLUSTER SHARDS

确认 cluster_state:ok、槽位全部覆盖、目标副本持有原槽位、旧主节点变成副本且复制正常。若切换卡住，先检查节点连通性、多数派、槽位迁移和日志，不要连续重试或直接使用 TAKEOVER。

4. 故障转移与只读副本提升

主节点已不可用时，先隔离旧主节点，再从副本中选择偏移最靠前、持久化健康、网络和磁盘正常的一台。纯主从部署可以手工提升：

redis-cli -h <replica> -p <port> REPLICAOF NO ONE
redis-cli -h <replica> -p <port> INFO replication
redis-cli -h <other-replica> -p <port> REPLICAOF <new-master> <port>

确认 role:master 且可以写入后，把其他副本指向新主节点。旧主节点必须保持隔离，确认没有需要保留的未同步写入后，才能作为副本重新加入；重新加入通常触发全量同步，分叉数据会被覆盖。

Sentinel 部署不要绕过 Sentinel 手工提升，否则它可能仍认为旧主节点是主。应使用 SENTINEL FAILOVER 或让 Sentinel 自动完成；Sentinel 失去多数派时先恢复网络和 quorum。Cluster 失去主节点多数派时无法安全选主，应优先恢复网络，不要在少数派上强行提升。

5. 客户端重连与流量切换

Sentinel 客户端应在收到 +switch-master 后重建连接池，Cluster 客户端应刷新槽位并正确处理 MOVED。更新 DNS、VIP、负载均衡或代理时提前降低 TTL；切换后滚动重启或排空连接池，确认没有进程仍持有旧主节点连接。先放少量流量做金丝雀，再逐步扩大。

redis-cli -h <new-master> -p <port> CLIENT LIST
redis-cli -h <new-master> -p <port> INFO clients
redis-cli -h <new-master> -p <port> INFO commandstats

CLIENT LIST 用于确认连接来源和数量，不建议在高峰长期开启 MONITOR。发现明确卡住的连接时按客户端 ID 精确清理，不要无差别杀掉全部连接。观察错误率、延迟、重连次数和慢查询，确认客户端没有在旧主节点和新主节点之间反复切换。

6. 重建旧节点并收尾

把旧主节点重建为副本，等待同步完成，确认偏移追平、master_link_status:up、副本可读。Sentinel 部署确认配置已收敛；Cluster 部署确认旧节点以副本身份加入、槽位归属正确。恢复批处理和定时任务，更新文档与告警，并制作新备份。

验证

• 新主节点 role:master，写入、读取和删除正常；副本 master_link_status:up，偏移持续接近新主节点。
• Sentinel 返回新主节点地址，没有持续 sdown/odown 抖动，日志没有反复切换；Cluster 的 cluster_state:ok、槽位全覆盖、每个主节点都有健康副本。
• 关键 key 的数量、类型、值和 TTL 与基线一致或在业务可解释范围内；写入 canary、计数器、会话和过期键验证通过。
• 应用连接池、队列和缓存命中率恢复，错误率和延迟回到基线，没有持续 MOVED、READONLY 或连接超时。
• 旧主节点处于隔离或副本状态，没有继续接受写入；所有客户端、代理和监控都指向新拓扑。
• 持久化、复制积压、磁盘和备份任务正常；故障转移已量化未复制写入的范围并记录 RPO。

失败与回滚

新主节点无法写入或提升失败。 立即隔离该节点，从剩余副本中选择偏移最靠前的一台重新提升；不要把旧主节点直接放回写入池。记录已切换的客户端和可能丢失的写入，业务侧暂停非关键写操作。

出现脑裂。 两侧都能写入时，先停止一侧，比较复制偏移、键数量、关键 key 内容和业务日志，确定唯一权威数据源；另一侧必须重建或从备份恢复，不能手工合并猜测。旧主节点重新接纳时可能全量同步并丢弃分叉写入，要在同步前保存快照并评估损失。

Sentinel 失去多数派或反复切换。 暂停自动故障转移操作，检查 Sentinel 之间的网络、时钟、配置和 quorum，确认没有两个 Sentinel 集合管理同一主节点。恢复多数派后再让 Sentinel 收敛，不要通过手工删除配置来“修复”状态。 Cluster 失去多数派。 不要用 TAKEOVER 绕过多数派，除非已接受脑裂和数据丢失并由决策人批准。优先恢复节点间网络、重启故障节点、确认槽位和节点 ID；恢复后检查是否有分叉写入需要业务核对。

客户端仍连旧主节点。 保持旧主节点只读或隔离，检查 DNS TTL、VIP、代理、连接池和直连配置，逐步重启或排空应用。不要为了恢复应用而放开旧主节点写入，否则会把切换变成双写事故。

需要回滚。 计划内切换且旧主节点已追平时，可以按对称步骤切回：冻结写入、确认追平、触发提升、切换入口、重建新主节点为副本。故障转移后的回滚要更保守，先确认数据一致、没有双写，再把回滚当成一次新变更重新评审，并保留双方快照、量化写入差异。

相关命令

• redis-cluster — Cluster 拓扑、槽位与副本管理
• redis-sentinel — Sentinel 部署、监控与故障转移
• redis-cli — 连接、状态查询与在线排障
• redis-cluster-failover — 分片主节点切换异常排查
• redis-connection-failed — 切换后的连接与重连问题
• build-redis-cluster — 从零搭建 Cluster 并验证副本
• redis-cheatsheet — 常用命令与状态字段速查
• migrate-redis-to-valkey — 替换引擎时的兼容性与切换考量
• redis-operator — Kubernetes 上的 Redis 高可用编排
• lab-redis-failover — 在 Redis 主从/Sentinel 或 Cluster 中演练切换、客户端重连与双主隔离。

参考链接

• Redis: Replication
• Redis: Sentinel

读完自测

合上页面，先回答，再展开对照。

1. Sentinel 的手动切换和 Cluster 的 CLUSTER FAILOVER 分别在什么条件下才能安全执行？
2. 为什么故障转移前必须先隔离旧主节点，而不是只在它上面设置只读？
3. 切换后发现旧主节点上有未同步的写入，应该怎样处理？