第36章：MongoDB 复制协议源码——Oplog、选举与同等性

1. 项目背景

业务场景：当地生活电商的运维在半夜被告警叫醒——"MongoDB 发生主从切换，持续时间 18 秒"。18 秒的选举期间，订单写入全部失败。事后复盘发现——选举耗时长是因为当时的 Primary 所在的机器发生了网络半断（能 ping 通但 TCP 连接间歇性超时），其他节点等了 10 秒心跳超时才发现 Primary 不可达，又花了 8 秒完成选举。运维想知道：能不能把心跳超时调短一点加快选举？调短了会不会导致网络抖动时频繁误选举？更关键的是——选举期间 Oplog 的同等性是怎么保证的？会不会出现两个节点同时认为自己是 Primary 的"脑裂"？
痛点：复制集是 MongoDB 高可用的基石，但多数团队只知其表——会用 rs.status() 看状态，不知道心跳协议怎么工作、term 的真正含义、Oplog 的写入和拉取流程、writeConcern: majority 在源码层面到底做了什么。一旦出现复制延迟、选举抖动、Oplog 窗口不足等深层题目，就只能凭感觉调参数。
2. 项目设计

小胖（拿着监控曲线图）：大师！昨晚 Primary 选举花了 18 秒，写入全断了。能不能把心跳改成 2 秒？这样 Primary 一挂立刻就选新的？
大师：心跳超时默认是 10 秒（heartbeatTimeoutSecs），不能调太低。因为 MongoDB 的选举不是"等心跳超时→立刻选举"这么简朴。实际上还有一个"选举超时"（electionTimeoutMillis，默认 10 秒）和"心跳间隔"（heartbeatIntervalMillis，默认 2 秒）——这三个参数组成了一套防止误选举和脑裂的安全网。
小胖：心跳、选举超时……这两个不是一回事吗？
大师：不一样。心跳是节点之间定期 ping-pong——每 2 秒发一次，如果 10 秒都没收到回复，就把对方标记为"不可达"。选举超时是指——从发现 Primary 不可达开始，等候 10 秒才开始选举。所以总故障检测时间 = 心跳超时（10 秒）+ 选举超时（10 秒）≈ 最多 20 秒。
技术映射：节点通过心跳交换 replSetHeartbeat 命令——焦点信息包括自己的 term、最新的 optime、是否认为自己是 Primary。当多数节点认为 Primary 失联时，它们各自等候一段随机时间（electionTimeout + random offset）后发起选举——这个随机偏移防止同时竞选导致分裂投票。
小胖：那 term 是什么？Raft 协议里的任期号？
大师：精确。Term（任期号）是选举的焦点概念，是一个单调递增的整数。每次选举 term+1——节点只有在自己的 term 大于即是当前集群 term 时才有资格成为 Primary。这保证了"在一个 term 里只能有一个 Primary"——这是防止脑裂的第一道防线。
技术映射：Term 在源码中存储为 long long，存储在 Oplog 的每条记录中（oplog.rs 中每条文档的 t 字段就是 term）。当两个节点都声称自己是 Primary 时，term 更高的那个胜出，另一个发现自己的 term 低后会立刻降级。
小白（追问）：Oplog 的写入和拉取是怎么协调的？从库是怎么追主库的？
大师：Oplog 的复制流程分两条线——Primary 侧的写入线和 Secondary 侧的拉取线：
Primary 侧：每次写操纵（insert/update/delete）执行完后，ReplicationCoordinator 会生成一条 Oplog 条目，格式如下：

1. {
2.   "ts": Timestamp(1711000000, 1),   // 时间戳（全局唯一）
3.   "t": 5,                            // term（任期号）
4.   "h": NumberLong("..."),            // 哈希（用于幂等检测）
5.   "v": 2,                            // Oplog 版本
6.   "op": "i",                         // 操作类型 i=insert u=update d=delete
7.   "ns": "life_mall.orders",          // 命名空间
8.   "o": { "_id": ..., "status": "待支付" }  // 操作内容
9. }

复制代码

Secondary 侧：通过 OplogFetcher 持续向 Primary（或另一个 Secondary）发送 find 命令拉取 Oplog——每次拉取从上次的 optime 往后取一批（默认 batchSize=5000 条），然后在当地依次应用（apply）。
技术映射：Oplog 拉取是异步的——Secondary 从 Primary 拉 Oplog 的延迟就是"复制延迟"。延迟的来源：网络传输延迟 + 批量缓冲延迟 + 当地 apply 开销。apply 是单线程的（MongoDB 4.0 前），4.0+ 支持并行 apply（每个库一个线程）。
小胖：那 Rollback 呢？如果 Primary 在 Oplog 还没传到从库时就挂了，新 Primary 的 Oplog 比旧 Primary 少——旧 Primary 重新加入时多出来的 Oplog 怎么处理？
大师：这就是 Rollback 的场景。旧 Primary 恢复后发现自己的 Oplog 中有新 Primary 没有的条目——这些条目被"回滚"。回滚的过程是：

• 找到旧 Primary 和新 Primary 的 Oplog 分叉点（common point）。
  
• 将分叉点之后旧 Primary 独有的写操纵——记录到一个回滚文件中（rollback 目录下的 BSON 文件）。
  
• 删除旧 Primary 的这些 Oplog 条目和对应的数据。
  
• 旧 Primary 重新从新 Primary 同步。
  

技术映射：Rollback 是 MongoDB 主动处理的，但被回滚的写入对客户端来说已经"成功返回"——因为旧 Primary 当时的 writeConcern 是 w:1，客户端收到确认后数据被回滚，造成了"已确认的写入丢失"。这就是 writeConcern: majority 如此重要的原因——majority 确认的数据不会被回滚。
大师（总结）：复制协议的三个焦点——心跳+选举保证高可用（约 10-20 秒切换时间），Oplog 拉取+应用保证数据同步，Rollback 处理 Primary 降级后的不同等。源码层面，ReplicationCoordinatorImpl 是这一切的中央控制者。
3. 项目实战

3.1 环境预备

必要 3 节点复制集（第 17 章设置），以及 MongoDB 源码调试环境（第 32 章设置）。
3.2 分步实现

步骤一：观察 Oplog 的结构与内容
目标：直接读取 Oplog 集合，理解每条 Oplog 条目标含义。

1. // 连接 Primary
2. use local
4. // 查看 Oplog 基本信息
5. var stats = db.oplog.rs.stats()
6. print("Oplog 条目数:", stats.count)
7. print("Oplog 大小:", (stats.size / 1024 / 1024).toFixed(1), "MB")
8. print("Oplog 平均对象大小:", stats.avgObjSize, "bytes")
10. // 查看最近的 5 条 Oplog 条目
11. db.oplog.rs.find().sort({ $natural: -1 }).limit(5).forEach(function(op) {
12.   print("---")
13.   print("时间戳:", op.ts)
14.   print("Term:", op.t)
15.   print("操作:", op.op, "→", op.ns)
16.   print("内容摘要:", JSON.stringify(op.o).slice(0, 120))
17.   if (op.o2) print("查询条件:", JSON.stringify(op.o2).slice(0, 80))  // update的filter
18. })
20. // 查看 Oplog 窗口大小
21. var first = db.oplog.rs.find().sort({ $natural: 1 }).limit(1).next()
22. var last = db.oplog.rs.find().sort({ $natural: -1 }).limit(1).next()
23. if (first && last) {
24.   var firstSec = first.ts.getHighBits()
25.   var lastSec = last.ts.getHighBits()
26.   var windowHours = (lastSec - firstSec) / 3600
27.   print("Oplog 窗口:", windowHours.toFixed(1), "小时")
28. }

复制代码

步骤二：观察心跳协议
目标：通过 mongod 日志观察节点之间的心跳交互。

1. # 在 mongod 日志中过滤心跳相关记录
2. docker exec mongo-rs1 cat /var/log/mongodb/mongod.log | grep "heartbeat" | tail -20
3. # 预期看到：
4. # - "Received heartbeat from ..."（收到心跳）
5. # - "Heartbeat to ... failed"（心跳失败）
6. # - 心跳中包含的 replSetName、term、optime 信息

复制代码

1. // 通过 replSetGetStatus 查看心跳状态
2. var status = rs.status()
3. status.members.forEach(function(m) {
4.   print(m.name)
5.   print("  状态:", m.stateStr)
6.   print("  健康:", m.health === 1 ? "正常" : "异常")
7.   print("  最后心跳:", new Date(m.lastHeartbeat))
8.   print("  心跳间隔(ms):", m.pingMs)
9.   print("  optime:", m.optime ? m.optime.ts : "N/A")
10.   print("  同步源:", m.syncSourceHost || "自己或者Primary")
11.   print("---")
12. })

复制代码

步骤三：观察选举过程
目标：手动触发 stepDown，观察选举日志。

1. # 终端 1：实时查看 mongod 日志（所有节点）
2. docker exec mongo-rs1 tail -f /var/log/mongodb/mongod.log | grep -E "election|stepDown|PRIMARY|SECONDARY"

复制代码

1. // 在 Primary 上执行 stepDown
2. rs.stepDown(30)
3. // Primary 降级，10-20 秒后另一个节点被选为新 Primary

复制代码

1. # 日志中应能看到完整的选举流程：
2. # "step down" → 当前 Primary 降级
3. # "Starting an election" → 某节点发起选举
4. # "election succeeded" → 当选成功
5. # "transition to PRIMARY" → 角色切换

复制代码

步骤四：模拟和观察 Rollback
目标：制造 Primary 孤立然后恢复的场景，观察回滚行为。

1. # 1. 在 Primary 上写入一条数据（writeConcern: w:1）
2. # 2. 立即断开 Primary 的网络（docker network disconnect）
3. # 3. Primary 降级，新 Primary 当选
4. # 4. 在新 Primary 上继续写入（覆盖 Oplog 分叉点后的部分）
5. # 5. 恢复旧 Primary 的网络
6. # 6. 旧 Primary 发现自己的 Oplog 分叉 → 触发 Rollback
7. # 7. 查看旧 Primary 的 mongod.log，搜索 "rollback"

复制代码

步骤五：源码追踪——Oplog 写入路径

1. // 源码关键路径（GDB 断点）
2. // 文件：src/mongo/db/repl/replication_coordinator_impl.cpp
4. // 1. Oplog 写入入口
5. // 函数：ReplicationCoordinatorImpl::_logOp()
6. // 作用：操作执行后将操作序列化写入 Oplog
8. // 2. Oplog 拉取
9. // 文件：src/mongo/db/repl/oplog_fetcher.cpp
10. // 函数：OplogFetcher::_doNextBatch()
11. // 作用：Secondary 向 Sync Source 请求下一批 Oplog
13. // 3. Oplog 应用
14. // 文件：src/mongo/db/repl/oplog_applier.cpp
15. // 函数：OplogApplier::applyOplogBatch()
16. // 作用：将拉取到的 Oplog 条目应用到本地
18. // 4. 选举发起
19. // 文件：src/mongo/db/repl/topology_coordinator.cpp
20. // 函数：TopologyCoordinator::checkShouldElect()
21. // 作用：判断自身是否有资格发起选举

复制代码

步骤六：writeConcern majority 的源码链路

1. // majority commit point 的概念：
2. // 每条 Oplog 条目有一个 "optime"（ts 字段）
3. // Primary 持续追踪每个 Secondary 的最后一条 optime（通过心跳）
4. // "majority commit point" = 大多数节点都复制的最高 optime
6. // 源码路径：
7. // ReplicationCoordinatorImpl::_updateCommittedSnapshot()
8. // → 计算新的 majority commit point
9. // → 所有 readConcern: majority 的读只在这个 commit point 之前返回
10. // → 所有 writeConcern: majority 的写等待 commit point 追上自己的 optime
12. // GDB 断点：
13. // (gdb) break mongo::ReplicationCoordinatorImpl::_updateCommittedSnapshot
14. // 观察 commit point 的推进逻辑

复制代码

3.3 完整代码清单

文件用途mongodb-lab/replicaset/oplog-inspect.jsOplog 结构与窗口分析mongodb-lab/replicaset/heartbeat-monitor.js心跳状态观察mongodb-lab/replicaset/rollback-simulate.shRollback 模拟脚本debug-scripts/repl-trace.gdb复制链路 GDB 断点脚本3.4 测试验证

1. // 连接 Primary
2. // 1. 验证 Oplog 写入：每次 insert 对应一条 Oplog
3. use local_life
4. db.repl_test.insertOne({ test: "oplog_write", ts: new Date() })
5. var oplogEntry = db.getSiblingDB("local").oplog.rs.find({
6.   "ns": "local_life.repl_test"
7. }).sort({ $natural: -1 }).limit(1).next()
8. print("Oplog 写入:", oplogEntry ? "PASS" : "FAIL")
10. // 2. 验证心跳可达
11. var status = rs.status()
12. var allHealthy = status.members.every(m => m.health === 1)
13. print("所有节点健康:", allHealthy ? "PASS" : "FAIL")
15. // 3. 验证 stepDown
16. var prePrimary = rs.isMaster().primary
17. rs.stepDown(30, 10)
18. sleep(15000)
19. var postPrimary = rs.isMaster().primary
20. print("Primary 已切换:", prePrimary !== postPrimary ? "PASS" : "FAIL")
22. print("\n=== 复制协议验证完成 ===")

复制代码

4. 项目总结

4.1 复制协议焦点概念速查

概念源码关键位置作用Term（任期号）Oplog 条目 t 字段防止脑裂——同一 term 只能有一个 PrimaryOplog 写入ReplicationCoordinatorImpl::_logOp()每次写操纵生成 Oplog 条目Oplog 拉取OplogFetcher::_doNextBatch()Secondary 向 Sync Source 拉 OplogOplog 应用OplogApplier::applyOplogBatch()Secondary 在当地应用 Oplog心跳协议TopologyCoordinator每 2s 交换心跳，10s 超时判定不可达选举TopologyCoordinator::checkShouldElect()多数节点同意 → 当选 PrimaryMajority Commit_updateCommittedSnapshot()盘算多数节点复制的最高 optimeRollbackReplicationCoordinatorImpl回滚分叉的 Oplog4.2 适用场景

复制协议知识适用：

• 选举耗时异常的根因分析——心跳超时、网络分区、term 冲突。
  
• Oplog 窗口不足的容量规划——根据写入速率盘算必要的 Oplog 大小。
  
• Rollback 事件的排查——被回滚的数据恢复与原因追溯。
  
• 多机房复制延迟优化——心跳间隔与选举超时的跨机房适配。
  

4.3 注意事项

注意事项说明heartbeatTimeoutSecs 不能低于 5 秒网络偶尔抖动大概触发频繁选举Oplog 是 Capped Collection固定大小环形缓冲区，写入达到大小上限后覆盖最旧数据Rollback 文件必要手动清理回滚产生的 rollback 目录中的文件不会主动删除writeConcern: majority 在 2 节点中即是 w: 2任意一个节点宕机写入就卡住4.4 常见踩坑经验

故障案例一：多机房复制延迟导致上海从库永远追不上
某团队把 Primary 部署在北京，Secondary 部署在上海。网络 RTT 40ms，Oplog 拉取延迟持续 8-10 秒。根因：Secondary 的 Oplog 拉取是单线程操纵（每批次等返回后再拉下一批），RTT 直接叠加到延迟中。解决：增大 OplogFetcher 的 batchSize（通过 replBatchLimitOperations 参数），将批次从默认 5000 条调大到 20000 条；或启用 chaining（Secondary 可以从另一个 Secondary 拉 Oplog，选择更近的节点）。
故障案例二：心跳超时误判导致的频繁选举
某团队把 MongoDB 部署在共享 K8s Node 上，CPU 资源竞争激烈——心跳包偶尔被 cgroup throttle 迟滞超过 10 秒，其他节点误以为 Primary 挂了触发选举。一个月内发生 47 次不必要的主从切换。解决：heartbeatTimeoutSecs 调大到 20 秒；给 MongoDB Pod 设置 CPU request（保障最低 CPU）；开启 electionTimeoutMillis: 15000 增加选举等候时间。
故障案例三：Rollback 后数据"消失"导致的订单对账异常
某次 Primary 宕机 + Rollback 后，财务系统报告有 127 笔订单在 MongoDB 中找不到（实际被 Rollback 了）。这些订单的客户端实际已收到"下单成功"——因为 writeConcern: w:1，Primary 返回了成功但数据被回滚。解决：关键业务写入统一用 writeConcern: majority；Rollback 事件告警 + 回滚文件主动解析入库做人工对账。
4.5 思考题

• 如果网络发生分区——3 节点复制会合，Primary 和 1 个 Secondary 被分到一侧（2 票），另一个 Secondary 单独在另一侧（1 票）。哪一侧能选举出 Primary？为什么？
  
• Oplog 条目中的 h 哈希字段的作用是什么？MongoDB 怎样利用它实现幂等的 Oplog 应用？
  

（答案将在第 37 章末尾发表）

上一章思考题答案：

• 重复元素 ["a","a","b"]——Multikey Index 只会为"a"创建1 个索引键（而非 2 个）。MongoDB 在索引数组时会主动去重每个文档的数组元素，避免重复的索引键造成空间浪费和查询时的重复结果。但这不是跨文档去重——不同文档中相同的"a"各自占一个索引条目。
  
• 复合唯一索引 {city:1, orderNo:1} 中——缺失字段被视为 null。如果两个文档都缺失 city 和 orderNo，它们在这个索引中的复合键都是 (null, null)——第二个文档插入时会触发 DuplicateKey 错误。如果必要允许缺失字段共存，使用 sparse: true——缺失字段的文档完全不入索引，不受唯一约束限制。
  

延伸阅读与资源

NumPy 从入门到生产落地：全链路实战指南（科学盘算/向量化）
Redis 8 实战精讲：从 CRUD 到源码，构建高可用缓存系统
Redis 实战修炼与原理进阶
Python 3实战精进：从脚本到高并发订单引擎
python入门：Rquests从菜鸟脚本到企业级SDK的网络实战圣经
Milvus向量数据库实战修炼：从 0 到 1醒目向量检索与生产落地
MongoDB 实战进阶与内核修炼
后端工程师的 AI 转型第一课：Ollama 与私有化大模型实战
10倍开辟者的 Dify 魔法书：从零构建全栈 AI 应用
后端工程师转型AI第一课-Ollama 与私有化大模型实战
大型语言模型(LLM) vLLM 高性能推理落地实战
Agent开辟之LlamaIndex 实战修炼与源码进阶
大语言模型Transformers 实战修炼与源码分析