MongoDB allowDiskUse处理大数据聚合的方法

在 MongoDB 中使用 allowDiskUse: true 时，不少开发者容易踩坑。本文将从原理到实践，详细拆解这个选项的正确用法与常见误区。核心结论：它必须作为 aggregate() 方法的 options 参数传入，而非 pipeline 数组的一部分；它只能缓解单个分片（shard）本地的内存压力，却无法解决 mongos 节点的归并 OOM 问题。真正需要警惕的，是 $group 阶段的 _id 字段必须至少包含分片键的前缀，才能实现聚合下推，避免全量数据传输。

allowDiskUse: true 必须作为 options 参数传入，不是 pipeline 一部分

很多人在编写聚合管道时，习惯将 allowDiskUse: true 直接放入 pipeline 数组，例如：[{$match: {...}}, {$group: {...}}, {allowDiskUse: true}]。这种写法会导致 MongoDB 抛出 Unrecognized pipeline stage name: allowDiskUse 错误，因为它不是一个合法的 stage 阶段。

正确的做法是将该选项作为 aggregate() 的第二个参数，一个独立的纯对象传入。例如：

db.orders.aggregate([{ $match: { status: "shipped" } },{ $group: { _id: "$region", total: { $sum: "$amount" } } }], { allowDiskUse: true })

• 在 Node.js 驱动中同样如此：collection.aggregate(pipeline, { allowDiskUse: true })，避免使用已废弃的链式调用 cursor.allowDiskUse()。
• PyMongo 中也是通过第二个位置参数传入：collection.aggregate(pipeline, allowDiskUse=True)。
• 如果同时需要 maxTimeMS 等其他选项，请统一放入同一个 options 对象中，不要分散书写。

allowDiskUse 只缓解 shard 本地聚合内存压力，不解决 mongos 归并 OOM

开启 allowDiskUse: true 后依然出现内存溢出？别急着怀疑配置，很可能是因为踩中了分片集群的致命陷阱：mongos 将各个 shard 的原始数据全部拉取到自身内存中进行归并，而你并未让每个 shard 提前完成“消化”操作。

举个例子：集合按 { user_id: 1 } 分片，但聚合时却按 { order_date: { $dateToString: { format: "%Y-%m" } } } 分组。此时每个 shard 都需要将匹配的全部文档发送给 mongos，即使单个 shard 只有 10 万条，10 个 shard 加起来就有 100 万条文档在 mongos 内存中重组、分组、排序，内存不崩溃才奇怪。

• 注意：allowDiskUse: true 不会让 mongos 将归并结果写入磁盘，因为 mongos 本身不支持磁盘归并。该选项仅对 shard 本地的子聚合阶段有效。
• 真正发挥作用的是各 shard 本地的子聚合阶段（例如 $group 之前的 $match、$sort），它们可以利用磁盘暂存中间结果。
• 如何验证是否实现了分片下推？使用 explain("executionStats") 查看 shards 数组中每个分片的 totalDocsExamined 是否远小于 nReturned。如果两者接近，说明几乎未做过滤，属于广播扫描。

比 allowDiskUse 更关键的是让 $group 和分片键对齐

与其不断调大内存或依赖磁盘，不如从根源上避免全量数据传输。核心原则只有一条：$group 的 _id 字段至少要包含分片键的前缀。

假设分片键是 { region: 1, user_id: 1 }，以下写法是安全的：

{ $group: { _id: "$region", total: { $sum: "$amount" } } }
{ $group: { _id: { region: "$region", type: "$type" }, total: { $sum: "$amount" } } }

但下面这些写法就非常危险：

{ $group: { _id: "$user_id", total: { $sum: "$amount" } } } // user_id 是分片键第二字段，但单独使用无法路由
{ $group: { _id: { day: { $dateToString: { format: "%Y-%m-%d", date: "$created_at" } } }, total: { $sum: "$amount" } } } // 完全无关

• 只要 _id 字段能被分片键前缀覆盖（例如上例中的 region），各 shard 就能独立完成子聚合，仅返回少量汇总结果给 mongos，内存压力瞬间消失。
• 如果业务必须按非分片字段聚合，建议优先建立预聚合表，并确保其分片键与原表一致。
• $unwind 后再执行 $group 属于高危操作——数组展开后文档数量暴增，极易突破单 shard 的内存限制，即使开启 allowDiskUse，也常因磁盘 I/O 成为新的瓶颈。

allowDiskUse 开启后仍慢？检查磁盘 I/O 和 WiredTiger 缓存竞争

磁盘已启用，但查询依然卡在 30 秒以上？不要只盯着 MongoDB 日志，还需要检查底层资源状况。

WiredTiger 引擎默认使用内存作为缓存（wiredTigerCacheSizeGB），而 allowDiskUse 生成的临时文件也走同一块磁盘。当聚合操作大量落盘时，可能和 WiredTiger 的 checkpoint、journal 刷盘争抢 I/O 资源。

• 使用 iostat -x 1 观察 %util 和 await：如果 %util 长期高于 90% 且 await 超过 50ms，说明磁盘已经饱和。
• 临时文件默认存储在 MongoDB 数据目录下的 _tmp 子目录，无法跨盘。生产环境建议将 dbPath 和临时目录挂载到不同的物理磁盘上（可通过 symlinks 或 mount bind 实现）。
• 如果并发聚合较多，可考虑降低单次聚合的 batchSize，或添加 $limit 提前截断数据——allowDiskUse 并不会减少计算量，只是用空间换时间。

实际上，真正限制性能的往往不是语法或配置，而是分片键设计与聚合意图之间的错位。磁盘只是缓冲垫，而非承重墙。只要将分片键对齐，很多问题根本不会出现。