chat-demo本地数据层设计揭秘:IndexedDB与localStorage双层存储实战
chat-demo本地数据层设计揭秘:IndexedDB与localStorage双层存储实战
chat-demo 是 DeepSeek 官方开源的纯前端聊天演示项目,没有应用后端,所有数据都保存在浏览器本地:会话与附件原件走 IndexedDB,API Key 与界面偏好走 localStorage。这套 IndexedDB 与 localStorage 双层存储方案,是前端做本地持久化的优秀范本。本文将带你逐层拆解它的设计取舍。
为什么需要双层存储?
浏览器原生提供的本地存储主要有两种,特性差异明显:
| 存储 | 同步/异步 | 容量 | 数据类型 | 适合存什么 |
|---|---|---|---|---|
| localStorage | 同步 | 约 5MB | 仅字符串 | 小体积配置 |
| IndexedDB | 异步 | 可达数 GB | 结构化数据、Blob | 会话、二进制附件 |
chat-demo 的会话包含完整消息树,附件还是二进制 Blob,天然不适合 localStorage;而 API Key、语言、主题这类键值型小配置,用 localStorage 的同步读写最省事。项目在 src/services/settings.ts 的注释里直接写明了分工:「本机设置,存 localStorage:API Key、语言、主题、位置、朗读音色、深度思考与智能搜索开关、侧边栏收起状态」。
💡 一句话原则:小的配置进 localStorage,大的数据进 IndexedDB,各取所长。
IndexedDB 层:会话与附件的持久化主场
数据访问入口集中在 src/services/chat/db.ts,基于 idb 库封装,数据库名为 chat-demo,结构版本号 DB_VERSION = 11(db.ts#L4-L5)。
五个对象存储各司其职
| 对象存储 | 作用 |
|---|---|
sessions |
会话完整详情(全部消息树),打开会话时才读取 |
sessionSummaries |
列表元数据(标题、时间戳)+ 附件引用 fileIds,侧边栏只读它 |
files |
附件原件 Blob,按本地 id 存储,多消息共用一份 |
sessionsStaging |
历史导入的会话暂存区 |
filesStaging |
历史导入的附件暂存区 |
sessionSummaries 是个巧妙的"瘦列表"设计:侧边栏渲染只需标题和时间,不必把每个会话的完整消息树从磁盘拖进内存,types.ts 中 toSessionSummary 负责显式裁剪字段。
事务保证写入原子性
一次 saveSession 会在同一个事务中写入会话详情、列表摘要和附件原件三处(db.ts#L84-L102)。任何一步失败,整个事务回滚,不会出现"列表更新了但详情丢了"的中间状态。删除会话时也是如此:先删记录,再逐个检查附件是否还被其他会话引用(db.ts#L126-L148)。
附件去重与按需清理
附件原件以本地 id 为主键存储,同一条图片被多个消息引用时只存一份。sessionSummaries 上建了 fileIds 多值索引,删除会话时通过 index('fileIds').count(id) 判断原件是否仍被引用,无人引用才真正删除——这等于用索引实现了轻量引用计数,避免删除会话后磁盘上残留孤儿文件。
localStorage 层:设置与密钥的轻量快车道
设置模块 src/services/settings.ts 把所有键统一加 chat-demo: 前缀,例如 chat-demo:api-key、chat-demo:theme-preference、chat-demo:tts-voice(settings.ts#L22-L31),避免与其他站点脚本冲突。
值得学习的细节是它的降级策略(settings.ts#L33-L51):
- 读取时
try/catch包裹,异常时返回null,走默认值逻辑(如语言跟随浏览器); - 写入失败时不抛错,「存储不可用时只在内存中生效」——隐身模式等场景下 localStorage 会抛异常,但应用本身不崩。
设置状态通过 zustand 的 useSettings 持有,界面组件订阅变化即可响应式刷新。
三层数据流:内存 → 详情缓存 → 磁盘
真正驱动界面的并不是数据库,而是内存中的 zustand store src/services/chat/store.ts。整体数据流是:
- 启动:
initChat只从 IndexedDB 读摘要列表,侧边栏立刻可用; - 打开会话:
ensureSessionLoaded按需加载单个会话详情,并发切换同一会话时会合并重复读取; - 详情缓存:
SESSION_CACHE_LIMIT = 5(store.ts#L39-L40),超出后按最近最少使用淘汰,但当前会话、生成中、未保存成功的会话绝不淘汰; - 落盘时机:每次状态变更后异步
persist,并在页面隐藏、关闭前强制补存(store.ts#L228-L254 监听visibilitychange与pagehide),防止刷新丢数据; - 草稿:输入中未发送的草稿只存内存,不写入 IndexedDB,见 drafts.ts#L26-L29。
📌 内存是"工作集",IndexedDB 是"档案库"。流式回答期间界面只更新内存,回复完成或停止后才统一落盘,避免高频写盘。
暂存区设计:历史导入的"整体回滚"
历史导入是最容易损坏数据的操作。chat-demo 的答案是双写 + 原子提交(db.ts#L26-L31):
- 导入期间,会话和附件只写入
sessionsStaging/filesStaging暂存区,正式数据纹丝不动; - 全部校验通过后,
commitStaging在同一事务内逐条游标复制、清空正式区并回填摘要(db.ts#L210-L245); - 中途失败或页面被关,只需清空暂存区,原有会话完好无损;
- 入口
replaceHistory还会先中止正在生成的回复、锁定界面,导入完成前旧记录照常展示(store.ts#L392-L441)。
导入导出的 ZIP 归档结构、字段校验规则,详见官方文档 history/README.md 与入口 backup.ts。
容错哲学:存储失败不打断对话
数据层最后一条原则体现在 reportStorageError(db.ts#L247-L251):本地存储读写失败不会中断聊天,只在控制台留痕;保存失败的会话被标记为"未保存",用户回到页面后可一键重试(retrySaveSessions)。对用户而言,磁盘问题永远是次要问题,对话体验优先。
数据在哪里?如何迁移?
- 隔离:所有本地数据按浏览器用户配置和站点源(origin)隔离,换浏览器即不互通;
- 备份:设置 → 数据管理可导出
deepseek_data-日期.zip,包含会话与本地图片原件,但不含 API Key 与非图片附件; - 清理:「删除所有对话」以空历史原子替换全部本地会话,API Key 与其他设置保留。
小结
chat-demo 的本地数据层值得收藏的实践经验:
- 双层分工——localStorage 存小配置,IndexedDB 存会话与二进制附件;
- 摘要/详情分离,列表轻、详情懒加载;
- 多表写入必须包在事务里,保证原子性;
- 用多值索引做引用计数,删除时自动清理孤儿文件;
- 暂存区 + 原子提交,让"全量替换"类操作可回滚;
- 存储失败降级为控制台日志,绝不打断用户对话。
这套设计对任何需要本地持久化的前端项目都是可直接参考的实战模板。