词根志上线：从本机工具到全球可用的跨设备学习应用

一个原本只在本地 localhost 运行的单词溯源学习应用，终于走出了这台电脑——现在任何设备打开同一个网址，就能继续昨天的学习进度。

起因

「词根志」是我一直在打磨的一个英语单词学习工具：听音回忆卡片、间隔复习、词根溯源三代（本义 → 拉丁/希腊 → 印欧祖根）、文章导学、测验、错词本、牛津词表浏览……功能齐全，但有一个致命问题：它只能在这台电脑上跑。

学习进度存在 localStorage 里，换台电脑、换部手机就归零。关键词库和 PWA 离线下载做得很早，但「跨设备」始终缺一块真正的后台。

这次的目标很明确：

1. 拿到一个永久的公开网址，任何设备打开即用
2. 真正的跨设备同步：同账号登录，进度自动合并
3. 沿用本博客的成熟架构，不引入新平台

方案：Cloudflare Pages + Supabase

本博客就是「Cloudflare Pages 前端 + Supabase 数据库」的组合，词根志直接复用同一套栈：

• 前端：静态资源照旧（零改动成本），部署到 Cloudflare Pages，自带 HTTPS、全球 CDN、可安装 PWA
• 后台：Supabase（与博客共用一个项目，但表完全独立）+ Cloudflare Pages Functions 提供 API

架构图：

任何设备浏览器
   │  https://root-lexicon.pages.dev
   ▼
Cloudflare Pages（静态资源 + Functions API）
   │  service_role（仅服务端持有）
   ▼
Supabase PostgreSQL（wa_users / wa_sessions / wa_state）

后台：3 张表 + 5 个接口

SQL 里只建了三张表，全部开启 RLS 并显式拒绝 anon/authenticated 直接访问（所有读写只经由服务端 Functions 用 service_role 完成，与博客的防线上保持一致）：

表	作用
wa_users	学习账号：昵称（唯一）、目标考试、每日目标、scrypt 加盐密码哈希
wa_sessions	登录会话：只存 token 的 SHA-256 哈希，30 天有效
wa_state	每账号一行：整包学习状态 jsonb + 逐条时间戳 stamps

Pages Functions 五个端点：

• POST /api/auth/register / login / logout / profile
• GET|PUT /api/state —— 学习状态的上传与拉取

安全细节：密码用 Node 内置 crypto.scrypt（N=16384, r=8, p=1）加盐哈希，数据库里永无明文；会话令牌本身也只存哈希，即使库泄露也无法冒用；退出登录即删除会话记录，旧 token 立即失效。这些在部署后都做了真实验证。

前端：一套「本地优先 + 时间戳合并」的同步层

应用原本是纯本地 localStorage 多用户结构，我加了 ~150 行同步层，原则是本地优先、断网可用、联网补齐：

• 打点：每次学习动作（评分、错词、打卡）都落下时间戳，持久化到本地 rootbook_sync_<账号>
• 推送：任何变更后防抖 4 秒整包上传（prog / log / err / daily / settings + 各自的 stamps）
• 拉取合并：登录后拉云端状态，按时间戳逐条合并：
  • log（每日学习数）和 daily（每日新词数）是加法语义——两边同一天都学过就相加，不会互相覆盖
  • prog（单词进度）和 err（错词本）是状态语义——后评分者胜
  • 导入备份 / 清空数据这样的全量操作会标记 all 时间戳，以较新一方的意图为准

因为推送是异步：断网时一切照旧写本地，联网后自动补齐，学习过程零感知。

验证：9 项端到端测试全过

部署完成后没用“看起来能跑”糊弄，而是用 curl 对生产环境做了完整回路验证：

1. 注册 → 返回 token + 用户资料 ✅
2. 登录 → 校验通过 ✅
3. 错误密码 → 密码错误 ✅
4. 重复昵称 → 该昵称已被注册 ✅
5. 上传学习状态 → ok ✅
6. 拉取 → 与上传内容逐字段一致（往返无损）✅
7. 无 token 拉取 → 拒绝 ✅
8. 退出登录 → 会话删除 ✅
9. 退出后用旧 token → 已失效 ✅

测试账号已清理，数据表干干净净。

现在的样子

网址：https://root-lexicon.pages.dev

• 电脑、手机、平板：打开网址，输入昵称 + 密码即可
• 同一账号任何设备登录，进度自动合并；各设备断网也能学（数据暂存本机，联网自动补齐）
• 手机浏览器可「添加到主屏幕」当 App 用；设置页可下载全部词库离线学习
• 原有的账号系统无缝升级：老用户首次输入密码登录即自动开通云端，本地进度自动上传

从「只能在这台电脑上打开」到「全球任何设备随时继续」，中间差的是一个后台 + 一层聪明的同步。这一趟走完，词根志才算真正毕业了。