必须升级至mongodb 7.0+服务端及兼容驱动（如node.js v6.0+、pymongo 4.7+），6.0预览版加密数据与7.0完全不兼容；需验证驱动与客户端加密库版本严格匹配、启用encryption、使用专用集群、提前创建带唯一索引的keyvault、正确配置encryptionschema中queries字段、加载libmongocrypt共享库，且无法对已有集合启用queryable encryption。
必须升级到 MongoDB 7.0+ 服务端 + 兼容驱动（如 Node.js v6.0+、Python PyMongo 4.7+），且不能复用 6.0 预览版加密的数据 —— 否则连接失败或查询返回空结果。
确认服务端和驱动版本是否真正兼容
Queryable Encryption 在 7.0 才正式 GA，6.0 的预览版数据与 7.0 完全不兼容。即使 mongod 进程显示 version: "7.0.x"，也要验证两点：
- 驱动程序版本号主次版本需严格匹配：例如
PyMongo==4.7.2对应mongodb-client-encryption==4.7.2，错一个 patch 版都可能触发InvalidArgumentError: Unsupported encryption version - 运行
mongosh连接后执行db.runCommand({getCmdLineOpts: 1})，确认输出中包含"enableEncryption": true（仅企业版默认启用；社区版需手动编译或换用 Atlas） - 若用 Atlas，必须选「7.0+ 专用集群」，共享集群（M0/M2/M5）不支持 Queryable Encryption
创建加密集合前必须建好 keyVault 和索引
不是“先建集合再配密钥”，而是密钥保管库必须提前就位，否则 createEncryptedCollection() 会静默失败或报 KeyNotFound。
- 确保密钥保管库集合存在：
encryption.__keyVault（路径固定，不可改） - 在
keyAltNames字段上建唯一索引：db.getSiblingDB("encryption").__keyVault.createIndex({keyAltNames: 1}, {unique: true}) - 如果跳过这步，后续插入文档时不会报错，但所有加密字段写入的是明文（
encryptedField看起来像乱码，实为未加密的 BSON binary）
加密模式（encryptionSchema）里 queries 字段决定能否查
只写 path 和 bsonType 不够 —— 字段默认不可查询。要支持 .find({ssn: "123-45-6789"}) 这类操作，queries 必须显式声明：
{
"ssn": {
"path": "ssn",
"bsonType": "string",
"keyId": UUID("..."),
"queries": { "queryType": "equality" }
}
}
-
"queries"是对象，不是布尔值；写成"queries": true会被忽略，字段仍不可查 - 目前仅支持
"equality"和"range"；"prefix"等类型在 7.0 中尚未开放 - 启用
queries后，每个加密字段会额外生成一个索引，写入延迟上升约 15–25%，务必在压测中验证
客户端必须加载自动加密共享库（libmongocrypt）
Node.js 或 Python 应用启动时若没正确加载 libmongocrypt，会出现 AutoEncryptionProviderError: unable to load libmongocrypt 或静默降级为普通写入。
- Node.js：安装
mongodb-client-encryption后，需在连接选项中显式传入autoEncryption: { keyVaultNamespace: "encryption.__keyVault", kmsProviders: {...} } - Python：PyMongo 4.7+ 默认启用，但必须确保系统能 resolve 到
libmongocrypt.so/.dylib/.dll；用pip install pymongo[cse]可自动带二进制依赖 - 切勿依赖
mongocryptd：该进程在 7.0+ 已废弃，启用后反而阻塞加密流程
最容易被忽略的是：加密集合只能新建，无法对已有集合开启 Queryable Encryption —— 即使集合为空也不行。迁移旧数据必须走导出→解密→重加密→导入流程，中间任何环节密钥丢失都会导致数据永久不可读。
