React Native 加密数据库实战：用 RxDB Encryption 插件保护移动端本地数据

React Native 加密数据库实战用 RxDB Encryption 插件保护移动端本地数据【免费下载链接】rxdbThe local-first database that runs on every JS runtime and replicates with your existing backend - no vendor, no lock-in - https://rxdb.info/项目地址: https://gitcode.com/gh_mirrors/rx/rxdb数据安全是移动应用绕不开的话题。在 React Native 应用中用户凭证、个人信息、财务数据等敏感内容如果以明文写入本地存储一旦设备丢失或被盗后果不堪设想。RxDB 提供了开箱即用的字段级加密能力只需在创建数据库时传入密码并在 Schema 中声明encrypted字段即可实现写入自动加密、读取自动解密且加密逻辑对上层业务代码完全透明。本文以 RxDB 的encryption-crypto-js插件为主线讲解在 React Native 中搭建加密数据库的完整步骤、底层加密原理、查询限制与安全最佳实践读完即可在真实项目中落地一套可靠的本地数据加密方案。为什么移动端本地数据必须加密加密的核心价值在于即使未授权方物理接触了你的设备或通过其他途径拿到了存储介质没有密钥也读不出数据内容。对凭证、个人信息、财务数据这类敏感字段加密是底线要求。增强安全性设备丢失或被盗时磁盘上只有密文没有正确密码无法还原原文访问控制服务端可以随时通过停止下发密码来撤销客户端对数据的访问能力防篡改与防窥探当密码仅保存在进程内存中时设备上的其他应用无法直接读出存储数据。同时规范的加密实践能降低数据泄露风险并帮助应用满足 GDPR 或 HIPAA 等合规要求外部法规链接仅供参考具体合规以专业法律意见为准。React Native 本地数据加密的三种路线方案适用场景说明加密数据库需要结构化、可查询的数据SQLite 加密层或直接使用 RxDB 的 encryption 插件在存储层透明加解密安全存储库Token、密钥等键值数据如react-native-keychain、react-native-encrypted-storage依托系统 Keychain/Keystore 保存小体积机密自定义加密需要细粒度控制用crypto-js或 Web Crypto API 在写入前手动加密数据再入库对于 React Native 应用最务实的组合通常是用系统安全存储Keychain/Keystore保管数据库密码用 RxDB 加密插件保护整库文档数据——两者职责互补下文会展开说明。在 RxDB 中启用加密安装与初始化RxDB 的加密插件本质上是对其他 RxStorage 的一层包装wrapper。你现有的存储——无论是内存存储、SQLite 还是 IndexedDB——被加密插件包裹后所有读写都会先经过加解密管线。RxDB 官方提供两种加密插件encryption-crypto-js免费基于 crypto-js 库的 AES 算法简单直接覆盖大多数基础场景encryption-web-cryptoPremium 插件基于浏览器原生 Web Crypto API性能与安全性更高文档插入速度约为 crypto-js 方案的 10 倍且构建体积更小不需要打包第三方 npm 模块。1. 安装依赖npm install rxdb npm install crypto-jscrypto-js是encryption-crypto-js插件的运行时依赖rxdb主包中已包含插件入口rxdb/plugins/encryption-crypto-js。2. 用加密包装创建数据库下面这段示例与本文档配套的官方写法一致测试场景使用 in-memory storage 便于快速验证生产环境应替换为持久化存储React Native 下推荐 SQLite-based storage详情见下文接入生产级持久化存储。import { createRxDatabase } from rxdb; import { wrappedKeyEncryptionCryptoJsStorage } from rxdb/plugins/encryption-crypto-js; /* * 测试时使用 RxDB 的内存存储。 * 生产环境请改用持久化的 SQLite 存储。 */ import { getRxStorageMemory } from rxdb/plugins/storage-memory; async function initEncryptedDatabase() { // 用加密插件包装普通存储 const encryptedMemoryStorage wrappedKeyEncryptionCryptoJsStorage({ storage: getRxStorageMemory() }); // 创建加密数据库 const db await createRxDatabase({ name: myEncryptedDatabase, storage: encryptedMemoryStorage, password: sudoLetMeIn // 生产环境切勿硬编码 }); // 定义 Schema 并创建集合 await db.addCollections({ secureData: { schema: { title: secure data schema, version: 0, type: object, primaryKey: id, properties: { id: { type: string, maxLength: 100 }, normalField: { type: string }, secretField: { type: string } }, required: [id, normalField, secretField] } } }); return db; }注意上例中的 Schema尚未声明encrypted数组因此所有字段都是明文存储。要真正加密某个字段需要在 Schema 中加入encrypted声明见下一节——这也正是许多初次使用者容易遗漏的关键一步。3. 在 Schema 中声明加密字段加密的粒度是字段级的把希望加密的字段路径加入 Schema 顶层的encrypted数组即可。const schema { version: 0, primaryKey: id, type: object, properties: { id: { type: string, maxLength: 100 }, secret: { type: string }, }, required: [id], encrypted: [secret] }; await db.addCollections({ myDocuments: { schema } });完整版官方加密指南可参考 encryption.md其中有对加密字段查询限制、密码管理、非对称加密、附件加密、Worker 场景等的系统说明。底层原理加密包装层如何工作从源码 src/plugins/encryption-crypto-js/index.ts 可以看到加密插件的完整实现逻辑wrappedKeyEncryptionCryptoJsStorage()通过Object.assign({}, args.storage, {...})复制原存储只覆盖createStorageInstance方法——这正是包装器架构的体现src/plugins/encryption-crypto-js/index.ts加密使用 crypto-js 的AES.encrypt/AES.decryptsrc/plugins/encryption-crypto-js/index.ts密码校验插件强制密码为字符串且长度不少于 8 位否则分别抛出EN1类型错误与EN2长度不足错误src/plugins/encryption-crypto-js/index.tsSchema 改写加密字段在落盘前会被改写为{type: string}并移除原字段的所有类型关键字properties、required、items、maxLength、enum等因为密文本质上就是一个字符串src/plugins/encryption-crypto-js/index.ts写入/读取管线modifyToStorage对加密字段执行JSON.stringify后 AES 加密写入modifyFromStorage解密后JSON.parse还原因此对象类型的字段也能整体加密src/plugins/encryption-crypto-js/index.ts是否加密由 Schema 决定hasEncryption()检查 Schema 中encrypted数组非空或attachments.encrypted为真若 Schema 未声明任何加密字段则原样透传、不产生加解密开销src/rx-storage-helper.ts。在 test/unit/encryption.test.ts 的测试中可以看到这些行为都被显式验证encryptString/decryptString的往返一致性含超长字符串与超长密码、空对象密码抛EN1、以及同一存储上用不同密码创建数据库会抛DB1错误等test/unit/encryption.test.ts。密码校验逻辑同样会在数据库创建时触发。写入、查询与更新加密数据数据库创建完成后加密字段的读写对业务代码完全透明——写入自动加密查询自动解密。(async () { const db await initEncryptedDatabase(); // 插入数据secretField 在落盘前会被自动加密 const doc await db.secureData.insert({ id: mySecretId, normalField: foobar, secretField: This is top secret data }); // 按主键或非加密字段查询 const fetchedDoc await db.secureData.findOne({ selector: { normalField: foobar } }).exec(true); console.log(fetchedDoc.secretField); // This is top secret data // 更新数据 await fetchedDoc.patch({ secretField: Updated secret data }); })();注意只能按主键或非加密字段进行查询。加密字段以密文形式存储在数据库中无法参与selector条件匹配。常见做法是保留一小部分需要查询的字段不加密敏感数据一律放进加密字段。加密字段查询限制的应对思路官方文档给出了几种绕过加密字段不可查询限制的可行方案查询字段与非加密字段分离查询走明文字段如用户 ID、业务状态敏感内容走加密字段——这是最常用的模式memory-mapped 存储使用 memory mapped RxStorage 把加密文档复制到非加密的内存存储中再查询适合对全量数据做内存级检索明文导出即敏感加密文档在读取时自动解密因此 JSON dump 等导出产物会包含明文必须当作敏感数据处理。接入生产级持久化存储SQLite 加密示例代码使用内存存储仅用于演示。在 React Native 生产环境中应改用 SQLite 存储——移动端系统iOS/Android本身内置 SQLite 引擎无需额外引入数据库服务。官方 SQLite RxStorage 文档 说明了其工作机制通过sqliteBasics适配层对接不同 SQLite 库将复杂 SQL 抽象为 RxDB 的 NoSQL JSON 文档 API。生产版 SQLite 存储位于 RxDB Premium 包中与加密插件组合使用的方式如下import { createRxDatabase } from rxdb; import { getRxStorageSQLite, getSQLiteBasicsQuickSQLite } from rxdb-premium/plugins/storage-sqlite; import { wrappedKeyEncryptionCryptoJsStorage } from rxdb/plugins/encryption-crypto-js; import { open } from react-native-quick-sqlite; const encryptedSQLiteStorage wrappedKeyEncryptionCryptoJsStorage({ storage: getRxStorageSQLite({ sqliteBasics: getSQLiteBasicsQuickSQLite(open) }) }); const db await createRxDatabase({ name: mydatabase, storage: encryptedSQLiteStorage, password: your-db-password, // 生产环境从安全存储获取 multiInstance: false, ignoreDuplicate: true });针对不同 React Native 环境react-native-database.md 给出了对应的 SQLite 适配推荐裸 React Native 项目使用react-native-quick-sqlite基于 JSI 直连 C绕过 React Native BridgeExpo 项目使用官方expo-sqlite模块getSQLiteBasicsExpoSQLiteAsync。加密包装与底层存储解耦因此无论切换哪种 SQLite 适配器加密配置都无需改动。密码管理安全存储与修改策略RxDB 不规定密码的存储与获取方式只要求创建数据库时提供密码这给了你充分的灵活性运行时获取应用启动时让用户输入密码或从后端按需下发不提供密码即等于撤销访问系统安全存储密码保存在 KeychainiOS/ KeystoreAndroid中通过react-native-keychain等库在运行时读取// 使用 react-native-keychain 安全地获取存储的密码 import * as Keychain from react-native-keychain; async function getDatabasePassword() { const credentials await Keychain.getGenericPassword(); if (credentials) { return credentials.password; } throw new Error(No password stored in Keychain); }密码不可修改密码是数据库级的打开已有数据库时传入不同密码会直接报错。若确需改密官方提供两条路径用 storage migration 插件 将数据迁移到新数据库或把随机生成的 meta-password 存为另一数据库的 local document用用户密码加密后启动时先解密再创建实际数据库对称加密的本质加密插件使用对称加密同一密码加解密以保证性能。若需要非对称加密公私钥官方建议用非对称密钥加密密码本身密文随数据存储启动时用私钥解密密码后再交给 RxDB 插件。附件加密与性能优化附件加密RxDB 支持附件图片、文本文件等自动加密。在 Schema 的attachments配置中设置encrypted: true附件数据在落盘时即用数据库密码加密读取时仅在显式获取附件时解密查询文档本身不会触发附件解密const mySchema { version: 0, type: object, properties: { /* ... */ }, attachments: { // 设为 true 后附件数据将用数据库密码加密 encrypted: true } };写入加密附件并读取的完整用法import { createBlob } from rxdb; const doc await db.secureData.findOne({ selector: { normalField: foobar } }).exec(true); const attachment await doc.putAttachment({ id: encryptedFile.txt, data: createBlob(Sensitive content, text/plain), type: text/plain, });从源码看附件加解密同样由加密包装层处理modifyToStorage把附件二进制转 Base64 后 AES 加密存入 BlobmodifyFromStorage解密 Base64 再还原为二进制 Blobsrc/plugins/encryption-crypto-js/index.ts 与 src/plugins/encryption-crypto-js/index.ts。性能优化建议加密是 CPU 密集型操作。若性能敏感优先使用 Premium 的 Web Crypto 插件原生 API插入速度约为 crypto-js 的 10 倍构建体积更小大块数据如文件内容应存为附件而非文档字段——附件只在显式获取时解密不会拖慢常规查询在 Worker/SharedWorker RxStorage 中使用加密时建议把加密放在 Worker 内执行避免占用主线程 CPU密码由主线程调用createRxDatabase时自动传入 Worker无需手动处理。若在 Worker 内用加密包装 OPFS 存储必须设置usesRxDatabaseInWorker: true否则 OPFS 返回的原始 JSON 字符串会导致加密层报错。Schema 加密配置的易错点加密字段不可嵌套于已加密父字段加密父字段时整个路径下的对象会被加密为一个字符串因此不能再把子路径也加入encrypted数组否则 dev-mode 下会报错// 不允许——nested.secret 是 nested 的子路径 const schema { encrypted: [nested, nested.secret] }; // 正确——只加密父字段 const schema { encrypted: [nested] };加密字段的 Schema 会被改写为字符串类型正因为底层把密文存成字符串加密字段的type、maxLength、enum等校验关键字对存储层不再生效——校验发生在加密前的业务写入端开发阶段用 DevMode 验证DevMode 插件 能在开发期校验 Schema 与加密配置的合法性生产环境应关闭以提升性能。React Native 加密最佳实践清单安全处理密码绝不硬编码密码或密钥用 React Native Keychain / react-native-encrypted-storage 在运行时安全获取数据库密码加密附件需要存储文件时通过 Schema 的attachments.encrypted: true让附件自动加密优化性能性能敏感场景优先 Premium Web Crypto 插件大块数据存附件而非文档字段开发期启用 DevMode用 DevMode 插件校验 Schema 与加密配置生产环境关闭安全通信与后端同步时使用 HTTPS 保证传输加密RxDB 的 replication 插件 可与安全端点配合保持数据一致SSL Pinning如需防御中间人攻击可启用 SSL Pinning让设备只信任固定证书防止攻击者替换证书。进一步学习从 RxDB Quickstart 开始完成引导式入门仓库自带完整的 React Native 示例包含initializeDb.js、storage.js等真实工程文件可作为实战教程直接对照学习深入阅读 RxDB 加密插件完整文档了解非对称加密、Worker 加密、改密策略等进阶主题。遵循上述实践并善用 RxDB 的加密插件你可以在 React Native 中构建安全、高性能且健壮的应用让用户数据从落盘那一刻起就处于保护之中。【免费下载链接】rxdbThe local-first database that runs on every JS runtime and replicates with your existing backend - no vendor, no lock-in - https://rxdb.info/项目地址: https://gitcode.com/gh_mirrors/rx/rxdb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考