Valkey 如何用 FAILOVER 命令完成一次手动的主从切换【免费下载链接】placeholderkvA flexible distributed key-value database that is optimized for caching and other realtime workloads.项目地址: https://gitcode.com/GitHub_Trending/pl/placeholderkv在 Valkey 的主从部署中如果需要主动把写流量从当前主节点切走而不是等主节点故障后才被动切换可以直接在主节点上执行FAILOVER命令让它和某个副本完成一次协调切换。该命令自 6.2.0 起提供属于 server 命令组成功受理时回复OK见 src/commands/failover.json。使用前提命令必须发给主节点且主节点当前至少有一个已连接的副本切换期间主节点会暂停写命令切换完成后原主节点自动降级为副本。FAILOVER 命令的语法与语义命令语法为FAILOVER [TO host port [FORCE]] [ABORT] [TIMEOUT milliseconds]各部分的含义见 src/replication.c 中的实现注释与参数解析TO host port指定要提升为新的主节点的具体副本。不带TO时由主节点从已连接的副本中自行选择。TIMEOUT milliseconds主节点等待副本追上同步流的时长毫秒必须大于 0。不指定时主节点会一直等待只能用ABORT手动取消。FORCE即使目标副本没有追上同步也强行切换。必须与TIMEOUT和目标host/port一起使用。ABORT取消正在进行中的 failover。这是唯一的取消方式因为 failover 进行期间REPLICAOF被禁用如果没有 failover 在进行中会报错No failover in progress.命令实现注释中描述的“正常路径”共四步主节点发起 client pause write停止写流量主节点周期性检查副本是否已通过 ack 消费完整个同步流目标副本追上后主节点将自己降级为副本主节点向目标副本发送PSYNC FAILOVER请求副本接受后升为主节点并开始同步。也就是说回复OK只表示命令被接受切换是否完成要看后续状态。执行主路径以下用primary-host:primary-port表示待切换的主节点、target-host:target-port表示要提升的副本均为占位符请替换为你部署中的实际地址。第 1 步确认复制关系已建立。先让目标副本复制主节点在副本上执行REPLICAOF primary-host primary-port然后在各节点用ROLE确认当前角色主节点一侧输出应体现 master副本一侧输出应体现 slave官方集成测试 tests/integration/failover.tcl 就是按*master*/*slave*匹配ROLE输出来验证角色的。没有在线副本时执行FAILOVER会直接报FAILOVER requires connected replicas.。第 2 步在主节点上发起切换。连到主节点执行FAILOVER TO target-host target-port回复OK即被接受。此时主节点日志中会出现FAILOVER requested to host:port.未指定TO时日志为FAILOVER requested to any replica.写命令进入暂停状态。第 3 步观察进度直到结束。INFO输出中包含字段master_failover_state:见 src/server.c取值来自 src/replication.c 的状态机waiting-for-sync等待目标副本追上同步流failover-in-progress切换正在进行主节点已降级、副本正在提升no-failover已结束——切换成功或已中止角色以实际ROLE输出为准。官方集成测试以状态回到no-failover作为一次 failover 结束的判断条件。第 4 步验证角色已交换。对每个节点执行ROLE目标副本target-host应显示为 master原主节点应显示为 slave。第 5 步把其余副本指向新主节点。FAILOVER只协调“旧主节点 目标副本”这一对节点集群里的其他副本不会自动改指向。官方测试在 3 节点场景中切换完成后手动对第三个副本执行REPLICAOF 新主地址并等待其同步完成wait_for_sync。如果你有多个副本对每一个非目标副本重复这一步。第 6 步核对数据一致性。集成测试用DEBUG DIGEST交叉比对各节点见 tests/integration/failover.tcl 中的assert_digests_match三节点摘要一致即认为切换没有丢数据。你可以在切换后对各节点执行DEBUG DIGEST做同样核对。超时、强制与中止带超时的普通切换FAILOVER TO target-host target-port TIMEOUT 500目标副本在 500 毫秒内没有追上同步流failover 自动中止各节点角色保持原样。强制切换FAILOVER TO target-host target-port TIMEOUT 100 FORCE超时后即使目标副本仍未追上也会执行切换日志出现time out exceeded, failing over.。注意切换完成后各节点会重新指向新主并补同步官方测试中切换前后DEBUG DIGEST一致但强制切换本身允许目标带着落后状态被提升。手动中止当状态为waiting-for-sync时在原主节点上执行FAILOVER ABORT状态回到no-failover角色不变。日志会记录FAILOVER to host:port aborted: 原因。另外切换成功结束时主节点上处于阻塞等待状态的客户端会被解除阻塞或重定向——测试中一个阻塞的BRPOP返回的错误为UNBLOCKED force unblock from blocking operation, instance state changed (master - replica?)。如果你的业务里有长阻塞命令BLPOP、BRPOP等需要按“客户端会收到 UNBLOCKED 错误”来预期结果。常见报错对照以下错误信息均来自failoverCommand的实现src/replication.c集成测试也逐项验证过错误信息出现场景FAILOVER is not valid when server is a replica.命令发给了副本而不是主节点FAILOVER requires connected replicas.主节点没有任何已连接的副本FAILOVER target HOST and PORT is not a replica.TO指定的地址不是当前已连接的副本含无效 host/portFAILOVER target replica is not online.目标副本存在但尚未同步完成、不在线FAILOVER with force option requires both a timeout and target HOST and IP.使用FORCE时缺少TIMEOUT或TO host portFAILOVER timeout must be greater than 0TIMEOUT值小于等于 0FAILOVER already in progress.上一次 failover 还未结束No failover in progress.执行FAILOVER ABORT时没有任何 failover 在进行此外目标副本如果在切换期间拒绝了psync例如 ACL 中移除了psync权限failover 会自动中止日志记录Failover target rejected psync request角色保持原样。可选分支Sentinel 侧触发同样的协调切换如果部署由 Sentinel 监控也可以从 Sentinel 端发起同一套协调切换流程SENTINEL FAILOVER primary-name [COORDINATED]COORDINATED选项自 9.0.0 提供它会寻求其他 Sentinel 的同意并走协调式 failover即上文FAILOVER的流程不带该选项时 failover 立即执行相当于把主节点视为不可达见 src/commands/sentinel-failover.json。官方测试 tests/sentinel/tests/17-manual-coordinated.tcl 给出的核对方式等待SENTINEL GET-PRIMARY-ADDR-BY-NAME primary-name返回的端口变为新主节点failover 进行期间再次执行该命令会返回带INPROG的错误若超时失败例如所有副本都拒绝了PSYNCSENTINEL PRIMARY primary-name的 flags 中不再包含failover_in_progress且原主从关系保持不变。参考命令定义src/commands/failover.json、src/commands/sentinel-failover.json实现与注释src/replication.c集成测试含执行、验证与错误分支的完整样例tests/integration/failover.tclSentinel 协调切换测试tests/sentinel/tests/17-manual-coordinated.tcl【免费下载链接】placeholderkvA flexible distributed key-value database that is optimized for caching and other realtime workloads.项目地址: https://gitcode.com/GitHub_Trending/pl/placeholderkv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考