Redis CLIENT PAUSE WRITE 的主节点切换步骤与写入保护边界

Redis 主节点升级或故障转移时，最怕旧主节点在切换窗口里继续接受写入。CLIENT PAUSE WRITE适合做这道短暂的写入闸门：它暂停写命令，让控制连接继续观察复制状态并完成切换；切到新主节点后，再用CLIENT UNPAUSE恢复暂停的客户端。它不是自动选主、复制追平或客户端重连工具，三个动作仍要由运维流程负责。

官方地址：https://redis.io/docs/latest/commands/CLIENT-PAUSE/

CLIENT PAUSE WRITE 保护的到底是什么

命令语法是CLIENT PAUSE timeout [WRITE | ALL]，时间单位为毫秒。WRITE只针对写命令建立阻塞，ALL则把所有客户端命令都纳入暂停范围。Redis 官方从 6.2 开始提供WRITE模式，并将它作为主节点切换时更合适的模式。

要点在于“暂停客户端处理”，而不是“冻结复制拓扑”。旧主节点仍然是旧主节点，候选副本也不会因为这条命令自动提升。暂停发起者会尽快拿到OK，所以实际切换需要另一个控制连接继续读取复制状态、确认候选副本已接近目标位置，再执行提升和连接迁移。

一套可回滚的主节点切换写入保护

下面的命令只展示控制面意图，地址、认证和副本提升方式应替换为实际环境的值。关键是控制连接与业务连接分开，避免业务连接被暂停后，运维人员也失去观察通道。

# 在旧主节点建立 5 秒写入保护窗口，单位是毫秒
redis-cli -h old-primary CLIENT PAUSE 5000 WRITE

# 用独立控制连接观察复制信息，不把观察动作混入业务连接
redis-cli -h old-primary INFO replication
redis-cli -h candidate-replica ROLE

# 完成副本提升和客户端指向切换后，在新主节点恢复暂停客户端
redis-cli -h new-primary CLIENT UNPAUSE

操作顺序可以拆成四个判断：先确认副本健康，再暂停旧主节点写入；然后在窗口内确认复制进度并完成副本提升；接着把客户端连接指向新主节点；最后执行CLIENT UNPAUSE。如果复制状态、提升动作或连接迁移超过timeout，就不应继续假设数据已经安全切换，应回滚或重新发起更长但仍受控的窗口。

WRITE、ALL 和 UNPAUSE 怎么分工

WRITE也不是“只影响普通 SET”。官方说明中，EVAL、EVALSHA、PUBLISH、PFCOUNT等命令在 WRITE 模式下有特殊阻塞行为，WAIT的确认也会延后。因此，如果切换脚本把这些命令当作控制信号，必须先把它们的影响纳入演练，不要只测试一个普通写请求。

哪些情况不适合直接使用 CLIENT PAUSE

它不负责选举新主节点，也不负责把副本复制到某个确定 offset，更不会自动修改应用连接池。Sentinel、Cluster 或自建故障转移编排仍需要自己的健康检查和路由切换；CLIENT PAUSE只是把旧主节点继续接收写入的窗口收窄。

生产上还要提前演练三件事：暂停期间连接池如何处理超时，切换失败时旧主节点如何安全恢复，以及新主节点恢复后积压请求是否会形成突发写入。若业务必须完全静默，才考虑ALL；若只需保护数据不被旧主继续改写，通常从WRITE开始更容易控制影响面。

总结与相关问题

把这条命令记成“切换前的写入闸门”即可：WRITE负责减少旧主写入，控制连接负责观察与切换，UNPAUSE负责在新主准备好后恢复请求。窗口时间、复制状态和回滚动作必须属于同一套演练方案。

CLIENT PAUSE WRITE 会自动把副本变成主节点吗？

不会。它只暂停客户端命令处理，副本提升、连接路由和故障转移仍由 Sentinel、Cluster 或运维编排完成。

为什么不直接使用 ALL？

ALL 会扩大影响范围，读请求和部分控制操作也可能被延迟。只有需要整体静默且维护窗口很短时才考虑它，普通主节点切换优先评估 WRITE。

暂停超时后能否认为切换成功？

不能。超时只表示暂停窗口结束，必须重新读取拓扑和复制状态，确认客户端是否已经指向新主节点。