直接向 fs.files 插入文档会失败，因为 MongoDB 7.0 GridFS 驱动禁止手动写入该集合，必须通过 uploadFromStream() 等 API 写入以确保元数据完整性与协议兼容。
为什么直接往 fs.files 插入文档会失败
MongoDB 7.0 的 GridFS 驱动（如官方 Node.js 驱动）默认禁止手动向 fs.files 写入文档，因为 fs.files 是 GridFS 协议强约束的元数据集合，字段结构、索引和校验逻辑由驱动控制。直接 insertOne 会触发写入拦截或导致后续 find / delete 行为异常（例如文件无法被 GridFSBucket.find() 正确识别）。
常见错误现象：WriteError: Document failed validation（启用了 schema validation 时），或插入成功但 GridFSBucket.openDownloadStream() 找不到该文件。
- 必须通过
GridFSBucket.uploadFromStream()或uploadFromStreamWithId()写入，驱动才会自动填充必需字段（_id,length,chunkSize,uploadDate,md5）并确保索引兼容 - 自定义字段只能作为
metadata对象的一部分传入，不能平铺到根层级 - 若已启用
jsonSchema验证，需提前在fs.files集合上扩展 schema，允许metadata中的新字段
metadata 是唯一安全的自定义入口
GridFS 规范把用户扩展字段统一收口到 metadata 字段（类型为 object），这是驱动明确支持且不破坏协议的位置。所有主流驱动（Node.js、Python PyMongo、Java）都接受该参数，并原样存入 fs.files.metadata。
示例（Node.js）：
const bucket = new GridFSBucket(db, { bucketName: 'myfiles' });
const uploadStream = bucket.openUploadStream('report.pdf', {
metadata: {
author: 'alice',
version: 2,
tags: ['finance', 'q3'],
reviewedAt: new Date('2024-09-15')
}
});
await stream.pipe(uploadStream);
-
metadata值可以是任意嵌套对象，但避免使用Date、ObjectId等非 JSON 可序列化类型（PyMongo 会自动转换；Node.js 驱动要求传Date实例，它会转为 ISO 字符串） - 字段名不建议用下划线开头（如
_private），某些旧版驱动或工具可能忽略或过滤 - 如果需要高频查询某个自定义字段（如
author），记得在fs.files上单独建索引：db.fs.files.createIndex({ "metadata.author": 1 })
如何安全地更新已有文件的元数据
GridFS 没有原子化的“更新元数据”操作。想改 metadata，本质是修改 fs.files 文档，但必须绕过驱动限制，且不能影响关联的 fs.chunks 数据完整性。
- 先用
bucket.find({ filename: 'xxx' })定位目标文件，拿到_id - 再直接对
fs.files集合执行updateOne，只更新metadata字段：db.fs.files.updateOne({ _id: fileId }, { $set: { "metadata.status": "archived" } }) - 严禁更新
length、chunkSize、uploadDate等核心字段，否则会导致读取错乱或校验失败 - 更新后，用
bucket.find()验证是否生效——注意：部分驱动缓存元数据，可能需重启连接或清空本地缓存
7.0 特别注意：schema validation 和通配符索引
MongoDB 7.0 默认启用更严格的集合级验证策略。如果你在 fs.files 上配置了 jsonSchema（比如为了强制 metadata.projectId 存在），必须显式允许 metadata 下的动态字段：
{
"bsonType": "object",
"required": ["filename", "length", "chunkSize", "uploadDate"],
"properties": {
"metadata": {
"bsonType": "object",
"additionalProperties": true // 关键：允许任意子字段
}
}
}
另外，7.0 支持通配符索引，若需按多级嵌套的自定义字段查询（如 metadata.audit.by），可建：db.fs.files.createIndex({ "metadata.audit.$**": 1 })。但要注意通配符索引不支持排序，且会增加写入开销。
真正容易被忽略的是：一旦开启 schema validation，所有 GridFS 写入（包括驱动自动写入）都会校验。漏掉 additionalProperties: true 就会导致上传直接失败，错误信息里不会明说，只报 Document failed validation。
