OpenBrowserClaw存储体系全解:IndexedDB + OPFS如何重塑浏览器数据持久化
OpenBrowserClaw存储体系全解:IndexedDB + OPFS如何重塑浏览器数据持久化
OpenBrowserClaw 是一个运行在浏览器里的个人 AI 助手(Browser-native personal AI assistant),它的口号是"零基础设施,浏览器即服务器"。这篇文章带你完整看懂它的存储体系:如何用 IndexedDB 持久化消息、会话与定时任务,如何用 OPFS(Origin Private File System) 为 AI 打造按群组隔离的文件工作区,以及 API Key 的加密方式——全程不依赖任何后端数据库。
一、零数据库服务器的 AI 助手,数据存在哪?
传统 AI 助手需要自建服务器 + SQLite/PostgreSQL,而 OpenBrowserClaw 把"数据库 + 文件系统 + 定时任务"全部塞进了一个浏览器标签页里:
| 数据类别 | 传统方案(NanoClaw) | OpenBrowserClaw 方案 |
|---|---|---|
| 消息、会话、任务 | SQLite(better-sqlite3) | IndexedDB |
| 文件工作区 | 本地文件系统 | OPFS |
| 敏感凭证 | 环境变量 | IndexedDB + AES-256-GCM |
| 部署 | 自托管服务器 | 静态文件,任意 CDN |
所有数据同域隔离(same-origin scoped),除了调用 Anthropic API 外,没有任何数据离开你的浏览器。
二、双引擎存储架构总览
📦 整个存储层只有两个核心文件:
- 结构化数据层:src/db.ts —— 封装 IndexedDB,管理 4 张数据表
- 文件系统层:src/storage.ts —— 封装 OPFS,提供按群组的文件读写
常量定义在 src/config.ts#L50-L56:IndexedDB 库名为 openbrowserclaw,OPFS 根目录名同样是 openbrowserclaw,默认聊天群组 ID 为 br:main。
浏览器标签页(PWA)
├── IndexedDB openbrowserclaw
│ ├── messages 消息流水(按群 + 时间索引)
│ ├── sessions 会话状态
│ ├── tasks 定时任务(cron)
│ └── config 键值配置
└── OPFS openbrowserclaw/
└── groups/<groupId>/workspace/ 每群独立的文件工作区
三、IndexedDB 深度解析:4 张表的设计思路
💾 打开数据库时,onupgradeneeded 回调一次性创建全部表结构,见 src/db.ts#L17-L43:
| 表名 | 主键 | 索引 | 用途 |
|---|---|---|---|
messages |
id |
by-group-time(复合索引)、by-group |
全量聊天流水 |
sessions |
groupId |
— | 每个群组的会话状态 |
tasks |
id |
by-group、by-enabled |
定时任务调度 |
config |
key |
— | 键值配置(模型、触发词等) |
几个值得新手学习的设计细节:
3.1 复合索引实现"最近 N 条消息"
getRecentMessages 利用 by-group-time 复合索引(groupId + timestamp)+ IDBKeyRange.bound 游标,倒序取出最新 50 条再反转——这是把 SQL 的 ORDER BY ... LIMIT 翻译成了 IndexedDB 的游标写法,无需加载全表。
3.2 布尔值不能直接建索引的坑
saveTask 里有个非常实用的技巧:enabled 字段入库前被转成 0/1 数字。因为 IndexedDB 的精确匹配索引中,true 和 1 是不相等的键,所以存数字、查数字、读出时再转回布尔值(见 getEnabledTasks)。这个坑几乎每个用 IndexedDB 做任务调度的人都会踩。
3.3 会话历史如何喂给 AI
buildConversationMessages 把存储的消息转成 Claude API 的对话格式,默认取最近 50 条(CONTEXT_WINDOW_SIZE,定义在 src/config.ts#L17)。你与 AI 的每轮对话上下文,都来自这张 messages 表。
四、OPFS 深度解析:每个群组一个私有工作区
🗂️ OPFS 让 AI 在浏览器里拥有了真正的"文件系统"。src/storage.ts 封装了 5 个核心操作:
| 函数 | 功能 | 对应 AI 工具 |
|---|---|---|
| readGroupFile | 读取工作区文件 | read_file |
| writeGroupFile | 写文件,自动创建中间目录 | write_file |
| listGroupFiles | 列目录 | list_files |
| deleteGroupFile | 删文件 | — |
| groupFileExists | 存在性检查 | — |
4.1 目录结构与群组分片
目录布局为 openbrowserclaw/groups/<safeId>/workspace(见 getGroupDir)。注意 groupId 里的冒号会被替换为连字符——因为文件系统不允许 br:main 这样的目录名,于是 br:main 变成 br-main,Telegram 群 tg:-100123456 变成 tg--100123456。每个群组一份隔离工作区,浏览器聊天和 Telegram 的消息互不干扰。
前端还提供了一个可视化的文件管理页 FilesPage.tsx,可以浏览、预览、下载和删除工作区文件。
4.2 AI 的长期记忆:CLAUDE.md
OPFS 最有意思的用法是"记忆文件":
- AI 通过
update_memory工具把重要偏好写入CLAUDE.md(写入逻辑在 src/agent-worker.ts#L306-L308) - 每次发起对话前,编排器都会先读取该群的
CLAUDE.md拼进系统提示词(见 src/orchestrator.ts#L283-L289)
相当于在浏览器里实现了一个轻量版"长期记忆",且完全基于文件、按群隔离。
4.3 持久化存储申请与配额监控
浏览器可能回收长期不用的站点数据,所以项目调用 requestPersistentStorage(navigator.storage.persist())申请持久化;getStorageEstimate 则实时读取用量/配额,在 SettingsPage.tsx 以进度条展示,并标注"Persistent storage active"。👀 这是把 Storage API 用得相当完整的案例。
五、安全设计:API Key 的 AES-256-GCM 加密
🔒 敏感凭证的存储是 src/crypto.ts 的重头戏:
- 用 Web Crypto 生成不可提取(
extractable: false)的 AES-256-GCM 密钥 - 密钥对象本身持久化到独立的 IndexedDB 库
obc-keystore——JS 永远读不到原始密钥材料,只能调encrypt/decrypt - API Key 加密后以 base64(IV + 密文)存入
config表
README 也坦承边界:这套加密能防 DevTools 和磁盘取证级别的"随手翻",但防不了同源的完整 XSS。对于单用户本地工具,这是合理的安全取舍。
六、上手实践:运行项目并查看自己的存储
最快的体验路径:
cd openbrowserclaw
npm install
npm run dev
打开 http://localhost:5173,粘贴你的 Anthropic API Key 开始聊天。之后可以:
- 打开 DevTools → Application → IndexedDB,查看
openbrowserclaw库里的 4 张表,消息都躺在messages表里 - 查看 Settings 页的存储用量条与持久化状态
- 在 Files 页查看 AI 工作区里由
update_memory生成的CLAUDE.md
⚠️ 两个诚实提醒:数据按源存储,清除浏览器站点数据会清空全部记录;另外 Telegram 通道依赖标签页保持打开(消息会排队,重新打开后处理),这正是"浏览器即服务器"模型的代价——没有后台进程,一切随标签页休眠。
七、总结:IndexedDB + OPFS 带来的价值
OpenBrowserClaw 用不到 400 行的 db.ts + storage.ts 证明了:IndexedDB 管结构化数据、OPFS 管文件、Storage API 管生命周期,这套纯浏览器组合足以撑起一个 AI 助手的完整持久化体系。对新手来说,它的代码也是绝佳的 IndexedDB 实战教材——从复合索引、游标分页,到布尔索引的坑、持久化申请,全都真实可查。如果你的下一个想法是"做个不后端的 Web 应用",可以直接从这个项目开始抄作业。