RxDB 在 Ionic 中的本地存储方案：加密、压缩与实时同步实战指南

RxDB 在 Ionic 中的本地存储方案：加密、压缩与实时同步实战指南

【免费下载链接】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

在 Ionic 混合应用中，选择一套可靠的本地存储方案通常需要同时满足四个诉求：离线优先（Offline-First）、敏感数据加密、存储占用压缩，以及与任意后端实时同步。RxDB（Reactive Database）正是围绕这四个能力设计的 local-first 数据库，本文以 ionic-storage.md 为主线，结合仓库源码逐层讲解如何在 Ionic 项目中落地 RxDB：从 LocalStorage 起步搭建数据库，到用 crypto-js 插件开启字段级加密、用 key-compression 插件压缩存储体积，再到无缝切换到 SQLite 原生存储并接入各类后端复制协议。读完本文，你将掌握一套从原型验证到生产发布的完整 Ionic 本地存储技术栈。

为什么在 Ionic 中选择 RxDB

Ionic 应用本质上是跑在 WebView 中的混合应用，其数据层既要面对浏览器存储的种种限制（容量、同步阻塞），又要承担原生应用常见的弱网与多端同步场景。RxDB 之所以适合作为 Ionic 的存储底座，主要基于以下几点：

1. 离线可用的 NoSQL 存储

offline-first.md 中明确指出：Local-First 是一种"软件在客户端设备上本地存储数据，离线时与在线时一样可用"的范式。RxDB 将全部数据存储在设备本地，Ionic 应用因此在网络不可靠或缓慢时仍能完整运行；一旦网络恢复，RxDB 会在后台自动把变更同步到后端，无需额外编写同步代码。

从架构上看，这种模式把本地数据库而非服务器作为应用状态持久化变更的入口（gateway），在 DDIL（连接被拒绝、中断、间歇、受限）环境中，这不是优化选项而是唯一可行的架构。

2. 强大的加密能力

处理敏感信息时，设备端数据的静态安全至关重要。RxDB 的加密插件让你可以：

• 使用 AES 对字段在静态存储时加密；
• 只需扣住密码即可随时撤销数据访问权；
• 即使设备被盗，用户数据仍然保密。

这使 RxDB 区别于许多缺乏内置安全机制的 Ionic 存储方案。

3. 内置数据压缩

大体积或高重复度的数据会拖慢内存有限的设备。RxDB 的 key-compression 特性通过缩短字段名来减小设备上存储的文档体积，从而：

• 降低磁盘占用；
• 加速查询；
• 减少同步时的网络开销。

4. 实时同步与冲突处理

除完全离线运行外，RxDB 还支持多种高级复制（Replication）协议，Ionic 应用可以与任意后端（CouchDB、Firestore、GraphQL、自定义 REST 等）实时同步，保持实时用户体验，并优雅地处理多端编辑冲突。

5. 易于采纳和扩展

RxDB 采用 NoSQL 模型，与 Ionic Angular 或其他与 Ionic 搭配使用的框架天然契合。你可以扩展或替换存储后端、添加加密、构建高级离线优先功能，而无需引入大量额外工程。

快速开始：在 Ionic 中使用 LocalStorage 存储

对于概念验证或测试环境，最简单的方式是用 LocalStorage 作为底层存储（rx-storage-localstorage.md 甚至将其列为浏览器环境的推荐默认项）。后续如需更好的原生性能，可以切换为 RxDB Premium 的 SQLite 存储。

1. 安装 RxDB

npm install rxdb rxjs

2. 初始化数据库

import { createRxDatabase } from 'rxdb/plugins/core'; import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage'; async function initDB() { const db = await createRxDatabase({ name: 'myionicdb', storage: getRxStorageLocalstorage(), multiInstance: false // or true if you plan multi-tab usage // Note: If you need encryption, set `password` here }); await db.addCollections({ notes: { schema: { title: 'notes schema', version: 0, type: 'object', primaryKey: 'id', properties: { id: { type: 'string', maxLength: 100 }, content: { type: 'string' }, timestamp: { type: 'number' } }, required: ['id'] } } }); return db; }

3. 随时准备升级

当需要在移动设备上获得最佳性能时，购买 RxDB Premium 的 SQLite 存储，将getRxStorageLocalstorage()替换为getRxStorageSQLite()即可——应用逻辑几乎保持不变，你只需要修改配置。

认识 LocalStorage 存储引擎的边界

从 src/plugins/storage-localstorage/index.ts 的源码可以看到，getRxStorageLocalstorage()是一个工厂函数，返回RxStorageLocalstorage实例，其createStorageInstance会把调用方传入的options与构造时的settings合并后创建存储实例。这说明 LocalStorage 存储是完全即插即用的插件化设计，这也解释了为什么它可以被加密包装器、压缩包装器层层包裹。

同时 rx-storage-localstorage.md 明确列出了它的两个主要限制，在 Ionic 项目中需要提前知晓：

1. 存储容量有限：浏览器通常将 LocalStorage 限制在每域名约 5 MB 左右（具体上限因浏览器而异）；
2. 同步访问：LocalStorage 操作会阻塞主线程，数据量小时通常无碍，但重度使用可能成为性能瓶颈。

此外，LocalStorage API 只在浏览器中存在；如果你需要在 Node.js 环境（如单元测试）中使用该存储，可以用 RxDB 自带的 mock——getRxStorageLocalstorage({ localStorage: getLocalStorageMock() })（见 rx-storage-localstorage.md 的 "Mocking" 一节）。

加密示例：保护设备端敏感数据

要保护本地数据，可以添加免费版的 crypto-js 加密插件，或使用 Premium 的 web-crypto 插件。下面以免费版 crypto-js 为例：

import { wrappedKeyEncryptionCryptoJsStorage } from 'rxdb/plugins/encryption-crypto-js'; import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage'; import { createRxDatabase } from 'rxdb/plugins/core'; async function initEncryptedDB() { const encryptedStorage = wrappedKeyEncryptionCryptoJsStorage({ storage: getRxStorageLocalstorage() }); const db = await createRxDatabase({ name: 'secureIonicDB', storage: encryptedStorage, password: 'myS3cretP4ssw0rd' }); await db.addCollections({ secrets: { schema: { title: 'secret schema', version: 0, type: 'object', primaryKey: 'id', properties: { id: { type: 'string', maxLength: 100 }, text: { type: 'string' } }, required: ['id'], // all fields in this array will be stored encrypted: encrypted: ['text'] } } }); return db; }

启用加密后：

• text字段在静态存储时被自动加密；
• 查询无法直接作用于加密字段（因为数据已加密），但一旦文档被加载，RxDB 会自动解密供正常使用。

加密插件的底层机制

从 src/plugins/encryption-crypto-js/index.ts 源码可以看到加密插件的完整工作方式：

• 插件是存储的包装器：wrappedKeyEncryptionCryptoJsStorage({ storage })返回一个与原存储同接口的对象，并覆写createStorageInstance（L62-L66）。因此它可以包裹 LocalStorage、IndexedDB、SQLite 等任意 RxStorage。
• 密码校验：创建存储实例时若传入了password，会调用validatePassword（L74-L76），要求密码必须是字符串且长度不小于 8（MINIMUM_PASSWORD_LENGTH = 8，见 L31）。
• 加密/解密钩子：通过modifyToStorage在写入前用AES.encrypt加密指定字段，通过modifyFromStorage在读取后用AES.decrypt解密（L131-L180）。加密后的密文一律以字符串形式存储，因此源码会临时把加密字段的 schema 替换为{ type: 'string' }（L98-L119）。
• 附件加密：如果 schema 的attachments.encrypted为 true，附件数据同样会被 base64 编码后加密存储（L145-L164）。
• 密码即访问控制：在 encryption.md 的 "Password handling" 一节中明确，RxDB 不规定密码的存取方式——你可以在应用启动时让用户输入密码，也可以从后端拉取密码（不提供密码即撤销访问权）。

加密相关注意事项

• 加密字段不能作为查询操作符使用；如需基于加密内容过滤，可借助 memory-mapped 存储把加密文档复制到内存中的非加密存储再查询。
• JSON 导出（dump）会包含解密后的明文，需按敏感数据处理。
• 数据库密码无法修改：以不同密码打开现有数据库会直接报错。如需换密码，可用 storage migration 插件 迁移到新库，或采用"meta-password + 用户密码加密"的方案。
• 若在 Worker 中使用加密，建议在 Worker 内部执行加密（加密是 CPU 密集操作），密码会自动从主线程传递到 Worker。

压缩示例：减小存储足迹

为了最小化存储占用，RxDB 提供了 key-compression 特性。你可以在 schema 中启用它：

await db.addCollections({ logs: { schema: { title: 'logs schema', version: 0, keyCompression: true, // enable compression type: 'object', primaryKey: 'id', properties: { id: { type: 'string', maxLength: 100 }, message: { type: 'string' }, createdAt: { type: 'string', format: 'date-time' } } } } });

设置keyCompression: true后，RxDB 会在内部缩短字段名，显著减小文档体积。这既有利于本地存储，也能降低复制（replication）过程中的网络传输量。根据 key-compression.md 的说明，压缩基于 JSON Schema 进行，可将长属性名压缩为更短的名称（并支持反向解压），最多可节省约 40% 的磁盘空间；压缩与解压均在内部完成，因此你操作 RxDocument 时仍可像访问普通属性一样读取任意字段。

与加密插件类似，key-compression 也是围绕任意 RxStorage 的包装器（wrappedKeyCompressionStorage），因此它可以与 LocalStorage、SQLite 等组合使用。

RxDB 与其他 Ionic 存储方案的对比

Ionic Native Storage或基于Capacitor的 key-value 存储可以处理少量数据，但缺乏高级能力，例如：

• 复杂查询；
• 完整的 NoSQL 文档模型；
• 离线优先的同步；
• 开箱即用的加密与键压缩。

RxDB 的优势在于把所有这些能力统一进一个库中：加密与压缩包装器可以叠加在同一个底层存储之上（源码中两者都基于wrapRxStorageInstance机制实现），这意味着"加密 + 压缩 + 复制"可以同时启用而互不冲突。

进阶：同步、迁移与运行环境

• 实时同步：RxDB 的复制协议支持 CouchDB、Firestore、GraphQL、HTTP 等后端，配合 transactions-conflicts-revisions 中的冲突处理机制，多设备编辑冲突可被自动合并或按策略解决。
• Schema 迁移：Ionic 应用发布后 schema 必然演进，可参考 contenteditable="false">【免费下载链接】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