OpenBrowserClaw存储体系全解:IndexedDB + OPFS如何重塑浏览器数据持久化

原创2026-11-16 19:00:301,839 阅读

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 最有意思的用法是"记忆文件":

相当于在浏览器里实现了一个轻量版"长期记忆",且完全基于文件、按群隔离。

4.3 持久化存储申请与配额监控

浏览器可能回收长期不用的站点数据,所以项目调用 requestPersistentStorage(navigator.storage.persist())申请持久化;getStorageEstimate 则实时读取用量/配额,在 SettingsPage.tsx 以进度条展示,并标注"Persistent storage active"。👀 这是把 Storage API 用得相当完整的案例。

五、安全设计:API Key 的 AES-256-GCM 加密

🔒 敏感凭证的存储是 src/crypto.ts 的重头戏:

  1. 用 Web Crypto 生成不可提取(extractable: false)的 AES-256-GCM 密钥
  2. 密钥对象本身持久化到独立的 IndexedDB 库 obc-keystore——JS 永远读不到原始密钥材料,只能调 encrypt/decrypt
  3. 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 应用",可以直接从这个项目开始抄作业。

登录后查看全文
openbrowserclaw