GridFS 不支持客户端字段级加密（CSFLE），因其文件内容以二进制块存于 fs.chunks.data，而 CSFLE 仅作用于 BSON 文档字段，无法触达该字段；元数据可加密，但文件本体需依赖传输层（TLS）、存储引擎加密及访问控制保障安全。
GridFS 本身不支持客户端字段级加密（CSFLE），你不能直接对 GridFS 文件内容启用自动或手动字段级加密——因为 CSFLE 只作用于 BSON 文档字段，而 GridFS 存储的是二进制分块（fs.chunks）和元数据（fs.files），驱动层不会对 fs.chunks.data 字段应用加密规则。
为什么 GridFS + CSFLE 会静默失效
CSFLE 的加密逻辑只在 insertOne、updateOne 等文档级操作时触发，且仅检查你传入的顶层 BSON 对象结构。GridFS 的写入流程是：GridFSBucket.openUploadStream() → 自动拆分成 fs.files（元数据文档）和多个 fs.chunks（二进制块文档）。这些块文档的 data 字段是 BinData(0, ...)，不是你控制的业务字段，CSFLE schemaMap 或 encrypt() 调用根本触达不到它。
- 即使你在
options.metadata里塞了ssn: "123-45-6789"这类敏感字段，CSFLE 也只能加密那个 metadata 对象里的字段，不影响实际文件内容 - 如果你试图对整个文件 buffer 手动调用
ClientEncryption.encrypt()再喂给openUploadStream()，那解密责任完全落在应用层——GridFS 不知道这是密文，读出来仍是乱码，且无法利用数据库查询能力 - mongocryptd 或 crypt_shared 不解析
fs.chunks集合，日志里也不会报错，只会“安静地跳过”
合规文件该怎么做：绕过 GridFS，改用普通集合 + 显式加密
当文件内容本身属于 GDPR/ HIPAA 级别的敏感数据（如扫描的身份证图片、病历 PDF），又必须由 MongoDB 托管时，放弃 GridFS，改用 base64 编码后存入普通集合的 content 字段，并手动加解密：
- 上传前：
const encrypted = await clientEnc.encrypt(dekId, Buffer.from(fileBuffer), { algorithm: "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" }) - 存入普通集合：
db.collection.insertOne({ filename: "id_card.pdf", content: encrypted, uploadedAt: new Date() }) - 下载时：
const doc = await db.collection.findOne({ filename: "id_card.pdf" }); const decrypted = await clientEnc.decrypt(doc.content) - 注意：
content字段值是BinData(6, ...)，不是原始 buffer；MongoDB 有 16MB 文档上限，单文件别超这个量
如果非用 GridFS 不可：只能加密元数据，内容靠传输与存储层防护
这是折中方案，适用于文件内容无需“字段级”隔离，但元数据（如患者 ID、就诊科室）必须脱敏的场景：
- 启用 CSFLE 的
schemaMap，把fs.files集合纳入自动加密范围：{"database.fs.files": {"properties": {"metadata.patientId": {"encrypt": {"keyId": [...], "algorithm": "Deterministic"}}}}} - 确保
openUploadStream()的options.metadata是 plain object，不要嵌套过深，否则 schema 匹配失败 - 文件本体仍明文存于
fs.chunks.data，所以必须叠加 TLS（tls=True）+ 磁盘加密（WiredTiger 加密存储引擎）+ 严格访问控制（RBAC 角色最小权限） - 禁止对
fs.chunks集合做任何直连查询或聚合，所有访问必须经封装过的服务接口，接口层做审计日志
容易被忽略的密钥生命周期陷阱
显式加密模式下，ClientEncryption 实例绑定的是初始化时加载的 KMS 配置，一旦进程启动，kmsProviders.local.key 就固定了。这意味着：
- 你不能在运行时热切换密钥文件路径——改了配置得重启服务
- DEK（数据加密密钥）存在
__keyVault里，但它的keyMaterial是用 KMS 密钥加密过的；如果本地 KMS 文件损坏或权限变更，所有已加密文件内容永久不可恢复 - 备份
__keyVault集合不等于备份密钥——你还得单独备份 KMS 文件（如 AWS KMS 的 CMK ARN 或本地masterkey.txt） - 测试环境用本地 KMS，生产切云 KMS 时，必须重新生成全部 DEK 并重加密历史文件，没有在线迁移工具
