- 当前位置：首页 >IT科技 >Node.js 结合 MongoDB 实现字段级自动加密
Node.js 结合 MongoDB 实现字段级自动加密
发布时间：2025-11-05 09:02:44 来源：技术快报 作者：数据库
某些场景下，结合加密对于数据隐私会有较高的现字要求，例如，段级用户系统的自动个人信息(身份证、手机号)、结合加密医患系统的现字患者信息等，怎么用技术手段安全的段级保护这些敏感数据是我们开发人员需要考虑的问题。
本篇文章，自动将介绍 MongoDB 的结合加密客户端字段级加密功能，英文全称为 Client-Side Field Level Encryption，现字在有些地方会看到简称为 CSFLE，段级代表的自动是一个意思，下文有些地方也会这样称呼。结合加密
该功能允许开发人员将数据保存到 MongoDB 服务器之前选择性的现字指定数据字段进行加密，这些加密/解密操作都是段级事先在客户端完成，与服务器通信时完全是加密的，最终只有配置了 CSFLE 客户端才能读取和写入敏感数据字段。
文末列举了几个使用中的常见错误原因，如有遇到类似错误可以做为参考。
环境要求
MongoDB Server 选择：MongoDB 客户端字段级加密分为自动加密、亿华云计算手动加密两种类型，自动加密社区版是不支持的，需要 MongoDB Server 4.2 企业版 或 MongoDB Atlas，学习使用推荐 MongoDB Atlas，它是在云服务器中托管的 MongoDB 服务器，不需要安装，且提供了免费的入门套餐是够我们学习使用了。
驱动兼容性：使用支持 CSFLE 功能的 Node.js MongoDB 驱动程序，3.4+ 以上版本是支持的，快速入门。
libmongocrypt：客户端字段级加密依赖 libmongocrypt，它是 MongoDB 驱动程序实现客户端加密/解密的核心组件，对应的 Node.js NPM 包为 mongodb-client-encryption，需要注意这个包依赖于 libbson 和 libmongocrypt C 库，需要 C++ 工具链，但是做为 Node.js Addons 插件，其已经利用 prebuild 在 CI 期间做了模块的预先编译，直接 npm i mongodb-client-encryption 安装即可，如果网络环境问题链接不上 github.com 可能就很麻烦了需要手动构建、WordPress模板编译，因为对模块的预先编译是放在 Github 上的。
mongocryptd：客户端加密必须要 mongocryptd 进程启动才能正常工作，刚开始一直遇到一个问题：MongoError: BSON field insert.jsonSchema is an unknown field. This command may be meant for a mongocryptd process. 貌似就是因为 mongocryptd 进程没有启动导致的。在 MongoDB Server 企业版中包含 mongocryptd 这个组件的，解决办法也很简单就是本机安装下企业版，尽管我们这里使用的是 MongoDB Atlas 也要安装的，安装方法参考 docs.mongodb.com/manual/tutorial/install-mongodb-enterprise-on-os-x。
项目准备
做一些初始化工作，安装依赖、配置文件、创建一个常规的 MongoDB client。
项目初始化 复制mkdir nodejs-mongodb-client-encryption
cd nodejs-mongodb-client-encryption
npm init
npm i mongodb mongodb-client-encryption -S1.2.3.4. 配置文件创建一个 index.js 文件，核心代码逻辑都在该文件编写，
复制// index.jsconst base64 = require(uuid-base64);const { MongoClient, Binary } = require(mongodb);const { ClientEncryption } = require(mongodb-client-encryption);const fs = require(fs);//配置
const config = { connectionString: ${替换为自己的 MongoDB 链接字符串}, keyVaultDb: encryption, //encryption 表示密钥保管数据库
keyVaultCollection: __keyVault, //__keyVault 表示集合
keyVaultNamespace: `encryption.__keyVault`, //密钥库命名空间
keyAltNames: test-data-key, masterKeyPath: master-key.txt}const LOCAL_MASTER_KEY = fs.readFileSync(config.masterKeyPath); //读取本地主密钥
const kmsProviders = { //指定 KMS 提供程序设置
local: { key: LOCAL_MASTER_KEY, },};1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21. 创建常规 复制/** * 获取常规 Mongo 客户端 * @param {String} connectionString * @returns */function getRegularClient(connectionString) { const client = new MongoClient(connectionString, { useNewUrlParser: true, useUnifiedTopology: true, }); return client.connect();}1.2.3.4.5.6.7.8.9.10.11.12.13.数据加密密钥
MongoDB 驱动程序自动加密/解密时需要访问事先创建的数据加密密钥，而这个密钥经过程序的处理会存储在密钥保管数据库的集合中，以下是创建一个数据加密密钥的云南idc服务商交互图。
创建 MongoDB 数据加密密钥还需要另外一个称为 “主密钥” 的密钥进行加密，下图展示了创建主密钥的流程：
主密钥的存储，生产环境 MongoDB 官方的推荐是使用密钥管理服务(KMS)：亚马逊网络服务 KMS、Azure 密钥保管库、谷歌云平台密钥管理，更多内容可阅读 客户端字段级加密：使用 KMS 存储主密钥。
学习为目的，简单方便些可使用本地密钥提供程序存储主密钥，这种方式不安全，不适合生产。
创建一个脚本文件 create-master-key.js，生成一个 96 字节的密钥文件，并写入到本地文件系统的 master-key.txt 文件中。
复制// create-master-key.jsconst fs = require(fs);const crypto = require(crypto);try { fs.writeFileSync(master-key.txt, crypto.randomBytes(96));} catch (err) { console.error(err);}1.2.3.4.5.6.7.8.9. 指定 KMS 程序配置客户端使用如下配置发现主密钥，local 表示的是使用本地主密钥。
复制const LOCAL_MASTER_KEY = fs.readFileSync(config.masterKeyPath); //读取本地主密钥
const kmsProviders = { //指定 KMS 提供程序设置
local: { key: LOCAL_MASTER_KEY, },};1.2.3.4.5.6.获取或创建数据加密密钥写一个函数 getOrCreateDataKey 分别传入创建的常规 client、上面指定的 KMS 程序配置，该方法目的是获取一个数据密钥，如果不存在则创建，实现为以下几个步骤：
在密钥保管库集合的 keyAltNames 字段上先设置唯一索引，这里创建的是一个部分索引，符合条件的才会创建。检查是否已创建数据加密密钥，若创建则立即返回。若未创建数据加密密钥，向指定的密钥保管库集合创建一条新的数据密钥。 复制/** * 获取或创建数据加密密钥 * 如果已存在 dataKey 则返回，否则创建一条 dataKey */async function getOrCreateDataKey(regularClient, kmsProviders) { //在密钥保管库集合的 keyAltNames 字段上先设置索引
await regularClient
.db(config.keyVaultDb) .collection(config.keyVaultCollection) .createIndex("keyAltNames", { unique: true, partialFilterExpression: { keyAltNames: { $exists: true } } }); //检查是否已创建数据加密密钥
const dataKeyInfo =await regularClient
.db(config.keyVaultDb) .collection(config.keyVaultCollection) .findOne({ keyAltNames: { $in: [config.keyAltNames] } }); if (dataKeyInfo) { //存在立即返回
return dataKeyInfo[_id].toString("base64"); } //创建一条新的数据密钥
const encryption = new ClientEncryption(regularClient, { keyVaultNamespace: config.keyVaultNamespace, kmsProviders, }); const dataKey = await encryption.createDataKey(local, { keyAltNames: [config.keyAltNames] }); return dataKey.toString(base64);}1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.24.25.26.27.28.29.30.31.32.33.34.35.36.37.38.39.40.41. 验证数据加密密钥是否成功创建调用编写好的方法，验证下数据加密密钥是否创建成功。
复制(async () => { let regularClient; try { //创建常规 MongoDB 客户端
regularClient = await getRegularClient(config.connectionString); //获取数据加密密钥
const base64DataKeyId = await getOrCreateDataKey(regularClient, kmsProviders); } catch (err) { console.error(err); regularClient.close(); }})();1.2.3.4.5.6.7.8.9.10.11.12.我使用 Robo 3T 链接的 Atlas 集群，如果一切正常，你会看到在 encryption.__keyVault 集合中有如下一条密钥记录，_id 字段就是为我们需要的数据加密密钥，使用 Base64 格式编码。
JSON Schema 定义
Node.js 驱动程序使用 JSON Schema 定义集合需要加密的字段，文档类型定义使用 BSON 类型。
encryptMetadata.keyId：在根级别配置数据加密密钥，properties 中的每个字段默认都继承该密钥，除非特别指定，参考 docs.mongodb.com/manual/reference/security-client-side-automatic-json-schema/#encryptmetadata-schema-keyword。algorithm：指定加密算法，AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic 为确定性加密算法，对读取操作提供了更好的支持，安全系数相对没有**随机加密 **AEAD_AES_256_CBC_HMAC_SHA_512-Random 高，随机加密算法每次执行加密都会输出不同的值。 复制/** * 使用 JSON Schema 定义集合需要加密的字段 * @param {String} base64DataKeyId * @returns */function getSchemaMap(base64DataKeyId) { //使用 JSON Schema 指定加密字段
const userJsonSchema = { bsonType: object, encryptMetadata: { keyId: [new Binary(Buffer.from(base64DataKeyId, base64), 4)] }, properties: { phone: { encrypt: { bsonType: string, algorithm: AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic } }, password: { encrypt: { bsonType: string, algorithm: AEAD_AES_256_CBC_HMAC_SHA_512-Random } }, emergencyContact: { bsonType: object, properties: { phone: { encrypt: { bsonType: string, algorithm: AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic } }, } } } } //将 JSON 模式映射到集合上
const schemaMap = { test.users:userJsonSchema
}; return schemaMap;}1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.24.25.26.27.28.29.30.31.32.33.34.35.36.37.38.39.40.41.42.43.44.45.46.CSFLE 客户端验证读写操作
在有了数据加密密钥、JSON Schema 之后可以创建一个支持 CSFLE 的 Mongo client，该客户端和 MongDB 服务器交互，读取/写入带有加密字段的数据。
读写操作流程图下图展示了客户端应用程序和驱动程序为写入字段级加密数据的一个步骤：
下图展示了客户端应用程序和驱动程序为读取加密后字段进行解密操作的一个过程：
创建 CSFLE 的 mongo client 与常规 mongo client 相比较，需要多传入 autoEncryption 对象，以下参数含义分别为：
keyVaultNamespace：存放数据加密密钥的密钥保管库集合名称。kmsProviders：指定本地主密钥。schemaMap：需要加密字段的一些定义。 复制function getCSFLEClient(schemaMap, kmsProviders) { const secureClient = new MongoClient(config.connectionString, { useNewUrlParser: true, useUnifiedTopology: true, monitorCommands: true, autoEncryption: { bypassAutoEncryption: true, keyVaultNamespace: config.keyVaultNamespace, kmsProviders,schemaMap
} }); return secureClient.connect();}(async () => { try { const regularClient = await getRegularClient(config.connectionString); const base64DataKeyId = await getOrCreateDataKey(regularClient, kmsProviders); const schemaMap = getSchemaMap(base64DataKeyId); const csfleClient = await getCSFLEClient(schemaMap, kmsProviders); //执行读写操作
} catch (err) { console.error(err); }})();1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.23.24.25.26.27.28. 执行读写操作验证在拥有 CSFLE 客户端后，执行一些读写操作，创建一条用户记录，下面的代码和我们常规的读写操作没什么区别，并且 phone 这个字段虽然是经过加密的，我们仍可使用该字段做为索引，更新/查找数据。
复制(async () => { try { //...
const db = csfleClient.db(test); const userColl = db.collection(users); const doc = { name: 小张, phone: 18800030009, password: 123456, emergencyContact: { name: 小李, phone: 16600260023 } }; const query = { phone: doc.phone }; await userColl.updateOne(query, { $set: doc }, { upsert: true }); const result = await userColl.findOne(query); console.log(result); } catch (err) { console.error(err); }})();1.2.3.4.5.6.7.8.9.10.11.12.13.14.15.16.17.18.19.20.21.22.当成功插入一条记录之后，在 Robo 3T 工具查询该集合，可以看到需要的字段都已经做了加密，尽管我是一个管理员能够查看数据，也无法查看这些隐私数据。
只能通过程序正确的创建了 CSFLE 的客户端才能读取出解密后的数据。
几个常见错误
文中示例测试时常见的几个错误，可以做为参考。
认证失败遇到 Authentication failed 错误，基本上都是连接字符串的账号密码或权限错误，使用 MongoDB Atlas 的需要检查下数据库的访问权限配置
Authentication failed.
...
ok: 0, code: 8000, codeName: AtlasError, [Symbol(errorLabels)]: Set(0) {}}1.2.3.4.5.6.7. 创建加密客户端链接失败下面的报错很简单就是服务器链接不上。需要注意的是文中创建加密客户端还会去链接本地安装的 MongoDB 企业版 Server，在本地启动 MongoDB 企业版 Server 时需要指定下端口 bin/mongod --dbpath data --logpath logs/mongo.log --port 27020。
复制MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27020 at Timeout._onTimeout (/Users/- 探索绝地求生电脑显示错误代码的解决方案（从错误代码解读到问题解决，让你畅享绝地求生游戏）
- 罗技G300（体验游戏新境界的利器）
- 神舟战神Z7装系统教程（适用于神舟战神Z7的系统安装教程，详细步骤及注意事项）
- 一步步教你使用U盘安装W10系统（简单易懂的W10系统安装教程，带你迈入新系统时代）
- 电脑挂防封条教程（轻松保护电脑安全的关键技巧）
- 深入了解throttle技术（如何通过throttle技术提升应用程序的效率）
- 探索索尼Assist（发现索尼Assist的功能和优势）
- 《TrustGo杀毒软件的功能与性能评估》（一款可信赖的移动设备安全保护工具）
- 手机插U盘使用教程（快速实现手机和U盘的数据传输，让移动存储更便捷）
- 荣耀战场代练攻略（王者之路，代练先锋）
- 电脑连接翼讯后发生错误的解决方法（翼讯连接错误、网络问题、解决方案）
- XP下安装Win10双系统教程（详细步骤让您轻松实现XP与Win10双系统共存）
- 多玩连点器教程（使用多玩连点器提升游戏效率，轻松战胜对手）
- 探索索尼Assist（发现索尼Assist的功能和优势）
- 如何使用苹果设备分享WiFi密码给其他手机（简单实用的方法和步骤，让你轻松共享网络连接）
- 如何添加无线网络连接（无线网络连接教程及常见问题解答）
- 联想笔记本使用教程（了解联想笔记本的基本操作和功能，轻松上手使用）
- 联想XPU盘系统重装Win7系统教程（简单易懂的步骤让您轻松重装Win7系统）
- 飞利浦SHB6250音质的真实评价（揭秘SHB6250的音质表现，解锁你的音乐世界）
- 乘客取消订单的影响及处理方式（了解取消订单对乘客、司机和平台的影响，探索有效处理方式）
随便看看
- Copyright © 2025 Powered by Node.js 结合 MongoDB 实现字段级自动加密,技术快报 滇ICP备2023006006号-46sitemap