MongoDB GridFS 大文件存储实战：分块原理、断点续传与避坑指南

提到大文件存储，很多人的第一反应都是找 FastDFS、MinIO、Ceph 这类分布式文件系统，再不济就是买个对象存储服务。但在某些资源受限、服务要轻量、又不想额外引入一堆组件的时候，MongoDB 自带的 GridFS 其实是一个被严重低估的方案。它不需要你搭什么新服务，只要你已经在用 MongoDB，就天然拥有了一套可拆分、可复制、支持断点续传思路的文件存储能力。

这篇文章就围绕 GridFS 的上传、下载、分块原理、适用边界和实战坑位展开，后端开发者、数据工程师都能直接参考。内容偏实践向，不整虚的，讲清楚它到底怎么用、为什么这么用、什么场景千万别用它。

1. GridFS 的整体设计思路与核心原理

1.1 BSON 文档 16MB 限制逼出来的分块方案

先理解一个背景：MongoDB 的单个文档大小上限是 16MB，这个限制不是随便拍脑袋定的，而是和 BSON 文档的序列化、网络传输、内存分配机制强相关。一次文档读写要在内存里构造完整的 BSON 对象，如果允许单文档无限大，内存和网络的开销都会失控，所以官方直接锁死了 16MB。

但业务里确实会有超过 16MB 的文件需要存，视频片段、数据集、压缩包、日志归档等等。GridFS 的思路很简单粗暴：把一个大文件切成 N 个 255KB（默认）的小块，每个小块独立存成一个文档，然后再用一个文档记录这些块的元信息和归属关系。这样一来，任何单条文档都不超过 16MB，却可以组合出 TB 级别的文件。

这个设计和经典的"分片上传"思路同源，相当于 MongoDB 在官方驱动层面帮你实现了分片逻辑。你不用自己写拆文件、合并文件、记录分段状态的代码，驱动已经做了。

1.2 两个核心集合：fs.files 和 fs.chunks

GridFS 默认使用两个集合来配合存储，搞清楚这两个集合的关系，是理解整个 GridFS 的钥匙。

fs.files（文件元数据表）：每个被存储的文件在这里有一条记录，包含文件 ID、文件名、文件大小（字节）、块大小（chunkSize）、上传时间、MD5 校验值，还可以塞进自定义 metadata 字段。

fs.chunks（数据块表）：文件的实际二进制内容被切成多个块，每一块是这里的一条记录。关键字段有 files_id（关联 fs.files 的 _id）、n（块序号从 0 开始）、data（二进制数据本身）。

用数据库的术语来讲，这就是一张主表和一张从表，通过 files_id 做外键关联。读取文件的时候，先查 fs.files 拿到文件信息和 chunkSize，再按顺序读 fs.chunks 中的块，拼接还原出完整文件。上传则正好反过来，先切块写入 fs.chunks，再写入 fs.files 元数据。

这里有个很容易踩的坑：删除文件必须同时删除 fs.files 里对应的元数据记录，以及 fs.chunks 里所有 files_id 等于该 ID 的块记录，只删一边会导致数据不一致。用官方驱动里的 delete 方法一般不会出问题，但如果有人直接操作集合去做清理，就容易漏。

2. 环境准备与 PyMongo 驱动的选择

2.1 准备 MongoDB 环境和 Python 依赖

GridFS 不是独立服务，是 MongoDB 的能力之一，所以环境准备就是准备 MongoDB 本身。本地调试我推荐用 Docker 起一个实例，省去安装配置的折腾：

docker run -d --name mongodb-gridfs \ -p 27017:27017 \ -e MONGO_INITDB_ROOT_USERNAME=admin \ -e MONGO_INITDB_ROOT_PASSWORD=admin123 \ mongo:6.0

连接串就写成mongodb://admin:admin123@localhost:27017。

Python 这边需要安装pymongo，它是 Mongo 官方推荐的 Python 驱动，GridFS 功能直接集成在驱动里，不需要额外装第三方包：

pip install pymongo

注意这里有个小坑。pymongo里和 GridFS 相关的模块有两个入口，一个是旧式的gridfs.GridFS，一个是推式的gridfs.GridFSBucket。两者都能用，但GridFSBucket才是官方推荐的现代 API，它支持流式上传下载、更完善的异常处理。老代码里的GridFS类现在基本只做兼容保留，新项目建议直接用GridFSBucket。

2.2 可视化工具 confirm 数据写入效果

写代码之前，先用 MongoDB Compass 或者命令行连上去看一眼，确认初始状态。连上之后你会发现，数据库里一开始并没有fs.files和fs.chunks这两个集合，它们是在第一次用 GridFS 写入文件时才被自动创建的。

这一点也说明了 GridFS 的"懒加载"机制：你不往里存文件，它不占任何额外空间。所以即使 MongoDB 本身还跑着其他业务，你完全可以在同一个实例上启用 GridFS，互不干扰。

3. 文件上传的完整实现与关键参数剖析

3.1 用 GridFSBucket 完成基础上传

直接上代码，这是最基础的上传实现：

from pymongo import MongoClient from gridfs import GridFSBucket client = MongoClient('mongodb://admin:admin123@localhost:27017') db = client['file_store'] bucket = GridFSBucket(db) with open('./big_data.csv', 'rb') as f: file_id = bucket.upload_from_stream( 'big_data.csv', f, chunk_size_bytes=1024 * 1024, # 1MB 分块 metadata={'source': 'local_server', 'tag': 'daily_backup'} ) print(f'文件 ID: {file_id}')

upload_from_stream接收源文件流并写入 GridFS，返回的 ID 是系统生成的 ObjectId，后续下载、删除都可以靠它定位文件。

这里最难理解的就是chunk_size_bytes这个参数，默认 255KB，为什么要调？我实测下来的体会是：分块大小影响的是读取块的数量和网络往返次数。块越小，单次传输的数据量越小，但块数量多，查询和传输次数指数增加；块越大，块数量少，但单块加载到内存的开销变大。1GB 文件，默认 255KB 大约需要 4000 个块；调到 1MB，只要 1024 个块，读取时 MongoDB 的查询次数减少约 75%。我自己的经验是普通办公场景 1MB 比较均衡，视频大文件可以再往上调，但建议单块不要超过 4MB，否则单文档又逼近 BSON 上限，分块的意义就没了。

metadata 字段是我强烈建议每次上传都带的。你不带也能用，但带上之后，查询文件、做数据治理、清理过期文件会方便很多。比如给你的文件打上expire_at标记，后面写个定时任务扫出来删掉，比硬翻 filename 字段靠谱得多。

3.2 验证写入结果：看 chunks 是怎么存的

上传完成后，到 MongoDB 里看一眼数据：

# 查看元数据 db.fs.files.find().pretty() # 查看分块情况，统计块数量 db.fs.chunks.countDocuments({ files_id: ObjectId('xxx') })

你会发现fs.files里存了length、chunkSize、uploadDate、md5这些字段，fs.chunks里每条记录的n从 0 开始递增，data字段是二进制类型。

放一个我之前排查问题时的真实数据片段：

{ "_id": ObjectId("661e2c8a9f1b2c3d4e5f6a7b"), "filename": "server_access.log", "length": 5237760, "chunkSize": 1048576, "uploadDate": ISODate("2024-04-16T08:32:10Z"), "md5": "d41d8cd98f00b204e9800998ecf8427e", "metadata": { "source": "local_server" } }

这个文件的 length 是 5,237,760 字节，块大小 1MB，所以应该有 5 个块（前 4 个 1MB + 最后 1 个约 66KB），去查fs.chunks数量确认正好 5 条。这种验证方式能帮你迅速确认分块逻辑是否按预期走了。

3.3 上传的文件名冲突和重名覆盖问题

GridFS 的filename字段并不具备唯一性约束，同一个文件名上传两次会生成两条独立文件记录。这其实也是设计上的一种取舍：允许同名文件存在，通过不同的_id区分它们。

所以下载的时候，如果用open_download_stream_by_name，它默认返回的是最新的一条（按 uploadDate 倒序），否则就要手动指定文件 ID。如果业务上需要"覆盖"某个文件，正确姿势是先查旧文件 ID，delete 掉，再上传新的，而不是依赖 MongoDB 去自动覆盖。

4. 文件下载与断点续传的实战实现

4.1 按文件 ID 下载到本地文件

下载是上传的逆过程，同样用 GridFSBucket 完成。注意一个细节：官方 API 分成了"按文件名下载"和"按文件 ID 下载"，工程上我强烈建议优先按文件 ID 走。原因很简单，文件名不唯一，按名字下载拿到的不一定是你要的那份，尤其在系统运行一段时间后，同名文件堆积，容易出现诡异问题。

from pymongo import MongoClient from gridfs import GridFSBucket client = MongoClient('mongodb://admin:admin123@localhost:27017') db = client['file_store'] bucket = GridFSBucket(db) file_id = '661e2c8a9f1b2c3d4e5f6a7b' # 请换成真实的 _id try: with open('./downloaded_report.pdf', 'wb') as f: bucket.download_to_stream_by_name( 'report.pdf', # 如果文件名不唯一，可能下到不确定的版本 f ) print('下载完成') except Exception as e: print(f'下载失败: {e}')

这种写法有一个常见的异常场景：目标文件在某次清理中被删除，download_to_stream_by_name会直接抛出NoFile异常，所以必须用 try-except 捕获。之前有一次线上任务就是在处理批量导出时，某个文件被别人清了，没有捕获异常导致整个导出任务中断，排查了老半天才定位到是 GridFS 的文件不存在了。所以下载代码一定要对NoFile做专门处理。

4.2 流式下载：处理 1GB 以上大文件的正确姿势

GridFS 的流式下载 API 设计得非常巧妙，它不需要把整个文件加载到内存里，而是逐个 chunk 读取并写入目标流。对于动辄几个 GB 的视频文件，这一点非常关键。

from pymongo import MongoClient from gridfs import GridFSBucket, NoFile client = MongoClient('mongodb://admin:admin123@localhost:27017') db = client['file_store'] bucket = GridFSBucket(db) def download_large_file(file_id, local_path): try: stream = bucket.open_download_stream(file_id) with open(local_path, 'wb') as f: while True: chunk = stream.read(1024 * 1024) # 每次读 1MB if not chunk: break f.write(chunk) print(f'下载完成，长度: {stream.length} 字节') except NoFile: print('文件不存在，请检查 file_id')

这里面的关键点是stream对象内部维护了一个游标，每次read()只从 MongoDB 拉取需要的 chunk。如果你在 read() 循环里加了进度打印，就能看到它是"边读边写"，不是一次性全部加载到内存的。

实际使用中我还喜欢加一个文件大小的判断逻辑，如果stream.length和预期的文件大小对不上，就直接报警，这样可以尽早发现文件数据不一致的问题。这个方法成本极低，但效果很好。

4.3 断点续传的实现思路与代码骨架

GridFS 的特性让断点续传变得非常简单，因为文件是分块的，我们只需要记录已经下载到第几个 chunk，然后从那个 chunk 继续读就行。

from pymongo import MongoClient from gridfs import GridFSBucket, NoFile client = MongoClient('mongodb://admin:admin123@localhost:27017') db = client['file_store'] bucket = GridFSBucket(db) def download_with_resume(file_id, local_path, checkpoint_path='download_meta.txt'): # 先检查本地是否已有部分下载的文件 offset = 0 try: with open(checkpoint_path, 'r') as f: offset = int(f.read().strip()) except (FileNotFoundError, ValueError): offset = 0 try: stream = bucket.open_download_stream(file_id if offset >= stream.length: print('已经下载完成，跳过') return # 以追加模式打开本地文件 with open(local_path, 'ab') as f: stream.seek(offset) while True: chunk = stream.read(1024 * 1024) if not chunk: break f.write(chunk) offset += len(chunk) # 定期更新断点记录 if offset % (10 * 1024 * 1024) < 1024 * 1024: with open(checkpoint_path, 'w') as cp: cp.write(str(offset)) # 下载完毕后清理 checkpoint import os if os.path.exists(checkpoint_path): os.remove(checkpoint_path) except NoFile: print('文件不存在') except Exception as e: # 发生异常时保存 checkpoint，以便下次续传 with open(checkpoint_path, 'w') as cp: cp.write(str(offset)) print(f'下载中断: {e}')

注意这里的seek()方法，它可以直接跳到指定偏移量的 chunk 边界，这是 GridFS 流对象自带的方法，普通文件的 seek 没法这么便捷。这个思路同样适用于上传场景，分段上传时只需要记录文件 ID 和已传块数，就能从断点继续。

5. GridFS 的适用边界与小文件存储方案

5.1 何时该用 GridFS，何时不该用

实践中我见过很多团队把 GridFS 当万能存储来用，结果性能踩坑。这里直接给一个速查清单：

尤其是最后一行，这是最容易出问题的点。如果一个 2MB 的图片被频繁访问，每次都要查 files 表 + 查多个 chunks 表，性能远比直接从普通字段读取慢。所以 GridFS 的最佳场景是"冷数据归档"和"大文件存储"，它不是为高频热点数据设计的。

5.2 小文件的最优解：BSON BinData

对于小于 16MB 的文件，更优雅的做法是直接存进 BSON 的 BinData 类型。比如用 PyMongo 存：

from pymongo import MongoClient client = MongoClient('mongodb://admin:admin123@localhost:27017') db = client['file_store'] col = db['small_files'] with open('./logo.png', 'rb') as f: data = f.read() col.insert_one({ 'name': 'logo.png', 'content': data, # BinData 'size': len(data), 'content_type': 'image/png' })

这样读取只有一个普通文档查询，性能远优于 GridFS。很多人会问"那我是不是可以完全不用 GridFS 了"，我的建议是：小文件别用，大文件必须用。系统里两者可以共存，不存在互斥关系，实际项目里应当通过文件大小阈值来分流，这样整体的效率最高。

6. 常见问题排查与性能优化经验

6.1 高频问题速查表

我把平时排查 GridFS 问题过程中遇到的高频问题整理成了一张表，方便按图索骥：

其中"删除文件后磁盘空间没释放"最容易被人误判为 Bug，实际是 MongoDB 在操作系统层面预分配了数据文件，不会因为删了文档就立刻把空间还给操作系统。这种机制是为了性能考虑，如果你真的在意磁盘回收，只能做数据文件级的整理。

6.2 索引优化：三个必查的索引规则

GridFS 查询性能的关键在索引，这也是我在优化过程中收获最大的部分。

首先，fs.chunks表上必须有一个{ files_id: 1, n: 1 }的复合唯一索引，否则你在读取文件并按顺序拼接块时会做全表扫描，数据量一大瞬间卡死。用 PyMongo 这样创建：

db['fs.chunks'].create_index( [('files_id', 1), ('n', 1)], unique=True )

其次，fs.files表上应该给filename加索引，方便按文件名查找。如果业务里经常用 metadata 里的字段做筛选，也给 metadata 加索引。

最后是排序索引，如果你的业务会按上传时间展示文件列表，uploadDate加个索引可以让排序走索引，避免内存排序。

说一个我踩过的坑：某个环境里 chunks 集合没建复合索引，下载一个 2GB 文件的时候，因为每个 chunk 查询都要全表扫，一个简单下载任务把数据库 CPU 打到 100%，二次查询等待时间直接翻了几十倍。建了索引之后，整个下载过程几乎是无感的。这个教训我一直记着，任何 GridFS 上线前，索引检查必须做。

6.3 数据一致性：孤儿 chunk 与元数据不一致

GridFS 最常见的"脏数据"就是孤儿 chunk，也就是fs.chunks里有数据，但fs.files里找不到对应的元数据记录。产生原因通常是：上传过程中程序崩溃、网络中断，或者有人手动清理了 files 集合但没清理 chunks。

排查方法是用聚合管道找出孤儿块：

db.fs.chunks.aggregate([ { $lookup: { from: 'fs.files', localField: 'files_id', foreignField: '_id', as: 'file' } }, { $match: { file: { $size: 0 } } }, { $count: 'orphan_count' } ])

清理时我建议先做备份，或者将孤儿块的files_id集合导出后，分批删除：

// 找出所有孤儿块的 files_id var orphanIds = db.fs.chunks.aggregate([ { $lookup: { from: 'fs.files', localField: 'files_id', foreignField: '_id', as: 'file' } }, { $match: { file: { $size: 0 } } }, { $project: { files_id: 1 } } ]).map(function(doc) { return doc.files_id; }); // 按批删除，避免一次性锁表 orphanIds.forEach(function(fid) { db.fs.chunks.deleteMany({ files_id: fid }); });

这个清理脚本建议在业务低峰期执行，毕竟$lookup是重操作，数据量大时会产生较大的数据库压力。如果数据量特别大，最好拆成分页处理。

另外还有一个容易忽略的细节：fs.files里的md5字段是上传时 MongoDB 自动计算的。如果业务需要做文件完整性校验，下载后自行计算 MD5 与这个字段比对。但如果中途手动改过 chunks 数据，这个 md5 就失效了，需要特别注意。

7. 一些来自实战的体会

关于 GridFS 这个方案，我个人的总结是：它不是一个"万能存储"，而是一个"在已有 MongoDB 基础上，解决大文件存储问题的优雅补充"。和 FastDFS、MinIO 这类独立文件系统相比，它的优势在于运维成本极低、与业务系统共用现有 MongoDB 集群，不需要额外的服务部署和监控。对于中小型项目、内部工具、数据归档这类场景，GridFS 完全可以扛住。

如果真要挑毛病，我觉得最需要注意的是不要把它用在频繁周读的热数据场景，也不要把所有类型文件都一股脑丢进去。合理的架构应该是：小文件存普通 BSON 字段，大文件进 GridFS，文件访问入口统一走一个封装好的 Service 层，这样后续切换底层存储（比如换到对象存储）时成本也更低。

最后分享一个小技巧：GridFS 的元数据字段完全可以自定义，我在项目里习惯把metadata里塞进业务关联 ID、文件过期时间、上传来源。这样即使文件名不友好，也能靠业务 ID 回查文件，做定时清理和数据统计也方便。这算是我用下来性价比最高的一条实践经验了。