在排查磁盘空间问题时，很多人第一反应是执行db.collection.stats()看一眼，但这个方法返回的结构因版本而异，而且不方便进一步加工处理。MongoDB从3.4版本开始，把集合统计能力搬进了聚合管道的$collStats阶段，其中storageStats选项返回的数据与collStats命令的输出保持一致，却能配合$project、$group等阶段做二次计算，这让存储分析变得灵活得多。本文重点讲解$storageStats的输出结构、典型用法以及常见误区。
一、$storageStats的基本用法与输出结构
$storageStats并不是一个独立的管道阶段，它是$collStats阶段的配置选项。使用时必须通过聚合操作作用在具体的集合上，语法非常简单：
db.orders.aggregate([
{
$collStats: {
storageStats: {}
}
}
])
返回结果是一个单文档流，核心字段包括：size表示压缩后的数据总大小（字节），storageSize是存储引擎已分配的空间，count是文档数量，avgObjSize是平均文档大小，nindexes和totalIndexSize描述索引数量与索引总占用。如果集合为空，storageSize可能是0，此时要留意后续计算中的除零问题。
需要特别注意的是，这些数值单位都是字节，直接阅读不太友好。可以在管道后面追加$project做单位换算，这也是管道方式相比传统命令最大的优势——数据可以继续流动加工，不必先取回客户端再处理。
二、实战示例：计算压缩率与定位大索引
单看原始数字意义不大，实际运维中更关心两个问题：WiredTiger的压缩效果如何，以及哪个索引占用了最多的空间。下面的示例把字节数换算成MB，并利用$objectToArray把索引大小对象展开成可比较的数组：
db.orders.aggregate([
{ $collStats: { storageStats: {} } },
{ $addFields: {
dataSizeMB: { $round: [{ $divide: ["$size", 1048576] }, 2] },
storageMB: { $round: [{ $divide: ["$storageSize", 1048576] }, 2] },
// 未压缩估算 = 平均文档大小 x 文档数
logicalMB: { $round: [{ $divide: [{ $multiply: ["$avgObjSize", "$count"] }, 1048576] }, 2] }
}},
{ $addFields: {
// 展开索引对象，按大小降序
indexes: {
$sortArray: {
input: {
$map: {
input: { $objectToArray: "$indexSizes" },
as: "idx",
in: {
name: "$$idx.k",
sizeMB: { $round: [{ $divide: ["$$idx.v", 1048576] }, 2] }
}
}
},
sortBy: { sizeMB: -1 }
}
}
}},
{ $project: { dataSizeMB: 1, storageMB: 1, logicalMB: 1, indexes: 1 } }
])
通过logicalMB和dataSizeMB的对比，可以估算出压缩前后的比例。如果发现某个索引的大小接近甚至超过数据本身，就要评估该索引是否真的被查询使用，可以结合$indexStats阶段查看索引的访问次数，把长期零访问的大索引删掉，往往能立刻释放可观的磁盘空间。
另一个实用技巧是计算碎片率。storageSize减去freeStorageSize就是实际被数据占用的部分，两者差距越大说明碎片越严重。大量删除或更新操作后，这个差值通常会明显增大，此时执行compact命令或重新同步副本集成员可以回收空间。
三、版本差异、分片环境与常见误区
不同版本的字段命名有细微变化，比如MongoDB 4.4之前用totalIndexSize统计索引占用，而新版WiredTiger引擎下部分字段含义有调整，写脚本前最好先确认目标版本的官方文档。此外，$collStats还支持scale选项，可以传一个除数让所有尺寸字段直接以KB或MB为单位返回，简化换算：
db.orders.aggregate([
{
$collStats: {
storageStats: { scale: 1048576 }
}
},
{ $project: { size: 1, storageSize: 1, totalIndexSize: 1, count: 1 } }
])
在分片集群中使用时要注意，$collStats默认只在聚合请求路由到的那个分片上执行，要拿到全集群的统计需要遍历所有分片，或者使用latencyStats配合其他监控手段。分片环境下更推荐从config.shards出发，对每个分片逐一执行聚合再汇总。
常见的误区还有几个：一是把size和storageSize混为一谈，前者是压缩后逻辑数据量，后者包含预分配和碎片；二是忽略了索引也占磁盘，有时索引占用能达到数据的30%以上；三是忘记avgObjSize在集合为空时不存在，管道里直接引用会报字段缺失，建议用$ifNull兜底。理解这些细节后，$storageStats就能成为容量规划和空间治理的可靠依据，配合定时脚本采集，还可以轻松搭建一套自己的存储增长趋势监控。