MongoDB 7.0中实施CSFLE必须使用Enterprise或Atlas，Community版仅支持显式加密；需配对兼容驱动、crypt_shared库（或mongocryptd），且keyVault索引与DEK创建顺序不可颠倒。
直接上结论：MongoDB 7.0 中实施客户端字段级加密（CSFLE）必须用 Enterprise 或 Atlas，Community Edition 不支持自动加密，仅支持显式加密；且必须配对使用兼容驱动 + crypt_shared 共享库（或 mongocryptd），缺一不可。
确认你的 MongoDB Server 和部署类型是否支持自动加密
CSFLE 的自动加密功能不是“装了驱动就能用”的通用能力。它依赖服务端的密钥管理协议支持：
- MongoDB Atlas：完全支持自动加密和显式加密
- MongoDB Enterprise Advanced：完全支持
- MongoDB Community Edition：不支持自动加密，仅能通过驱动调用
encrypt()/decrypt()手动加解密字段（即显式加密）
如果你在本地跑的是 Community 版 mongod，却按 Atlas/Enterprise 文档配置了 autoEncryption，启动时会静默失败或报错 Auto encryption requires a supported server version —— 这不是驱动问题，是服务端直接拒绝协商。
必须安装 crypt_shared 并正确传入路径
从 MongoDB 6.0 起，mongocryptd 已被标记为 legacy，crypt_shared 是默认且推荐的自动加密共享库。但它的加载不是自动的：
- Node.js 驱动 v6+ 必须显式传入
cryptSharedLibPath选项，例如：cryptSharedLibPath: "/usr/lib/libmongocrypt-shared.so" - 路径必须指向真实存在的、与驱动主版本号匹配的
.so（Linux）/.dylib（macOS）/.dll（Windows）文件 - 如果路径错误、权限不足、或 ABI 不兼容（比如用 v7 驱动配 v6 的
crypt_shared），连接会卡在初始化阶段，日志里可能只显示Failed to load auto encryption shared library - 下载地址在 MongoDB Download Center → “MongoDB Enterprise Server” → 选平台 → Package 选
crypt_shared，不是在 driver 包里自带的
keyVault 集合索引和 DEK 创建顺序不能颠倒
哪怕你跳过了 KMIP/Azure 等 KMS，用本地 master-key.txt 测试，也必须严格按顺序操作，否则 createDataKey() 会失败：
- 先确保
encryption.__keyVault集合存在（不存在会自动创建） - 必须在
keyAltNames字段上建唯一索引，且带partialFilterExpression: { keyAltNames: { $exists: true } }—— 缺少这个 filter，插入重复别名时不会报错，但后续查询密钥会漏匹配 -
createDataKey("local", { keyAltNames: ["myAppKey"] })必须在索引建好后调用；如果先调用再建索引，DEK 文档写进去了但没索引，之后所有基于keyAltNames的查找（包括自动加密流程里的密钥发现）都会失败 - 注意：
keyAltNames是数组，不是字符串；写成keyAltNames: "myAppKey"会导致密钥无法被定位
kmsProviders 配置中 kmip.useLegacyProtocol 容易被忽略
如果你对接的是老版本 KMIP 服务器（比如某些硬件 HSM 只支持 1.0/1.1），默认的 KMIP 1.2 协议会握手失败，错误表现为连接超时或 TLS alert 10，而不是明确的协议版本错误：
- 必须显式启用
useLegacyProtocol: true，例如：kmsProviders: { kmip: { endpoint: "kmip.example.com:5696", useLegacyProtocol: true } } - 该字段只对
kmip有效，azure、gcp等 provider 不识别它 - 即使你用了最新版
crypt_shared，KMIP 协议降级仍由驱动层控制，不取决于共享库版本
最常被绕过的点是：以为只要证书和 endpoint 对了就能通，结果卡在 TLS 握手后的协议协商环节，日志里没有任何 KMIP 相关关键词，排查方向容易跑偏。
