做MongoDB运维这行最常被问到的问题之一就是能不能手动让主节点下台、让备份节点顶上平时大家习惯了故障后数据库自动选主但真到了要做硬件维护、内核升级、或者验证高可用机制的时候才发现这种“被动等待”根本不够用。这时候真正能派上用场的就是rs.stepDown()这个命令。它做的事情很直接把当前主节点降级为从节点然后触发一次副本集选举让其他节点接管主角色。这篇文章围绕的就是一次完整的rs.stepDown()手动主从切换运维演练。我会从命令原理讲起把切换前要检查什么、怎么选目标节点、参数怎么定、切换后怎么验证、切完怎么回切以及我踩过的那些坑全部过一遍。适合正在维护 MongoDB 副本集、需要做计划内维护或容灾演练的运维同学也适合刚接手副本集、想搞懂主从切换机制的人。1. 为什么要手动切主rs.stepDown() 解决的真实痛点1.1 哪些场景非切不可很多人以为主从切换只在故障时才需要其实生产环境里“主动让主节点下台”的需求非常频繁。比如主节点所在的机器要升级内核、更换磁盘、迁移机房或者要做一次高负载压测这时候你总不希望等机器坏了再让数据库自己反应那样不可控因素太多。提前在主节点上执行一次手动切换让业务先平稳跑到其他节点上再对原主节点做操作才是正常的运维节奏。另一个典型场景是验证高可用机制本身。副本集能不能在主节点宕机后正确选主应用连接串配得对不对监控告警能不能在切换发生时及时捕捉这些如果不通过演练验证真出故障时就是一片混乱。rs.stepDown()就是这类演练中最核心的触发手段——它模拟了一次“优雅降级”你不会破坏数据又能真实观察整个选举链路。1.2 副本集高可用机制速览先说清楚 MongoDB 副本集是怎么维持主从关系的不然后面讲命令参数会一头雾水。副本集里每个节点通过心跳互相探测默认每 2 秒发一次超过 10 秒没有响应其他节点就认为这个成员失联了。一旦主节点失联有投票权的从节点会发起选举选举超时时间默认是 10 秒electionTimeoutMillis。选举遵循“多数派”原则副本集必须有超过半数的投票节点在线才能选出主节点。三节点副本集需要至少 2 个节点在线五节点副本集需要至少 3 个。选举结果受两个因素影响最大一个是节点的priority参数优先级高的会被优先选择另一个是节点数据的新鲜程度从节点需要尽量追平主节点的操作日志oplog才能避免赢得选举后出现数据回滚。1.3 rs.stepDown() 与 rs.freeze()、priority 调整的分工手动切换不只有rs.stepDown()一种手段还有rs.freeze()和修改节点priority它们各管一段组合使用才能让切换过程可控。rs.stepDown()的作用是让当前主节点主动放弃主角色并在指定时间内不参与选举。rs.freeze()则是让某个从节点在指定时间内冻结不参与选举。修改priority则是从规则层面改变选举偏好把某个节点配置成“更适合当主”。三者的区别可以用一张表看明白操作作用对象主要用途对选举的影响rs.stepDown(seconds)当前主节点主动降级触发新一轮选举当前节点在 seconds 秒内不能当选rs.freeze(seconds)任意从节点临时冻结某个候选者被冻结节点在 seconds 秒内不参与选举修改 priority任意节点调整节点的“领导意愿”优先级更高的从节点会优先赢得选举实际演练中最稳的组合方案是先用rs.freeze()锁住不期望当选的节点再把目标节点的 priority 调高最后执行rs.stepDown()交接主角色。这样选举结果完全由你控制而不是看节点之间的“运气”。2. 切换前的检查清单先确认这5件事再动手2.1 确认副本集当前状态执行任何切换操作前第一件事永远是先看清楚副本集的全貌。我用得最多的命令是rs.status()它会把每个成员的状态、健康情况、oplog 时间都展示出来。重点关注每个节点的stateStr正常情况下应该是一个 PRIMARY、两个 SECONDARY不能出现 RECOVERING、ROLLBACK、UNKNOWN 这些异常状态。mongosh --quiet --eval rs.status()看输出的时候不要只盯着整体状态还要注意每个成员的lastHeartbeatMessage有时候这个字段会提示“同步源异常”“配置不一致”之类的隐患。带--quiet是为了减少 shell 启动时的噪音让输出更干净。如果发现某个从节点的状态不对先修复再演练不要在带病状态下做切换否则切换后新主可能根本追不上数据。2.2 确定目标新主节点切换前必须明确一个问题这次想让谁成为新主如果副本集里所有节点 priority 都是 1那么rs.stepDown()之后谁赢选举是不确定的大概率是数据最新的节点但这不是你主动选择的结果。对于演练来说不可控就是风险。我的做法是先在rs.status()的 members 数组里确认每个节点的索引位置然后用rs.conf()查看当前 priority。比如希望 node2 成为新主就找到 node2 在 members 数组里的下标把它的 priority 临时改高。cfg rs.conf(); cfg.members.forEach((m, i) print(i, m.host, m.priority));这一步是为了准确修改配置避免改错节点。很多人直接凭感觉改members[1].priority结果发现 members 数组的下标跟主机名对不上reconfig 之后切到了完全没预期的节点上耽误时间不说还可能引发误判。2.3 检查同步延迟与oplog窗口主从切换最怕什么最怕新主节点数据落后太多接管后出现写冲突或读到旧数据。所以在动手前必须确认目标从节点的数据同步进度。最简单的方法是对比主节点和从节点的optimeDate时间差越小切换越安全。mongosh --quiet --eval let st rs.status(); st.members.forEach(m print(m.name, m.stateStr, m.optimeDate)); 如果发现某个从节点 lag 持续增长先排查复制异常原因等它追平再切换。另外还要检查 oplog 窗口够不够大用rs.printReplicationInfo()看一下 oplog 的时间跨度和已用大小。窗口太小的话如果从节点短暂断连再恢复可能直接因为 oplog 被覆盖而无法追上这种节点名义上是 SECONDARY实际已经失去复制能力了。2.4 检查业务连接串和请求量这一步经常被跳过但恰恰是最容易翻车的地方。应用连接到 MongoDB 副本集时URI 必须带上replicaSetrs0这样的参数驱动才能通过副本集监控机制感知主节点变化。如果连接串只写了mongodb://node1:27017,node2:27017,node3:27017没有指定 replicaSet驱动程序不会把这三个节点当成同一个副本集的成员主节点一旦切换应用可能会一直往旧主节点写数据然后收到NotWritablePrimary的报错。切换前还要看一眼当前的写入请求量。可以用mongostat --discover观察一段时间确认峰值和毛刺。演练最好安排在低峰期比如凌晨或者周末尽量避免在业务高峰强行切换。即使rs.stepDown()是优雅降级切换瞬间仍然可能产生短暂的不可写窗口对高 QPS 业务造成影响。提示如果业务侧无法接受任何写中断不建议在生产环境直接演练。要么先改造连接串和重试逻辑要么先在测试环境完整跑通流程再进入生产。3. 三节点副本集完整演练从 stepDown 到回切3.1 演练环境与目标设定我这里用一个三节点副本集作为示例节点分别叫 node1、node2、node3当前主节点是 node1。演练目标很明确手动把主角色从 node1 切换到 node2验证应用连接能自动感知验证监控能捕获角色变化最后再把主角色切回 node1验证回切流程。三节点副本集是最常见的生产拓扑既能满足多数派选举要求又不会太复杂。演练前请确认所有节点都在线rs.status()输出没有任何异常状态。同时确认应用已经配置了正确的 replicaSet 连接串不然演练一半发现业务写不进去就得边修连接串边排查那就不是演练是事故。3.2 锁定候选节点与调整优先级为了让 node2 成为唯一的目标新主我先在 node3 上执行rs.freeze()把它的参选资格冻结掉。命令里的单位是秒比如冻结 5 分钟可以写成rs.freeze(300);执行完以后node3 在这段时间内即使收到选举请求也不会参与竞选。这一步的意义在于缩小选举范围让结果只会在 node1 和 node2 之间产生。如果 node1 已经因stepDown被禁选那新主就只剩 node2 一个候选。接着在 node2 上临时提高 priority。假设 node2 在 members 数组中的下标是 1操作如下cfg rs.conf(); cfg.members[1].priority 2; rs.reconfig(cfg);这里要提醒一下rs.reconfig()不要在从节点数据明显落后时执行因为 reconfig 本身也是复制操作配置变更会同步到整个副本集。同时如果你只是临时调高 priority演练结束后记得改回原值否则之后某次故障切换时node2 会因为 priority 更高而强行接管主角色打乱你对主节点位置的预期。3.3 执行 stepDown核心参数怎么定关键操作来了。在 node1 上执行手动降级这里有两个参数要理解清楚。use admin db.adminCommand({ replSetStepDown: 120, secondaryCatchUpPeriodSecs: 60 })第一个参数 120表示 node1 在 120 秒内不能参与选举不能重新成为主节点。这个值不能设得太小否则 node1 刚降级完还没等新主稳定下来就可能重新被选回去出现主节点来回跳的“乒乓效应”。我一般至少给 60 秒生产维护场景给 120 秒更稳。第二个参数secondaryCatchUpPeriodSecs是新版本里更关键的东西。它的作用是告诉 MongoDB在降级后给从节点留出多少时间追赶主节点的最新 oplog追平之后再进行选举。这个窗口越大新主节点赢得选举时数据就越新发生回滚的概率就越低。这里有个计算逻辑要理解如果你只执行rs.stepDown(120)不指定secondaryCatchUpPeriodSecsMongoDB 会按默认策略大概留出seconds - 10秒左右的追赶窗口也就是 110 秒左右。实际值以当前版本的默认策略为准。如果手动指定为 60就等于明确告诉数据库最多等 60 秒如果从节点还没追平也强行开始选举。这个参数在从节点数据比较滞后时尤其重要给得太短会导致选出来的新主数据落后给得太长会延长整个切换期间的不可写窗口需要根据实际延迟情况权衡。提示force: true是极端场景才用的选项。加了它之后主节点会立刻降级不等待任何从节点追赶数据。虽然命令执行速度快但新主可能没有拿到最新日志旧主重新加入后反而可能出现回滚。常规演练一定不要用 force。3.4 观察切换过程与验证结果执行完stepDown之后不要急着下结论切换是有过程的。我习惯另外开一个终端用循环脚本每 1 秒查询一次节点的db.hello()结果观察isWritablePrimary字段的变化。while true; do date %H:%M:%S mongosh --quiet --host 127.0.0.1 --port 27017 --eval db.hello().isWritablePrimary sleep 1 done正常情况下你会看到这样的过程node1 的isWritablePrimary从 true 变成 false几秒后 node2 的该字段变成 true。整个过渡一般在 10 到 30 秒内完成取决于从节点追赶日志的速度。期间如果出现几十秒还没有任何节点变成主就需要按下一章的排查思路去处理了。切换稳定后再执行一次完整的rs.status()确认members里谁是 PRIMARY谁是 SECONDARY。另外用rs.printSecondaryReplicationInfo()可以快速确认所有从节点的同步进度最好的状态是所有副本都跟踪到了新主的日志位点。3.5 验证业务写入与回切流程角色切换成功不代表业务就正常了还要做一次真实写入验证。我通常在 node2 上执行一条简单的插入和查询操作db.test_collection.insertOne({ ping: true, ts: new Date() }); db.test_collection.findOne({ ping: true });如果业务应用本身就是通过副本集连接串访问的这个时候应该能自动感知新主并继续正常写入。如果写入报错大概率是连接串配置问题或者驱动缓存问题建议先查连接串再查驱动版本。回切流程与切换流程完全对称想在 node1 恢复主角色就在 node2 上执行一次同样的rs.stepDown()同时确保 node1 已经过了禁选期、priority 配置符合预期。如果之前 node1 执行的是stepDown(120)那么在 120 秒内它都不能参选。演练中想尽快回切就要等足这个窗口或者当初就把 seconds 设短一点。4. 高频翻车现场与排查诀窍4.1 执行后一直没有新主产生最让人头皮发麻的现象就是replSetStepDown明明执行成功了但等了半天rs.status()里一个 PRIMARY 都看不到。这种场景我遇到过两次原因基本都是“候选节点不够”。比如三节点副本集里一个节点被 stepDown 禁选另一个节点执行过rs.freeze()还没到期剩下唯一的节点又不满足多数派条件选举自然无法成功。排查步骤先确认副本集里在线且有投票权的节点数量是否达到多数派。再检查rs.status()里那些 SECONDARY 节点是否被冻结stateStr旁边会显示相关状态。如果是被 freeze 住的节点导致选举无法完成可以在对应节点上执行rs.freeze(0)解除冻结让选举恢复。4.2 业务端持续报 NotWritablePrimary主节点已经成功切到 node2但应用还是不断报NotWritablePrimary遇到这种情况不要怀疑 MongoDB 出问题了问题基本都在应用侧。最常见原因是连接串没有配置replicaSet参数驱动不知道应该动态发现新主节点。这时候需要检查应用的 MongoDB URI把它改成标准副本集格式mongodb://node1:27017,node2:27017,node3:27017/?replicaSetrs0第二个常见原因是应用连接池里的连接一直是旧的驱动虽然在主节点变化后会自动刷新但某些老版本驱动对副本集拓扑变化的感知能力比较弱需要业务侧重启应用或主动清空连接池才能恢复。出现这种情况时先升级驱动到支持副本集监控的较新版本再考虑应用侧是否需要加一层重连逻辑。4.3 原主节点又抢回主角色的“乒乓效应”这个问题在 priority 默认全为 1 的副本集里特别容易发生。操作顺序通常是这样的node1 执行 stepDownnode2 赢得选举成为新主。但 node1 的禁选期一过它作为日志最新的节点很可能再次赢得选举把主角色抢回来。如果下次又有人执行 stepDown主角色又跳走来回切换对业务的影响比单一一次切换大得多。避免乒乓效应有两个手段一个是把 stepDown 的 seconds 设置得足够长比如 120 秒给业务充分的稳定时间另一个是在切换前临时调整原主的 priority把它调低这样即使禁选期过了它也不会因为优先级最高而被优先选回。演练结束后记得把 priority 恢复原值。4.4 节点出现 ROLLBACK 状态切换过程中如果出现了强制降级或者追赶窗口太短原主节点重新加入副本集时可能发现自己有一部分写操作没有被新主复制到多数派节点这时它会进入回滚流程在rs.status()里显示为ROLLBACK。回滚完成后被回滚的数据会写入该节点的 rollback 目录供后续人工确认。出现 ROLLBACK 不一定是灾难但说明这次切换并不“优雅”。规避方式就是两点提前确认目标从节点日志足够新以及给secondaryCatchUpPeriodSecs留足时间。如果已经出现回滚不要手动重启节点等待 MongoDB 自己完成回滚流程然后立刻检查被回滚的数据是否影响业务必要时做数据补偿。4.5 常见问题速查表症状可能原因解决思路stepDown 后没有新主候选节点被冻结 / 不满足多数派检查节点状态用 rs.freeze(0) 解除冻结业务写入持续报错连接串缺 replicaSet / 驱动太旧修正 URI升级驱动必要时重启应用原主快速重新当选stepDown 窗口太短 / priority 过高加长 seconds临时降低原主 priority节点进入 ROLLBACK强制降级 / 追赶窗口过短等回滚完成检查回滚数据调整切换参数从节点一直追不上主节点oplog 窗口不足 / 复制断档扩大 oplog 大小重新初始化该从节点5. 一些真正值得记住的经验5.1 演练频率建议手动主从切换这件事一个月做一次都不嫌多前提是做好演练预案和业务沟通。每次故障切换的场景和手动演练的场景其实不完全一样故障切换没有时间让你提前检查同步延迟也没有机会预先设置 priority完全靠副本集的自动机制兜底。定期手动演练相当于把这条兜底路径提前跑熟真遇到故障时你不会在指挥页面面前犹豫“这一步应该先看什么、再点什么”。我习惯在每个维护窗口前做一次完整演练演练完顺手把监控告警阈值校对一遍。如果你的副本集已经很久没发生过切换建议近期就安排一次因为你无法确定应用连接串、驱动版本和监控策略是不是在“主节点从来不变”的前提下运行太久了。5.2 分片集群与 config server 的特殊性演练环境如果涉及分片集群需要额外注意。分片集群里的每个分片都是一个副本集对分片副本集执行 stepDown逻辑上和单副本集一样但还要考虑正在进行的 chunk 迁移。切换会导致分片主节点短暂变化某些迁移任务可能被中断重试虽然设计上是安全的但建议在低峰期操作并且提前观察迁移任务是否活跃。config server 的副本集更要谨慎。它承载了整个集群的路由元数据mongos 会缓存 config server 的主节点信息虽然正常情况下 mongos 会自动刷新但切换瞬间可能导致路由请求产生瞬时抖动。我的建议是除非有明确的维护需求否则不要轻易对 config server 做手动切换演练确需维护时要预留更充裕的时间窗口并且通知所有业务方关注连接抖动。5.3 自动化与监控联动手动演练最大的价值之一是验证监控体系是否正常。切换前记录一下监控面板上主节点的角色标签、复制延迟曲线和告警状态切换后立即检查这些指标是否有变化。很多团队的监控只覆盖了节点存活、CPU、内存这些基础指标却没有覆盖“主节点角色变化”和“复制延迟”这两个直接反映高可用状态的指标导致演练时切换都完成了监控面板却毫无波澜。有条件的话可以写一个简单的脚本自动轮询rs.status()并记录角色变化时间线。这一步既能让演练结果有据可查也能在真正的主从切换发生时快速定位“切换始于什么时间点、持续了多久、是否有异常状态”。演练不是给人看的是给系统和流程做体检的。从我个人的实践经验来看rs.stepDown()这个操作真正的难点不在于命令怎么写而在于你是否想清楚了为什么切、切给谁、切完怎么验证。每次演练都抱着“马上就要出故障”的心态去操作把检查项逐条过一遍几个月下来你对自己数据库的高可用能力会非常有底气。下次再有人问“主从切换怎么做”你可以直接把这篇的流程甩给他然后告诉他先在测试环境完整跑三遍再动生产。