跳到主要内容
锦木信息 JINMU INFO
MongoDB 博客
MongoDB · 技术文章

Change Streams:
让数据库主动通知你变了什么

缓存失效、搜索索引同步、事件驱动的微服务、跨库数据复制,这些场景都需要"数据一变就知道"。变更流(Change Streams)让应用不必再手工去追 oplog,就能订阅一个集合、一个库甚至整个部署的实时变化。这篇文章讲它怎么打开、事件里有什么、断了怎么续,以及上线前该留意的坑。

一次变更的旅程示意
01 写入
应用写入insert / update / replace / delete
→
02 复制
oplog变更记录在 oplog 中,复制给从节点
→
03 变更流
多数派已提交只通知已在多数派持久化的变更
→
04 消费
你的应用缓存、搜索、消息队列、下游服务
断点续传靠 oplog 窗口续传令牌对应的操作必须还留在 oplog 里
令牌 A已被覆盖,无法续传
令牌 B仍在窗口内,可续传
更早(已被覆盖)最新

示意:位置仅用于说明 oplog 窗口与续传令牌的关系,不是真实数据

01 · 为什么用变更流

不用再自己"追" oplog

官方文档的说法是:变更流让应用无需承担手工追踪 oplog 的复杂度与风险,就能访问实时数据变更。应用可以订阅单个集合、一个数据库或整个部署上的所有数据变化,并立即做出反应。

适用条件

副本集或分片集群

变更流适用于副本集和分片集群,并且必须使用 WiredTiger 存储引擎。启用静态加密的部署也可以使用。

可靠性

只通知多数派已提交的变更

通知只针对已经提交到多数派、在故障场景下依然持久的变更,因此不会收到之后可能被回滚的数据。

灵活

基于聚合框架

变更流建立在聚合框架之上,可以用管道过滤、转换通知,只拿到自己关心的事件。

读关注无需额外配置

无论 "majority" 读关注支持处于开启(默认)还是关闭状态,变更流都可以使用。

02 · 打开变更流

三个层级:集合、数据库、整个部署

用 watch() 打开变更流,再迭代游标取事件。

范围shell 方法说明
单个集合 db.orders.watch() 除 system 集合,以及 admin、local、config 库里的集合以外的任意集合
一个数据库 db.watch() 该库下所有非 system 集合(admin、local、config 库除外)
整个部署 Mongo.watch() 所有库里的非 system 集合(同样排除 admin、local、config)
订阅 orders 集合,只关心写入类事件
// 用管道过滤,只保留 insert / update / replace
const pipeline = [
  { $match: {
      operationType: { $in: ["insert", "update", "replace"] }
  } }
]
const cs = db.orders.watch(pipeline)

while (cs.hasNext()) {
  const ev = cs.next()
  printjson(ev.documentKey)
  // 处理完成后,把 ev._id 作为续传令牌持久化
}
一条更新事件长什么样(示意,已精简)
{
  _id: { _data: "8265..." },   // 续传令牌
  operationType: "update",
  ns: { db: "shop", coll: "orders" },
  documentKey: { _id: ObjectId("...") },
  updateDescription: {
    updatedFields: { status: "paid" },
    removedFields: []
  }
}
权限

需要 changeStream 和 find 权限

打开变更流时,需要在目标范围(集合、库内所有非 system 集合或整个部署)上拥有 changeStream 与 find 权限。

别改 _id

事件文档的 _id 就是续传令牌。从 MongoDB 4.2 起,如果管道修改了事件的 _id,变更流会直接抛出异常。使用 $project 时要保留它。

03 · 事件内容与前后镜像

默认只给增量,想要完整文档要额外开口

默认情况下,更新事件只返回被修改字段的增量(delta)。如果要拿到完整文档,有两条路。

方式一

fullDocument: "updateLookup"

返回"当前多数派已提交的最新版本"的文档。注意它是事后查询:如果在更新之后、查询之前又有已提交的操作修改了这篇文档,返回内容可能与更新那一刻的文档差别很大,但增量描述始终是准确的。

方式二(6.0+)

前后镜像 Pre- / Post-Images

前镜像是替换、更新或删除之前的文档,后镜像是插入、替换或更新之后的文档。插入没有前镜像,删除没有后镜像。需要先在集合上开启。

先开启,再请求镜像
// 1) 在集合上开启前后镜像
db.runCommand({
  collMod: "orders",
  changeStreamPreAndPostImages: { enabled: true }
})

// 2) 打开变更流时请求前后镜像
db.orders.watch([], {
  fullDocument: "whenAvailable",
  fullDocumentBeforeChange: "whenAvailable"
})
required 与 whenAvailable

找不到镜像时怎么办

两个字段都可设为 required 或 whenAvailable。镜像缺失的原因包括:写入时尚未开启,或超过 expireAfterSeconds 保留期被清理。

代价

占存储、增加处理时间

前镜像写入 config.system.preimages 集合,可能变得很大,可以用 expireAfterSeconds 限制。文档建议:确实需要时再开启。

updateLookup 的局限

更新事件里的 fullDocument 在这些情况下可能缺失:文档在更新与查询之间被删除,或集合被删除,或这次更新修改了分片键字段。另外,文档提醒:updateLookup 与 $match 过滤组合,在快速删除或流量突增时可能引发 "Resume Token Not Found" 错误,并推荐改用前后镜像。

04 · 断点续传

应用重启、连接中断之后,从哪里接着读

变更流可以通过续传令牌(resume token)恢复,把令牌传给 resumeAfter 或 startAfter 即可。

选项起点要点
resumeAfter 某个续传令牌之后 不能在 invalidate 事件(如集合被删除或重命名)之后恢复
startAfter 某个续传令牌之后,新建一个变更流 与 resumeAfter 不同,可以在 invalidate 事件之后继续
startAtOperationTime 某个时间点 起点如果在过去,必须落在 oplog 覆盖的时间范围内
从上次处理到的位置继续
// savedToken 是上次持久化的 ev._id
const cs = db.orders.watch(pipeline, {
  resumeAfter: savedToken
})

// 集合被 drop / rename 触发 invalidate 之后:
const cs2 = db.orders.watch(pipeline, {
  startAfter: savedToken
})
两种令牌

事件令牌与高水位令牌

事件令牌对应具体的变更事件;高水位令牌表示一个没有对应事件的时间点,服务器会定期生成,用来表明集群时间已经前进,即使没有任何变更。

硬性前提

oplog 必须留有足够的历史

要找到令牌或时间戳对应的操作,oplog 里必须还保留着那段历史。续传时还要使用与生成令牌时相同的管道和选项,否则可能行为异常、影响数据一致性,甚至无法续传。

WAP 提示

"能不能续上"本质上取决于 oplog 窗口够不够长:消费端停机越久、写入越猛,窗口就越容易被追平。oplog 窗口、复制延迟、成员状态这类指标,正是 WAP 监控和告警模块持续关注的对象,把它们纳入告警,可以在消费者落后太多之前就收到提醒。

05 · 集群与运维

放进生产之前,先想想这几件事

下面这些行为都来自官方文档的描述。

分片集群

mongos 为每个分片开流

在分片集群上从 mongos 打开变更流。mongos 会在每个分片上各建一个变更流,收到结果后统一排序、过滤,必要时还会做 fullDocument 查询。副本集则可以从任意数据承载成员打开。

连接池

每个流占一个 getMore 连接

每个变更流在等待下一个事件时,都会占用一个带 getMore 的连接。同一数据库上活跃的变更流数超过连接池大小,就可能出现通知延迟,应让 maxPoolSize 大于打开的流数。

时序集合

不支持变更流

时序集合使用优化的存储格式,不在文档级别跟踪变更,因此不支持变更流。

故障切换

getMore 可能被打断

文档指出,在读偏好为 primary 或 secondary 时,故障切换可能让 getMore 返回 InterruptedDueToReplStateChange(错误码 11602)。兼容的驱动和 mongos 会自动续传;手写 getMore 循环或使用 mongosh 时,需要自己捕获并用 resumeAfter 恢复。

事务

事件里带事务标识

如果某个操作属于一个事务,变更事件文档会包含 txnNumber 和 lsid。

排序规则

默认二进制比较

除非显式指定排序规则(collation),变更流使用 simple 二进制比较。

06 · 避坑清单

常见现象、原因与对策

根据上文整理的一份速查表。

现象可能原因对策
Resume Token Not Found 令牌对应的操作已经滚出 oplog;或 updateLookup 与 $match 组合遇到快速删除、流量突增 加大 oplog、及时持久化令牌;改用前后镜像
续传后行为异常 续传时的管道或选项与生成令牌时不一致 使用相同的管道和选项
更新事件缺少 fullDocument 文档已被删除、集合被删除,或更新改了分片键 需要时使用后镜像
通知有延迟 活跃的变更流数超过连接池大小 调大 maxPoolSize
集合被 drop 或 rename 后流关闭 发生了 invalidate 事件 用 startAfter 新建变更流
config.system.preimages 越来越大 前镜像没有设置保留期 设置 expireAfterSeconds,并监控该集合大小
最后一句

订阅变化很容易,
可靠地"续"上才是功夫

把续传令牌持久化、把 oplog 窗口盯紧、把管道和选项保持一致,变更流就能成为事件驱动架构里稳当的数据源。

聊聊您的数据难题

告诉我们业务现状,资深技术顾问一对一给出选型与实施建议,咨询免费。