如果某张表在新的
stores()声明里漏掉了,升级时它可能会被直接删除。
这是 thus-note(如是记录)源码里的一行注释,大意如此。第一次读到它的时候,我正准备随手清理几个同步上的小毛病,手里的鼠标停在半空,后背凉了一下。
刚开始折腾这个笔记项目时,我想得很浪漫:市面上现成的笔记软件功能太重、弹窗太多,不如自己动手搭一个干净清爽的去处,追求所谓“打开就写,写完就走”,把繁琐的云同步安安静静地藏在幕后。可真当自己接过维护的担子,在代码里摸爬滚打了大半年之后,当初那种轻巧的幻想慢慢变成了敬畏。一个极简的输入框固然能让人痛快地敲下第一行字,但长久的维护终归要回答另一个更实在的问题——当那些碎碎念和日常记录写下以后,无论经历多少次版本升级与换机迁移,数据还要能完完整整地回来。
带着这个问题,我把整个仓库的存储与同步链路从头到尾盘了一遍。
藏在 liu 前缀里的来路
thus-note 不是我从零写的。
点开根目录,README 与 NOTICE 文件里都明明白白地保留着上游开源项目 Liubai 的署名与说明,旁边的 AGPL-3.0-or-later 许可证一个字没动。当初决定做这个笔记工具时,我没打算自己造富文本编辑器和底层同步框架的轮子,而是站在 Liubai 的肩膀上做二次开发。最早的那次提交完成了初始代码的导入与品牌名称的替换;随后的几个月里,我才一步步把统一认证(Caiths Auth)、工作区空间、多端同步改造、数据导入导出、缓存策略与容器化部署接了进去。
直到今天,翻看源码的不少角落,依然能看到带着 liu 前缀的变量与函数命名。每次在编辑器里滑过这些名字,我都觉得它们像是一枚枚安静的胎记,提醒着这段代码的血缘来路。
接手并长期维护一个二次开发项目,其实是一场很磨性子的对话:你得先耐下心来读懂原作者的设计脉络,再去权衡哪些模型值得原样保留、哪些模块必须动刀重构、哪些地方暂时不宜轻举妄动。比起大包大揽地吹嘘自己“从零做出一款软件”,坦坦荡荡地守好开源协议、认清自己真正动过刀的那部分工程改造,心里反而踏实得多。
浏览器里的数据,背着 76 次迁移
刚开始用 Web 端记笔记时,我曾以为留在浏览器本地的数据就像桌面上的 .txt 一样直白。
等真正潜入源码底层才看清,前端是用 Dexie 封装了浏览器的 IndexedDB,数据库名叫 ThusNoteDatabase,里头细密地排布着用户、空间、成员、草稿、正文内容、收藏夹、下载任务以及上传任务等好几张数据表。不知不觉间,本地数据库的版本号已经一路演进到了 76。
开头那行注释就写在这里。每次新增数据表或者调整索引字段时,都必须同步把版本号往上抬一格;倘若某张早先定义过的表在新的 stores() 声明里不小心漏写了,浏览器在执行版本升级时可能会直接把它抹除。原来哪怕把数据留在本地浏览器里,开发者也半点逃不掉 schema 演进的担子:一次看似不起眼的表名微调、一个索引增删、一回旧表清理,稍有不慎,都可能直接决定下一次打开网页时还能看见多少旧笔记。
再看字段设计就会发现,本地存储与云端同步从来不是两套彼此孤立的账本。正文内容与草稿表的旁边,紧挨着负责调度的上下行同步任务表;索引字段严密地覆盖了记录状态、编辑时间、删除时间、提醒时间、标签以及所属的工作区。当指尖在键盘上敲下句号、输入动作停下的那一刻,这段文字就已经步入了一套环环相扣的数据模型里。
盯着那个已经涨到 76 的数字,我常常会在心里盘算那些平时容易忽略的角落:当用户的浏览器从版本 75 升级到 76 时,原有记录能不能一字不落地平滑过渡?升级到一半有人随手关掉了标签页,再次打开时会发生什么?代码能够顺利通过类型检查与构建打包是一回事,而替这些躺在用户浏览器里的旧数据备好全套的迁移测试,则是另一回事。这笔账,我还欠着。
打包成 ZIP,给数据留一扇门
为了让写进去的字句不至于被锁死在单个浏览器的沙盒里,设置页放了 JSON 和 Markdown 两种格式的导出入口。
顺着导出逻辑往下读:程序会先筛选出当前工作区里状态正常的笔记记录,按照创建时间分页拉取,在内存里打包成一个 ZIP 压缩包。选 Markdown 导出,代码会把编辑器里的结构化节点转换成纯文本,并把随附的图片与文件一并写进旁边的 assets 文件夹;选 JSON 导出,则会完整保留内容字段与附件元数据,同时剔除内存里的二进制数据块与云端存储的临时 URL。
这条路径给数据留了一扇随时能打包带走的门,但在排查代码时我也记下了几处还不够严实的地方:
- 导出的范围仅限于当前所在的工作区;
- 单次导出的条数受制于配置项的上限;
- 笔记里的附件只有在本地数据库依然存有
arrayBuffer二进制数据时,才会被顺手写进压缩包里。一旦某个早期附件在本地只剩下一串指向云端的临时地址,目前的导出程序还不会主动先去远端把文件拉下来再打包。
最后这一条最让我在意:用户以为自己导出了全部,实际却漏掉了几张旧图,而且在界面上毫无知觉。
与之对应的导入流程,则会先逐一校验记录 ID、所属空间与内容类型,随后解包处理 ZIP 里的附件资源。当一批外部笔记被导入当前账号时,数据的归属权会被统一改写为当前的用户、成员与工作区;对于本地数据库里尚不存在的记录标记为新增,而对于已经存在的同 ID 记录,只有当导入版本的 updatedStamp 时间戳比本地更新时才会走入覆盖分支,其余记录维持原样。等在界面上点下确认,这些新增与更新的记录便会通过 bulkPut 批量写进 IndexedDB,并顺带触发全文搜索字段的重建。
平时自己写代码,人很容易把精力全扑在输入框的响应够不够跟手、动画够不够顺滑上;等真正背起维护的担子才明白,把源码里那个关于 profile 上下文处理的 TODO 补齐、给跨越正文与附件的批量写入加上稳妥的回滚保护,才是让“本地优先”这四个字立得住的根本。
5 月 6 日的那个晚上
把目光从本地存储移向网络层,多端同步的代码里同样留着不少深夜排障的真实脚印。
正常流程下,每当本地产生编辑改动,同步模块会先把改动打包成一条上行任务,状态从 waiting 切换为 syncing,倘若遇上网络抖动请求失败,便重新退回等待队列;而下行拉取的请求则会把短时间窗口内的多个任务合并到一起发送,拿到响应后再按照各自的 taskId 拆分派发。
5 月 6 日那天留下的一串连续提交,我到现在还记得是怎么来的。
那天晚上,加密同步一直报错,多端登录时密钥互相打架。为了解决这个问题,我先在后端引入了一套基于 Redis 的 client_key 候选存储机制:把客户端当前的密钥与历史密钥在缓存里保留七天,每次收到加密请求时最多取出五个去重后的候选密钥逐一尝试解密;只有当所有候选密钥都对不上号时,才向前端返回 401 状态码,通知客户端重新登录刷新密钥。
可后端改完接着联调时,前端的加密封装还是时不时闹脾气。夜已经很深了,为了先把笔记同步的主流程保住,我在随后的提交里做了一个妥协:把前端的三个核心同步入口改成了直接依托底层的 HTTPS 传输 atoms 数据结构,提交说明里也老老实实记了一笔“临时绕过加密同步报错”。
(“临时”这两个字,在程序员的字典里通常意味着“很久”。)
如今回头看,后端的多密钥解密兼容路径与前端直接发送明文结构体的路径就这么并排留在了仓库里,根路由旁还单列着兼容旧调用的 /get 与 /set 路由。
更让我记挂在心上的,是那天排障时随手打开的调试日志。为了看清数据到底卡在哪一步,当时在前端上行代码里直接把发送的 atoms 内容和响应打印进了浏览器控制台,后端的解密排查路径上也输出了密钥前缀、IV 向量、用户标识和报错详情,甚至仓库里还跟踪了几个早期的 .env 配置文件。在调试的当口,这些日志确实帮我逮住了虫子;可对于一个用来存放私人随想的笔记工具来说,排完障之后必须把这些日志干干净净地收起来,把 .env 和历史凭据彻底清理掉,再把当初临时绕开的应用层加密封装重新合拢。把这些带着汗水味的欠账一笔笔记清,下回动手修整时才不会手忙脚乱。
PWA 更新得很快,测试还没跟上
除了躺在 IndexedDB 里的结构化笔记,作为渐进式 Web 应用,它还会在浏览器里缓存一整套前端静态资源。
目前 Service Worker 的注册策略设为了 autoUpdate,安装阶段直接执行 skipWaiting,并在激活时立刻调用 clients.claim 接管页面;与之配合的 Nginx 部署配置则明确对 index.html、Service Worker 脚本以及 manifest 清单禁用缓存,好让浏览器每次打开时都能第一时间拿到新版本。
8 月 9 日那天,我在本地检出最新提交,把整条构建链重跑了一遍。前端 vue-tsc 类型检查、Vite/PWA 生产构建,后端 TypeScript 编译和 Node.js 22 环境下的打包都顺顺当当地走完了,吐出一份包含 264 项资源的预缓存清单。终端里顺带飘过几行黄字警告:某个调试依赖内部用了 eval,本地缓存模块混用了静态与动态导入,主 chunk 体积越过了 500 kB 的提醒线。
一切看着都挺好。我顺手在后端终端里敲下 pnpm test。
jest: command not found
我盯着这行报错愣了好一会儿。翻回 package.json,脚本栏里明明写着 jest,依赖锁文件里却压根没装这个包;早先留在 tests 目录里的脚本,也还被排除在编译范围之外;远端的 GitHub Actions 工作流里同样只跑了安装、构建和发布。原来这么久以来,那一排绿色的勾,从来没有替我测过任何实际的业务逻辑。
说实话,有点哭笑不得,但更多是庆幸——幸好是我自己翻了出来。当 Service Worker 执行 skipWaiting 强行接管一个在后台挂了好几天的旧标签页时,正在输入框里敲了一半的草稿能不能稳稳落盘?新脚本触发的本地数据库升级要是遇上阻碍,多个标签页之间怎么通气?这些问题,光靠绿色的构建流水线是回答不了的。
下一轮修整的头三件事
关掉构建终端之前,我在备忘录里给 thus-note 的下一轮修整列好了头三件事:
- 把同步链路上的调试日志与环境配置清理干净;
- 把
Jest测试环境实打实配起来; - 拿一份脱敏的固定样本数据,在自动化环境里完整跑通一次“版本升级、导出
ZIP、清空本地库、重新导入并逐字节比对正文与附件”的闭环。
“打开就能写”,只是向用户发出了一份邀请。而唯有亲眼确认每一行写下的字都能跨越缓存、网络与版本的更替,毫发无损地回到屏幕前,这份关于记录的承诺才算真正落了地。