概述
MongoDB 是一款高性能、开源的 NoSQL 文档数据库，以灵活的文档模型与强大的横向扩展能力著称，广泛应用于 Web 应用、移动应用与大数据分析场景。DataBuddy 数据接入支持将 MongoDB 作为来源端进行实时整库同步与离线同步。本文介绍其连接配置、能力支持范围、前提条件与常见问题。
支持的版本
类型 | 支持版本 |
自建 MongoDB | 3.6 / 4.0 / 4.2 / 4.4 / 5.0 / 6.0 / 7.0 / 8.0 |
腾讯云数据库 MongoDB | 3.6 / 4.0 / 4.2 / 4.4 / 5.0 / 6.0 / 7.0 / 8.0 |
实时同步（Change Streams）要求 MongoDB 版本 ≥ 3.6。
读取能力
能力 | 离线读 | 实时整库读 |
支持 | ✓ | ✓ |
使用限制
实时同步限制
限制项 | 说明 |
版本要求 | MongoDB 版本必须 ≥ 3.6 |
副本集 | 需配置为副本集（Replica Set）模式才能使用 Change Streams |
oplog 保留 | 需要足够的 oplog 保留时间以支持增量同步 |
系统集合 | 不支持 system.* 等系统集合的同步 |
离线同步限制
限制项 | 说明 |
单文档大小 | 不超过 16 MB（MongoDB 限制） |
嵌套深度 | 建议控制文档嵌套深度，过深可能影响性能 |
支持的字段类型
字段类型 | 离线读 | 实时读 |
Int32 / Int64 / Long / Double / Decimal128 | ✅ | ✅ |
Boolean / String / ObjectId / UUID / Symbol / Regex | ✅ | ✅ |
JavaScript / BinData | ✅ | ✅ |
Date / Timestamp | ✅ | ✅ |
Object / Array / Null / Undefined / MinKey / MaxKey / DBPointer | ✅ | ✅ |
MongoDB 为 Schema-free 数据库，同一字段可能存在多种类型，建议在源端统一字段类型以避免同步异常。
实时同步支持的 DML / DDL
DML
操作 | 是否支持 | 说明 |
INSERT / UPDATE / REPLACE / DELETE | ✅ | 文档级变更操作 |
DDL
操作 | 是否支持 |
DROP COLLECTION / DROP DATABASE / RENAME COLLECTION | ❌ |
MongoDB 基于 Change Streams 进行变更捕获，不支持 DDL 变更的自动同步。集合的删除、重命名等操作需要在目标端手动处理。
前提条件
1. 确认副本集配置（仅实时同步）
rs.status()
2. 配置账号权限
离线同步 ：
use admindb.createUser({user: "wedata_user",pwd: "your_password",roles: [{ role: "read", db: "your_database" }]})
实时同步 ：
use admindb.createUser({user: "wedata_cdc_user",pwd: "your_password",roles: [{ role: "read", db: "your_database" },{ role: "read", db: "local" } // 读取 oplog 必需]})
3. 配置 oplog 大小（仅实时同步）
use localdb.oplog.rs.stats() // 查看当前 oplog 配置db.adminCommand({ replSetResizeOplog: 1, size: 10240 }) // 单位 MB
修改 oplog 大小需要在副本集每个节点执行。
创建数据源
操作步骤
1. 登录 DataBuddy 控制台。
2. 在顶部切换到目标地域和 Workspace。
3. 进入 数据接入 > 任务管理 > 数据源管理 （或 平台管理 > 数据源管理 ）。
4. 点击 添加数据源 ，选择 MongoDB 。
5. 填写连接配置与认证信息，详见 参数说明。
6. 点击 测试连接 （参见 数据源连通性测试）。
7. 测试通过后点击 保存 或 保存 & 创建任务 。
参数说明
参数 | 说明 | 是否必填 |
数据源名称 | 数据源在工作空间内的唯一标识 | 是 |
连接地址 | MongoDB 连接地址（见下方格式） | 是 |
数据库 | 默认连接的数据库 | 是 |
用户名 | 数据库连接账号（如开启认证） | 视认证情况 |
密码 | 数据库连接密码（如开启认证；支持 SSM 凭证托管） | 视认证情况 |
数据源版本 | 见 支持的版本 | 是 |
连接地址格式
部署方式 | 格式示例 |
单节点 | mongodb://host:port |
副本集 | mongodb://host1:port1,host2:port2,host3:port3/?replicaSet=rsName |
分片集群 | mongodb://mongos1:port1,mongos2:port2 |
完整示例：
mongodb://10.0.0.1:27017,10.0.0.2:27017,10.0.0.3:27017/?replicaSet=rs0mongodb://10.0.0.1:27017/mydb?authSource=admin
在数据接入任务中使用
实时整库
配置项 | 说明 |
来源表范围 | 指定集合 （仅同步选中的几个，新增集合需重启）/ 正则匹配 （指定库名 + 集合名正则，符合规则的新增集合自动接入） |
读取模式 | 全量 + 增量 / 仅增量 |
订阅类型 | 可勾选 INSERT / UPDATE / DELETE，至少勾选一种 |
离线单表
参数 | 说明 |
库 / 集合 | 必填；支持选择或手动输入 |
筛选条件 | MongoDB 查询条件（JSON 格式） |
筛选条件示例：
{"age": {"$gte": 18}, "status": "active"}{"create_time": {"$gte": {"$date": "2024-01-01T00:00:00Z"}}}
最佳实践
账号权限最小化 ：使用专用账号，避免 root 权限。
oplog 保留时间 ：建议 ≥ 72 小时，防止任务重启后数据丢失。
索引优化 ：离线同步时在查询字段上建索引以提升读取效率。
网络打通 ：优先使用内网连接。
常见问题
Q：连接失败？
A：检查网络连通性、确认用户名密码正确、检查
authSource 配置。Q：报错 Change Streams 不可用？
A：MongoDB 未配置为副本集模式或版本 < 3.6。请将 MongoDB 配置为副本集，并升级到 3.6 及以上版本。
Q：增量同步报错找不到 oplog？
A：oplog 保留时间太短，已被覆盖。增加 oplog 大小：
db.adminCommand({ replSetResizeOplog: 1, size: 20480 })
Q：同步过程中报错类型不匹配？
A：MongoDB 是 Schema-free 的，同一字段可能存在不同类型。建议在源端统一数据类型，或在写入端配置类型转换。
Q：某些文档同步失败？
A：单文档超过 16 MB 限制。请拆分大文档，或使用 GridFS 存储大文件。
相关文档
创建单表同步任务
