股海求生1. 双写方案为什么还在流行：一个看似省力的同步方案
服务端用 MongoDB 存业务数据、用 Elasticsearch 做搜索分析，这套组合在社区里早就不是新鲜事了。MongoDB 胜在写入灵活、文档模型天然贴近业务对象，ES 强在倒排索引和聚合查询，两者各管一段，看起来分工明确。问题只出在中间那条数据链路上：MongoDB 里的一条订单、一篇文章、一台设备状态，怎么才能实时出现在 ES 里？
大多数团队的第一反应是双写。用户在创建订单的接口里先插入 MongoDB，再调用 ES 的 Bulk API 写入一份同样的数据；更新时就两边同时 update；删除时两边同时 delete。代码写起来最直接，不引入额外基础设施，上线也快。我见过不少项目一开始都这么干，而且初期跑得还挺好，数据量不大、并发不高的时候，双写几乎没有存在感。
但双写真正的问题不会在第一天暴露，而是会在业务增长、团队扩容、字段变更的过程中，一点一点显现出来。等你意识到要换方案时，往往已经在补丁上叠补丁，线上躺着好几套定时对账脚本。这个演进路径我太熟悉了，所以这篇博客想从根上讲清楚：为什么双写看起来省力、实际是给自己挖坑，以及怎么用 MongoDB Change Streams 重新设计一条更可控的同步链路。
先说清楚一个基本认知：MongoDB 和 ES 是两套独立的存储系统，它们之间不存在原生事务。你可以在 MongoDB 里用事务保证多条文档的原子性，可以在 ES 里用 bulk 保证一批请求的原子性，但没有任何机制能保证"写 MongoDB 成功"和"写 ES 成功"这两个动作同时生效。双写方案的所有问题，本质上都是在对抗这个跨系统原子性缺失的现实。
因此，这篇内容适合谁看？如果你正在维护 MongoDB + ES 的搜索/分析链路，或者准备从双写重构为事件驱动同步，这篇文章会把原理、代码、踩坑经验都摊开讲。我不会只给结论，会把"为什么这么选"的原因也一起说清楚。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 双写同步的崩溃点：失败场景、数据补偿和代码耦合
2.1 先看最常见的失败时序：MongoDB 成功，ES 失败
假设你在订单接口里写了这样一段业务逻辑：先 insert 订单到 MongoDB，再 index 订单到 ES。看起来顺序没问题，但分布式系统里最不缺的就是"看起来没问题"的时序。ES 集群抖动、网络超时、Bulk 队列满了、字段类型冲突，任何一个原因都可能让第二步抛异常。
这时候订单在 MongoDB 里已经存在了，用户那边也收到了"下单成功"的响应。如果 ES 写入是同步的，接口会直接报错，用户看到的是系统异常；如果 ES 写入是异步的，接口返回正常，但搜索里查不到这条订单。两种结果都很难接受，前者把搜索系统的故障放大成了核心业务故障，后者产生了一个用户可见的脏数据。
于是补救措施来了：加一个定时任务，每隔几分钟对比 MongoDB 和 ES 的数据，把差异补回去。这个补偿任务听起来不难，但实际维护起来非常痛苦。你需要处理分页扫全表的性能问题，需要在对比时处理正在写入的中间状态，还需要考虑删除标记到底怎么同步。一个补偿脚本写到后面，复杂度往往超过业务代码本身。
2.2 双写还会放大"顺序"问题：更新乱序会直接产生脏数据
这是双写链路里特别隐蔽的一个坑。MongoDB 里同一条文档可能被并发更新，比如库存扣减、状态流转、金额修改。双写时，更新操作 A 和更新操作 B 先后到达 MongoDB，但到达 ES 的顺序可能反过来，尤其是经过了线程池、异步队列、或者网络重试之后。
我遇到过这样一个线上事故：用户订单状态先更新成"已支付"，紧接着又更新成"已退款"，但 ES 里最终存的是"已支付"。原因就是第二次 ES 写入重试了，晚于第一次写入到达，把旧状态覆盖回去了。这个问题用补偿任务很难解决，因为你对比 MongoDB 和 ES 时看到的是最终状态，不会意识到中间发生过乱序覆盖。
解决乱序的常见思路是带版本号写入，用版本号控制 ES 里的文档版本，旧版本覆盖不了新版本。但双写方案里，版本号得你自己维护，每张表、每个字段都要设计，等于在业务代码里塞进一套分布式一致性逻辑。
2.3 双写让业务代码和同步逻辑高度耦合
双写的本质是在每个业务写入点上手动添加 ES 调用。这意味着每新增一个搜索字段、每修改一次文档结构、每新增一个写入入口，你都必须在 MongoDB 和 ES 两边同步修改代码。业务发展到一定阶段，写入入口会变得非常多：管理后台、用户操作、定时任务、外部接口回调，每个入口都得记得做双写。
只要有一个入口漏了，就会出现"MongoDB 有数据，ES 没有"的问题。团队里每个人都很小心，但数据不一致还是会在各种角落里冒出来。这种问题最可怕的地方在于你很难用自动化手段发现，往往是用户搜不到数据时才意识到。
我见过一个团队为了排查"为什么 ES 里少了 3% 的文档"，把半个月的日志翻了个遍，最后发现是一个内部工具调用了 MongoDB 直连更新，绕过了业务服务的双写逻辑。这种问题属于架构层面的结构性漏洞，靠代码 review 和责任心是堵不住的。
2.4 性能层面：双写把写入放大了两倍
双写还意味着你的业务写入链路要承担两份 I/O。MongoDB 一次写入，ES 一次写入，ES 的写入还要经过分词、建索引、刷新到磁盘。对于高吞吐场景，ES 的写入延迟和资源消耗往往比 MongoDB 本身更夸张。
更麻烦的是，如果业务写入峰值和 ES bulk 写入峰值重合，搜索集群的 CPU 和内存就会被顶上去，查询延迟跟着飙升。为了给写入让路，你可能得给 ES 扩容，但大促结束后集群又闲置了。MongoDB 和 ES 的资源需求是不同的，双写让两个集群互相拖累，成本就在这种互相妥协中涨上去了。
拆解到这里你会发现，双写的所有问题都指向同一个根源：同步逻辑被塞进了业务通道里，缺少一个独立的、可靠的、可恢复的传递机制。解决方案的方向也不复杂，就是把这个同步动作从业务代码里拆出去，让 MongoDB 的变更事件自己驱动 ES 更新。
3. 变更流（Change Streams）同步的底层机制：从 oplog 到事件驱动
3.1 Change Streams 到底是什么
MongoDB 从 3.6 版本开始提供 Change Streams 功能，它允许客户端订阅集合、数据库、甚至整个集群的变更事件。实现原理上，它基于 MongoDB 的 oplog（操作日志）。MongoDB 的主节点会把每一次写操作记录到 oplog 里，Change Streams 就是对这个 oplog 做了一层面向业务的封装和过滤。
你可以把 oplog 想象成数据库自己的"账本"，每次 insert、update、delete 都会按顺序记一笔。Change Streams 则像一个订阅者，跟随 oplog 的尾部，把这些变更事件推送给你。因为顺序和可靠性是由 oplog 保证的，所以 Change Streams 天然解决了双写方案里的两个核心问题：事件不会丢、事件顺序有保障。
注意，这里说的"事件不会丢"不是绝对意义上的不丢，而是指在 MongoDB 集群正常运行、oplog 没有被覆盖的情况下，客户端可以靠恢复令牌从断点继续消费。oplog 容量是一个关键参数，如果消费端停机太久、oplog 被新写入覆盖了，就会发生断点失效。
3.2 三种主要的变化事件：insert、update、delete
Change Streams 推送的事件类型，对应了 MongoDB 的写操作类型。最常用的是这三种：
- insert：文档新增。事件里含完整的
fullDocument，可以直接用来写入 ES。 - update：文档更新。默认情况下事件里只包含被修改的字段和更新描述，如果你需要文档修改后的完整内容，要在创建 Change Stream 时配置
fullDocument: "updateLookup"。 - delete：文档删除。事件里只有被删文档的
_id，ES 侧对应执行 delete by id。
这个差异很重要，直接决定了你的消费端怎么设计。insert 事件可以直接拿到整条文档，update 事件如果不配 updateLookup，你只能拿到 update 操作符（比如 $set），得自己去拼 ES 里的文档；delete 事件最轻量，ES 侧删掉对应文档即可。
还有一种 replace 事件，是 replaceOne 操作触发的，本质上是整体替换文档，事件负载和 insert 类似。
3.3 恢复令牌与断点续传：这是双写方案完全不具备的能力
Change Streams 最核心的一个特性是恢复令牌（resume token）。每个变更事件都携带一个 _id 字段，这个字段的值就是该事件的恢复令牌。消费端在本地记录这个令牌，下次连接时通过 resumeAfter 或 startAfter 参数从上次位置继续消费，即使消费端中途宕机、重启、发布，都不会重复或丢失已经处理过的事件。
这里要注意两个参数的区别：
resumeAfter：从某个恢复令牌之后开始读，如果该令牌对应的 oplog 已经被覆盖，会报错。startAfter：也是从某个令牌之后开始读，但允许在令牌失效时从最新位置开始（需要额外的 fallback 逻辑）。
我在实践里通常用 resumeAfter，配合持久化令牌到 Redis 或 MongoDB 自身，这样消费逻辑重启后可以精确续传。如果遇到令牌失效，说明消费端停机时间超出了 oplog 的保留窗口，这时候宁可做一次全量重灌，也不要糊里糊涂地从最新位置消费，否则中间的数据变更就静默丢了。
3.4 为什么说变更流比双写更符合"事件溯源"的思路
双写是同步状态，变更流是传递事件。这两者带来一个核心差别：双写时你的同步逻辑必须知道"业务发生了什么"，变更流只要知道"数据变成了什么样"。
更具体地讲，变更流的消费端可以和业务系统完全分离。业务服务专注于 MongoDB 和 ES 各自的职责，同步代码迭代时不影响核心链路；新增一个搜索消费方时也不需要动业务代码。数据同步从"你主动推"变成了"你订阅变化"，这在架构上是更干净的分层。
当然，Change Streams 也不是银弹。它依赖 oplog，导致需要 MongoDB 副本集或分片集群环境，单机实例不支持；在分片集群上，Change Streams 的全局事件排序是弱于副本集的，因为不同分片的事件无法保证全局总序。如果你的业务强依赖所有数据的全局有序性，选型时要特别注意。
3.5 变更流的使用前提和集群要求
具体使用前，先确认你的 MongoDB 版本和环境：
- MongoDB 3.6 及以上，推荐 4.0 以上，因为 4.0 开始支持更多的聚合管道阶段和类型。
- 必须运行在副本集或分片集群中，且必须开启 oplog。单节点实例没有 oplog，无法使用 Change Streams。
- 连接方式需要使用副本集连接串，并确保
readConcern为majority（大多数 MongoDB 版本默认开启）。 - 如果你的集群启用了鉴权，需要给使用 Change Streams 的账号授予
read权限，同时建议使用专属的同步账号，不要直接复用业务账号。
4. 一个可落地的同步实现：从采集、投递到 Elasticsearch 写入
4.1 整体链路设计
把双写重构为变更流同步，我推荐一个经过实践检验的分层结构：生产者只负责采集和投递，消费者只负责转换和写入，中间再放一个消息队列做缓冲。
具体来说：
- MongoDB Change Streams 作为生产者，订阅目标集合的变更事件。
- 生产者把事件序列化后投递到 Kafka（或 RabbitMQ、Pulsar），投递成功后记录当前恢复令牌。
- 消费者从 Kafka 拉取事件，做字段映射和文档组装，然后写入 ES。
为什么要在中间加消息队列，而不是让消费者直接订阅 Change Streams？核心原因是解耦。Change Streams 的消费速度和 ES 的写入速度并不总是一致的。ES 写入遇到瓶颈时，消息队列可以暂存大量事件，相当于给同步链路加了一个缓冲区和熔断层。如果消费者直连 Change Streams，消费端一慢，就会阻塞 MongoDB 的订阅，处理不当可能拖慢数据库节点。
当然，如果你的数据量不大、对同步可靠性要求不极端，也可以省掉 Kafka，直接用 Change Streams 到 ES 的轻量管道。但我下面讲的代码还是会以"事件驱动 + 消息中间件"为主线，因为这是通用性最强的方案。
4.2 生产者端代码示例（Node.js + MongoDB Driver）
先看生产者端。这里我使用 Node.js 和官方的 MongoDB Node.js Driver 4.x 及以上版本。
javascript复制const { MongoClient } = require("mongodb");
const MONGO_URI = "mongodb://user:pass@mongo1:27017,mongo2:27017,mongo3:27017/?replicaSet=rs0";
const DB_NAME = "app_db";
const COLLECTION_NAME = "orders";
async function startChangeStreamProducer() {
const client = new MongoClient(MONGO_URI, { monitorCommands: true });
await client.connect();
const collection = client.db(DB_NAME).collection(COLLECTION_NAME);
const changeStream = collection.watch(
[
{
$match: {
$or: [
{ operationType: "insert" },
{ operationType: "update" },
{ operationType: "delete" },
{ operationType: "replace" }
]
}
}
],
{ fullDocument: "updateLookup" }
);
const sendToKafka = async (event) => {
// 伪代码：投递到 Kafka 并确认
// const result = await kafkaProducer.send({
// topic: "mongodb-orders",
// messages: [{ key: event.documentKey._id.toString(), value: JSON.stringify(event) }],
// });
console.log("send event:", event._id);
};
changeStream.on("change", async (next) => {
try {
await sendToKafka(next);
// 投递成功后，记录恢复令牌。注意：这里需要确保幂等，
// 如果投递失败，不能更新本地持久化的 resumeToken。
} catch (err) {
console.error("Failed to send event, will retry with backoff", err);
// 这里应该做重试，或者终止进程让上层拉起，
// 切不可直接吞掉错误继续消费。
}
});
changeStream.on("error", (error) => {
console.error("ChangeStream error", error);
// 连接断开、令牌失效等场景，需要重新初始化 Change Stream
});
}
startChangeStreamProducer();
生产者端有几个关键点需要强调。
第一，fullDocument: "updateLookup" 很重要。它保证 update 事件里包含完整的、更新后的文档内容。如果不配置这个选项，update 事件里只有变更字段，消费者要写 ES 时还得额外按 _id 回查 MongoDB，多一次查询，还引入了跨系统的一致性问题。
第二，投递事件和记录恢复令牌之间要保证顺序。我先投递到 Kafka，投递成功后才认为这个事件已经处理了，然后才去更新本地存储的恢复令牌。如果先更新令牌再投递，投递失败时事件会丢；如果先投递再更新令牌且投递成功但更新令牌失败，重启后会重复消费，这可以通过消费者端的幂等设计来兜底。
第三，遇到异常不能闷头重试。Change Streams 内部有自己的重连机制，如果网络抖动，流会自动重连。但如果遇到 resume token not found 这类错误，说明断点已经失效，必须走全量同步流程。
4.3 消费者端代码示例（Python + Elasticsearch）
消费者端的职责是把 Kafka 里的变更事件转换成 ES 的写入请求。我习惯用 Python 写消费者，因为 Python 的 Elasticsearch 客户端在处理批量写入时非常顺手。
python复制import json
from elasticsearch import Elasticsearch, helpers
from kafka import KafkaConsumer
ES_HOSTS = ["http://es-node1:9200", "http://es-node2:9200"]
KAFKA_BOOTSTRAP = "kafka1:9092,kafka2:9092"
TOPIC = "mongodb-orders"
GROUP_ID = "es-sync-orders"
es = Elasticsearch(ES_HOSTS)
def map_order_event(event):
operation = event["operationType"]
doc_id = event["documentKey"]["_id"]["$oid"]
if operation == "delete":
return {
"_op_type": "delete",
"_index": "orders",
"_id": doc_id,
}
full_document = event.get("fullDocument")
if not full_document:
# 如果某些 update 事件拿不到全量文档，回查 MongoDB 或跳过并告警
return None
# 转换 _id 为字符串
source = {
"id": doc_id,
"order_no": full_document.get("orderNo"),
"user_id": full_document.get("userId"),
"amount": full_document.get("amount"),
"status": full_document.get("status"),
"created_at": full_document.get("createdAt"),
"updated_at": full_document.get("updatedAt"),
}
if operation == "insert":
return {
"_op_type": "create",
"_index": "orders",
"_id": doc_id,
"_source": source,
}
# update/replace 统一用 index，整体覆盖
return {
"_op_type": "index",
"_index": "orders",
"_id": doc_id,
"_source": source,
}
def consume():
consumer = KafkaConsumer(
TOPIC,
bootstrap_servers=KAFKA_BOOTSTRAP,
group_id=GROUP_ID,
value_deserializer=lambda m: json.loads(m.decode("utf-8")),
auto_offset_reset="latest",
enable_auto_commit=False,
max_poll_records=500,
)
for batch in consumer:
actions = []
for msg in batch:
event = msg.value
action = map_order_event(event)
if action:
actions.append(action)
if actions:
success, failed = helpers.bulk(
es, actions, stats_only=False, raise_on_error=False
)
if failed:
# 失败的请求落盘到死信队列，或者打印告警
print("failed actions:", failed)
consumer.commit()
consume()
这段代码展示了三个关键设计。
第一，delete 事件简化成 _op_type: delete，按 _id 删除 ES 文档；insert 事件用 _op_type: create，如果文档已存在会报版本冲突；update 和 replace 事件统一用 index，整体覆盖 ES 文档。这样设计的好处是消费幂等：不管同一个文档的事件被消费多少遍，最终 ES 里的内容都和最后一次写 MongoDB 的文档内容一致。
第二，enable_auto_commit=False，并且只在批量写入 ES 完成后才手动提交 Kafka offset。这是为了避免"消息已消费但 ES 写入失败"导致数据丢失。至于重复消费的问题，由于 ES 的 _id 是幂等的，同样的文档写两遍不会有副作用。
第三，raise_on_error=False 让批量接口把失败项返回出来，你需要对这些失败项做额外处理。我在生产环境里的做法是：把失败项写到一个独立的"死信"Kafka topic 里，由单独的告警任务扫描并人工介入。不要把这些失败项重新扔回原 topic，否则会反复消费失败，把 Kafka 的堆积水位拉高。
4.4 为什么使用 Kafka 而不是直接调用 ES
有人会问：Change Streams 拿到事件后，直接调用 ES 写入不就行了吗？为什么要绕一圈 Kafka？
我举一个具体场景。假设某个时刻 ES 集群正在做大量分片迁移，或者正在执行段合并，写入吞吐下降了。如果生产者直接写入 ES，同步链路就会跟着变慢，进而阻塞 Change Streams 的消费，导致 MongoDB oplog 里的积压数据越来越多。严重时，MongoDB 节点会因为无法清理 oplog 而产生磁盘告警。
加上 Kafka 之后，生产者始终以恒定的速度把事件写入 Kafka，消费者按照 ES 的实际能力动态调整消费速度。即使 ES 挂了 5 分钟，Kafka 里的积压也会被保留，ES 恢复后再继续消费，数据不会丢。这套机制本质上就是把同步链路的稳定性边界从"实时同步"调整成了"可积压、可追赶"。
4.5 全量同步和增量同步怎么做
Change Streams 覆盖的是增量数据。如果 MongoDB 里已经积累了历史数据，你还需要先做一次全量同步，把存量数据灌入 ES，再启动增量同步。
常见的做法是"全量 + 增量并行"：
- 先记录当前 MongoDB 的 oplog 恢复位置（或当前时间）。
- 用 mongoexport、历史表扫描或 DataX 等方式把存量数据批量导入 ES。
- 全量导入完成后，启动 Change Streams，从步骤 1 记录的位置开始消费增量。
- 全量导入期间产生的增量事件，在启动 Change Streams 后会重新消费，配合 ES 的幂等覆盖，最终达到一致。
这里要特别警惕全量和增量的时间窗口重叠。如果全量导入过程中有新的写入，且 Change Streams 启动节点晚于这些写入，就会漏数据。所以步骤 1 之后的任何增量事件，都要从记录点开始完整消费。实际实现时，我会先启动一个只做投递的 Change Streams 生产者，把事件积压到 Kafka，然后开始全量导入，全量完成后再启动消费者。这样窗口重叠的问题就自动解决了。
5. 生产环境的扩展与异常处理：断点续传、幂等写入和监控告警
5.1 持久化恢复令牌的正确方式
前面提到过恢复令牌，这里展开讲一下持久化的姿势。生产环境里，我建议把恢复令牌存到 MongoDB 自身的一个系统集合里，或者存到 Redis。关键要求是：令牌的更新必须与事件投递到 Kafka 的动作保持原子性，或者至少不能出现"令牌提前推进，事件还没投递"的情况。
一个稳妥的方案是把令牌和投递动作放在同一个流程里：先投递 Kafka，投递成功后再把令牌写入 Redis。如果投递成功但写 Redis 失败，进程重启后会从旧令牌恢复，导致已经投递过的事件被重复消费。重复消费在消费者幂等的前提下是可以接受的。
这里还要注意，不要把恢复令牌的更新做成独立定时任务，比如"每 10 秒从内存里读当前令牌写到 Redis"。如果在这 10 秒窗口内进程崩溃，而这 10 秒里已经投递了数十条事件，重启后这些事件就会丢失。必须每条事件投递成功后立即更新令牌。
5.2 消费者端幂等设计
消费者的幂等性主要靠 ES 写入的 _id 唯一性来保证。无论是 create、index 还是 delete，只要 _id 是 MongoDB 文档的 _id，同一条消息被重复处理时，最终 ES 状态一致。
但这里有三个容易被忽略的细节：
- 不要把业务主键（比如 orderNo）当作 ES 文档的
_id。如果 MongoDB 中一条文档的业务主键变更了，而你用业务主键作为 ES_id，ES 里会残留旧文档。 - 处理 update 事件时，如果配置了
fullDocument: "updateLookup"，但文档在查询时已经被删除了，fullDocument可能为null。此时消费者要么跳过，要么主动向 ES 发一个 delete。 - delete 事件只含
_id，但 ES 里可能存在由历史脏数据造成的同名文档。用同一个_id删除是安全的，不需要额外条件。
5.3 重试与死信队列
生产环境里，ES 写入失败的场景很常见，比如字段类型冲突、分词器异常、ES 集群临时不可用。我的建议是区分两类错误：
第一类是可重试错误，如连接超时、429 限流、集群阻塞。这类错误应该让消费者线程按照指数退避策略重试，重试上限可以设为 3 到 5 次。不要无限重试，否则会拖垮整个消费线程。
第二类是不可重试错误，如字段类型不一致、文档里含有非法字符、索引不存在。这类错误无论重试多少次都会失败，应该直接进入死信队列，由专门的告警机制通知负责人。
在 4.3 的代码示例里，我把 raise_on_error=False 的失败项直接打印了，这在实际生产里是不够的。更好的做法是用一个独立的 Kafka topic（比如 mongodb-orders-dlq）存储失败消息，同时记录失败原因和原始事件，方便人工排查和事后回放。
5.4 监控指标和告警阈值
同步链路要上线，监控不能缺。我最关心这几个指标：
- Change Streams 消费者的延迟：当前事件时间与最新事件时间的差值。延迟持续增长说明 Kafka 堆积或消费者能力不足。
- Kafka 堆积消息数：lag 曲线如果一直上升，说明消费者处理速度跟不上生产者。
- ES 写入失败率：失败率突增通常意味着字段映射问题或集群异常。
- ES 写入拒绝数：HTTP 429 和 es_rejected_execution_exception 出现时，要考虑限流和扩容。
- 恢复令牌更新延迟：如果令牌长时间不变，可能 Change Streams 已断连。
你可以用 Prometheus 暴露这些指标，配合 Grafana 做看板。具体实现上，在消费者里面用 Prometheus client 记录 counter 和 histogram，在生产者里面记录 Change Streams 的事件处理耗时和投递成功数量。告警阈值我一般配置两条规则：延迟超过 5 分钟触发 warning，超过 30 分钟触发 critical；失败率超过 1% 触发 warning。
5.5 关于 ES 端索引模板和字段映射
同步链路跑起来之前，先在 ES 里把索引模板建好。很多人忽略这个，导致 Change Streams 消费端一启动，ES 自动创建索引，字段类型全被默认成 text 和 keyword，搜索效果完全不对。
我建议提前设计好 mapping。对于订单这类业务数据，orderNo 和 userId 用 keyword，amount 用 double 或 long，createdAt 和 updatedAt 用 date，状态字段用 keyword。如果有一些全文检索字段，比如商品标题、文章摘要，才用 text 并配置合适的分词器。
索引模板可以在 ES 启动时用初始化脚本创建，也可以在服务初始化时检查。总之，不要把 mapping 的创建交给首次写入数据的那一刻。
6. 从双写迁移到变更流：重构落地清单与经验总结
6.1 迁移前的评估：什么样的团队应该换，什么样的可以先不换
在决定是否迁移之前，先客观评估一下你当前的状态。如果你的场景属于下面这些，其实继续用双写也没太大问题：
- 数据量小，并发低，每天只有几百次写入。
- 同步链路可以容忍分钟级延迟，且已经通过定时任务稳定跑了一段时间。
- 团队没有多余的运维资源维护 Kafka 等额外组件。
- MongoDB 是单机或存储引擎不支持 Change Streams。
但如果出现以下信号，就应该认真考虑迁移了：
- 双写逻辑在业务代码里散落得到处都是，新增写入入口总忘记同步 ES。
- 数据不一致需要靠人工定时脚本去修补，且修补逻辑越来越复杂。
- 业务对搜索实时性的要求越来越高，分钟级补偿满足不了需求。
- 团队已经引入了消息队列，且愿意把同步链路作为一个独立的子系统来维护。
我个人是"及时换派"。双写方案的复杂度是随业务线性增长的，而变更流方案的复杂度在搭建初期集中一次爆发，之后就趋于平缓。从长期维护成本看，后者明显占优。
6.2 迁移的步骤拆解
按照我走过的路径，迁移过程可以分成六步：
- 搭建消息队列主题和 ES 索引模板，准备好消费者服务骨架。
- 启动 Change Streams 生产者，只投递不消费，让事件积压在 Kafka 里。
- 执行存量数据全量导入，把 MongoDB 历史数据批量写入 ES。
- 全量导入完成后，启动消费者，从 Kafka 里消费之前积压的增量事件。
- 业务代码里逐步删除双写逻辑，每删一个入口就验证一次搜索数据。
- 观察一段时间，确认无数据不一致问题后，下线补偿脚本。
这个顺序里最关键的是第 2 步和第 3 步之间的配合。先让生产者跑起来，保证任何增量事件都不会丢，再开始全量导入，最后消费者再追平。这样即使全量导入耗时很长，数据也不会出现永久性缺口。
6.3 常见坑和避坑建议
我在迁移中实际踩过几个坑，写出来供你参考。
第一坑：没有配置 fullDocument: "updateLookup"。消费者拿到的 update 事件里没有完整文档，为了拼 ES source，还得回查 MongoDB。查询是异步的，串联起来复杂度飙升。解决办法就是配置 updateLookup，让 MongoDB 在推送事件时自动带上最新文档内容。
第二坑：没有处理 delete 事件。有时候业务里删除操作很少，很容易被忽略。但一旦出现删除，ES 里就会留下幽灵文档，搜索结果里会出现已经删除的数据。这个问题在搜索场景里很致命，因为用户看到的内容不应该包括已经下架或注销的数据。消费者代码里必须显式处理 delete。
第三坑：Kafka 的 auto.offset.reset 配错了。如果配置成 earliest，消费者第一次启动时会从 topic 最早的 offset 开始消费，可能把很久以前的旧事件全部重新写入 ES，白白增加大量 I/O。增量场景建议配置 latest，全量场景用先生产者后消费者的方式解决。
第四坑：忽略 oplog 大小。MongoDB 的 oplog 默认大小取决于磁盘空间，通常为磁盘的 5%。如果数据变更量很大，而消费者突然停机，oplog 可能被新写入覆盖。恢复令牌失效后，你只能做全量重灌。建议在部署时把 oplog 大小调整到一个合理的值，比如 100GB 或更大，并在监控里增加 [oplog 剩余时间] 指标。
第五坑：全量导入和增量事件处理字段格式不一致。全量导入如果用了自定义的字段名，而增量消费者映射的是 MongoDB 文档里的字段名，两边写出的 ES 文档结构就不一样，搜索字段对不上。解决方法是全量导入也走同样的字段映射逻辑，不要图省事手动写一遍。
6.4 迁移后的收益复盘
讲完坑，说点实际的收益。迁移完成后，最直观的变化是业务代码里不再出现 ES 相关代码，新增写入入口只需要关心 MongoDB 本身。我之前维护的那个双写项目，业务服务里大概有 30 多处 ES 调用，重构后直接降到了 0。这带来的好处不止是代码量减少，更重要的是新增业务功能的开发效率提升了，同步逻辑的 bug 从"到处都有可能"变成了"只存在于消费者服务里"。
另一项收益是故障隔离。ES 集群出现故障时，业务写入完全不受影响，消息在 Kafka 里积压，ES 恢复后自动追平。以前 ES 抖动会导致核心业务接口报错，现在最多是搜索结果延迟更新。产品经理接收到"搜索结果有几秒延迟"这个体验问题，比起"下单失败"要容易接受得多。
6.5 给还在纠结方案的人最后说几句
同步方案没有绝对的好坏，关键是匹配你的业务形态和团队能力。双写方案适合快速验证期，变更流方案适合稳定发展期。如果你已经在双写路上走得很痛苦，不必继续打补丁，变更流这条路是成熟的、可落地、社区实践也很丰富。
我的经验里最核心的一句总结是：把 MongoDB 当作数据源，把 ES 当作搜索索引，把同步当作一个独立的数据管道，而不是业务请求的一部分。架构上拆开之后，很多看似复杂的问题都会迎刃而解。