MongoDB 日常运维与故障场景（replica set 和 sharded cluster）

这不是安装指南：而是一份按场景组织的 runbook，用于日常管理已安装的 MongoDB replica set 和 sharded cluster，并在出现故障时恢复。内容包括健康检查、添加/删除成员、priority/hidden/delayed 成员、用数据成员替换 arbiter、重新同步落后的成员、多数派丢失时的 force reconfig、计划内 stepDown、oplog 大小、FCV；添加/删除 shard、balancer、jumbo chunk 和 reshardCollection。不确定该做什么时，请从健康检查开始；从备份恢复、安全设置和大版本升级见单独的 MongoDB 指南。

架构: Replica set（3 个以上成员）或 sharded cluster（config server + shard replica set + mongos）

场景

• 健康检查：成员、延迟、oplog 窗口（sharded 时还包括 shard 和 balancer） — 只读：成员状态、复制延迟、oplog 窗口、配置；在 sharded cluster 上还包括 shard 列表、balancer 和 chunk 分布。不确定该做什么时，从这里开始。
• 向 replica set 添加新成员（initial sync） — 新服务器已准备好（相同版本、keyfile、replSetName）；先以 priority 0 / votes 0 加入，initial sync 完成并变为 SECONDARY 后再赋予投票权和 priority。无停机。
• 从 replica set 删除成员 — 服务器即将下线或已永久丢失：从配置中删除该成员，并确认剩余投票仍构成多数。如果它是 primary，先执行 stepDown。
• 更改成员角色：priority、hidden、delayed（延迟）成员 — 更改成员成为 primary 的优先级，将其设为用于报表/备份的隐藏（hidden）成员或防止误删的延迟（delayed）成员，或恢复为普通成员。
• 用数据成员替换 arbiter（PSA → PSS） — Replica set 为 primary + secondary + arbiter：一个数据成员宕机后，majority 写入和缓存压力会成为问题。添加一个新的数据成员，然后删除 arbiter。
• 重新同步落后或损坏的成员（resync） — 成员卡在 RECOVERING 并报告 'too stale to catch up'，或其数据文件损坏：清空该成员的数据目录，通过 initial sync 从头同步。其他成员继续运行。
• 多数派丢失：用存活成员强制重新配置（force reconfig） — 大多数成员已永久丢失（站点/服务器丢失），存活成员无法选出 primary：用存活成员执行 rs.reconfig(cfg, {force: true})。这是最后手段；使用不当会导致数据丢失和 split brain。
• 计划内切换 primary（rs.stepDown，指定某成员成为 primary） — 需要在 primary 服务器上做维护/打补丁：primary 降级，一个已追平的 secondary 成为 primary。应用可能有几秒钟出现写入错误。
• 更改 oplog 大小（replSetResizeOplog） — oplog 窗口过短：维护后 secondary 变为 'too stale'，备份无法捕获 oplog，或不足以做时间点恢复。可在每个成员上在线扩大。
• 检查并完成 Feature Compatibility Version（FCV） — 升级后 FCV 仍停留在旧版本，或成员之间版本不一致：检查所有成员的二进制版本和 FCV，然后把 FCV 提升到新版本。
• 向集群添加 shard（sh.addShard） — 容量不足：已搭建新的 shard replica set（shardsvr），将其加入集群；balancer 会逐步把 chunk 迁移过去。
• 删除 shard（removeShard：drain 和 movePrimary） — 某个 shard 即将下线：把它的 chunk 迁空到其他 shard（drain），迁移以它为 primary shard 的数据库（movePrimary），然后从集群中删除。
• Balancer：时间窗口、停止/启动、按 collection 禁用 — 高峰时段 chunk 迁移造成负载，维护/备份期间需要停止迁移，或某个 collection 不应参与均衡。
• 分布不均或存在 jumbo chunk（诊断与处理） — 某个 shard 比其他 shard 满得多、balancer 不迁移、有标记为 'jumbo' 的 chunk，或 moveChunk 报错：检查分布、jumbo chunk 和 balancer 错误。
• 更改 shard key（reshardCollection） — 当前 shard key 导致热点 shard、jumbo chunk 或 scatter-gather 查询：在线以新 shard key 重新分布 collection（5.0+）。最后阶段写入会阻塞约 2 秒。

开始之前

• 管理服务器上已安装 mongosh，并且能…解析 mongos（…）的名称并访问其端口…解析所有成员（…）的名称并访问其端口…。连接中使用的名称必须与 rs.conf() 中的成员名称一致。
• 已掌握 … 用户的密码；其角色为 root，或至少为 clusterAdmin + readAnyDatabase。…直接连接 shard 或 config server replica set 时，需要 shard-local 管理员用户（在 mongo-sharded 指南中创建）。…
• 已开立变更单/维护窗口，并通知了应用团队。Reconfig、stepDown 和 shard 操作可能导致几秒钟的选举（election）或路由延迟。
• 新成员 … 已按照 replica set 安装指南 中操作系统、安装、keyfile 和配置各阶段准备好：相同的 MongoDB 版本（…）、相同的 keyfile、replication.replSetName: …，mongod 正在运行，但未执行 rs.initiate。与其他成员之间双向名称解析和端口访问正常；数据盘的可用空间不少于现有数据量。
• initial sync 期间，所有数据会在该成员磁盘上重新写入…；由于旧目录被移到一边，需要相当于数据大小两倍的可用空间…。其余成员保持多数派，且源成员的 oplog 窗口长于 initial sync 所需时间。

指南阶段

• 状态：成员、延迟和 oplog（只读） — 显示成员状态和延迟 · 显示配置（priority、votes、hidden、delay） · 解读结果并选择正确的场景
• 状态：shard、balancer 和 chunk 分布（只读） — 显示集群概要 · Chunk 分布和 jumbo chunk · 检查 shard replica set 的状态
• 1. 诊断：新成员是否就绪？ — 检查新成员的服务和版本 · 查看现有 set 的状态和数据大小 · 验证到新成员的访问
• 2. 安全措施 — 保存当前 replica set 配置
• 3. 执行：添加成员并等待同步 — 以 priority 0 / votes 0 添加成员 · 等待 initial sync 完成 · 赋予成员投票权和 priority
• 4. 验证与后续工作 — 验证状态 · 更新应用连接串和监控
• 1. 诊断：要删除的成员是不是 primary，多数派是否仍能保持？ — 确定成员角色和剩余投票数
• 2. 安全措施 — 保存当前 replica set 配置
• 3. 执行：删除成员 — 从配置中删除成员（rs.remove） · 在被删除的服务器上停止 mongod
• 4. 验证与后续工作 — 验证状态 · 更新连接串、监控和防火墙
• 1. 诊断 — 查看成员当前设置和 oplog 窗口
• 2. 安全措施 — 保存当前 replica set 配置
• 3. 执行 — 更改成员设置（rs.reconfig）
• 4. 验证 — 验证结果
• 1. 诊断：arbiter 和新成员 — 查看 arbiter 和 write concern · 验证新成员已就绪
• 2. 安全措施 — 保存当前 replica set 配置
• 3. 执行：添加数据成员，删除 arbiter — 以 priority 0 / votes 0 添加新成员 · 等待 initial sync 完成 · 赋予新成员投票权和 priority · 删除 arbiter · 在 arbiter 服务器上停止 mongod
• 4. 验证与后续工作 — 验证状态和 write concern
• 1. 诊断：该成员是否真的需要重新同步？ — 查看成员状态和最后一条消息 · 查看成员日志中的错误
• 2. 安全措施 — 保存当前 replica set 配置
• 3. 执行：清空数据目录并进行 initial sync — 停止 mongod · …将数据目录移到一边…清空数据目录… · 启动 mongod（initial sync 开始） · 等待 initial sync 完成
• 4. 验证与后续工作 — 验证状态 · 删除旧数据目录
• 1. 诊断：多数派是否真的已永久丢失？ — 从存活成员查看状态和 optime · 确认丢失的成员已关闭
• 2. 安全措施 — 保存存活成员的配置
• 3. 执行：force reconfig — 仅用存活成员强制重新配置 · 确认已选出 primary
• 4. 验证与后续工作 — 尝试 majority 写入 · 重新添加丢失的成员并消除根本原因
• 1. 诊断：secondary 是否已追平？ — 查看 primary 和延迟
• 2. 执行 — 冻结其他 secondary（以便选出目标成员） · 让 primary 降级（rs.stepDown）
• 3. 验证 — 验证新状态
• 1. 诊断：当前 oplog 大小和窗口 — 每个成员上的 oplog 大小和窗口