自建 Supabase 云服务与 BeeCount 云同步详解
本文是 BeeCount 技术系列第 2 篇,主题:如何 10 分钟完成自建 Supabase 云端并在 BeeCount 中启用“可选云同步”。无论你是只想做本地记账的普通用户,还是希望完全掌控数据的自托管玩家,本文都提供分层次的指导。
项目地址:https://github.com/TNT-Likely/BeeCount (欢迎 Star / Issue / PR)
0. 为什么要自建?(可选,而非必须)
BeeCount 的设计理念是:记账首先应当离线可用,其次才是“可选”云同步。因此应用默认即可离线使用,本地数据存储在设备内的 SQLite,不强制账号,也不强制服务器。只有当你满足以下任一需求时,自建才有价值:
需求 | 是否适合自建 | 说明 |
---|---|---|
多设备(手机 + 平板)同步 | ✅ | 同一 Supabase 项目即可同步 |
异地/意外备份 | ✅ | 设备丢失仍可恢复 |
数据绝对主权与隐私 | ✅ | 服务端完全由你掌控 |
只在本机记账 | ❌ | 可直接忽略云同步功能 |
总结:你可以“先用再决定”。不需要在第一次打开 App 就填任何“服务器地址”。
1. 整体架构概览
┌────────────────┐ 上传/下载 ┌────────────────────┐
│ BeeCount App │ <------------------> │ Supabase (Storage) │
│ (本地 SQLite) │ │ + Auth (Email) │
└────────────────┘ └────────────────────┘▲ │ ▲│ │ 指纹/差异计算 │ RLS 策略限制│ └─────────────── 本地校验 ───────────────┘
核心点:
- 仅使用 Supabase Auth + Storage;备份文件是 JSON / (未来可能 gzip)
- 不侵入你本地日常记账流程;上传/下载是显式操作或可选“自动同步”
- 采用“指纹 + 条数 + 时间戳”判断差异,避免不必要全量下载
2. 准备你的 Supabase 项目(约 5 分钟)
2.1 创建项目
- 打开 https://supabase.com → 登录 / 注册
- New Project → 选择离你最近 Region
- 设置数据库密码(只在数据库管理时用;客户端不会用到)
- 等待项目初始化完成
2.2 获取配置参数
进入 Project → Settings → API
Project URL
复制为SUPABASE_URL
anon public
复制为SUPABASE_ANON_KEY
切记:不要在客户端使用
service_role
。
3. 创建存储 Bucket 与访问策略
BeeCount 使用 Storage Bucket: beecount-backups
保存每个账本的快照文件。
3.1 创建 Bucket
- Project → Storage → "New bucket"
- 名称:
beecount-backups
- 访问权限:建议 Private(更安全);Public 也能用但不推荐
- 创建完成
3.2 对象路径规范
users/{user_id}/ledger_{ledgerId}.json # 或未来:.json.gz
{user_id}
为 Supabase Auth 分配的 UUID- 一个用户多个账本 → 多个文件并列
3.3 RLS 策略(Storage Objects)
打开 SQL Editor,针对 storage.objects
(或通过 Storage → Policies)添加 4 条策略:
读取
create policy "beecount_select_own"
on storage.objects for select
using (bucket_id = 'beecount-backups'and (storage.foldername(name))[1] = 'users'and (storage.foldername(name))[2] = auth.uid()::text
);
上传
create policy "beecount_insert_own"
on storage.objects for insert
with check (bucket_id = 'beecount-backups'and (storage.foldername(name))[1] = 'users'and (storage.foldername(name))[2] = auth.uid()::text
);
更新(可覆盖已有备份)
create policy "beecount_update_own"
on storage.objects for update
using (bucket_id = 'beecount-backups'and (storage.foldername(name))[1] = 'users'and (storage.foldername(name))[2] = auth.uid()::text
)
with check (bucket_id = 'beecount-backups'and (storage.foldername(name))[1] = 'users'and (storage.foldername(name))[2] = auth.uid()::text
);
删除
create policy "beecount_delete_own"
on storage.objects for delete
using (bucket_id = 'beecount-backups'and (storage.foldername(name))[1] = 'users'and (storage.foldername(name))[2] = auth.uid()::text
);
若选择 Private Bucket,必须有这些策略,否则客户端无法读写。
4. 在 BeeCount 中启用自定义云服务
打开 App → 我的 → 云服务:
- 点击“新增 / 修改 自定义 Supabase”
- 粘贴
SUPABASE_URL
与SUPABASE_ANON_KEY
- 保存后自动登出(防止旧 session 混用)
- 登录/注册(邮箱)
- “同步”区域点击“上传”执行首次全量上传(每个账本一次)
- 可选:开启“自动同步”
- 随时可以“切回默认”且自定义配置不会丢失,再次进入可一键启用
提示:首次上传完成后,状态将变为“已同步”;若看到“本地较新”再点一次刷新即可。
5. 同步工作原理(简述)
步骤 | 动作 | 说明 |
---|---|---|
获取状态 | 计算本地指纹 + 查询远端文件元数据 | 指纹:基于账本记录序列化哈希 |
上传 | 序列化当前账本 → 覆盖用户目录下对应文件 | 失败自动提示,不隐式重试 |
下载 | 获取文件 → 解析 → 合并本地(去重) | 输出导入/跳过/重复统计 |
差异判断 | localCount / cloudCount / fingerprints / 时间 | 多条件组合更准确 |
未来计划(Roadmap 方向):
- 多账本“一键首次全量上传”
- 增量(差量)同步(减少流量)
- 端到端加密(可选)
6. 问题排查(Troubleshooting)
问题 | 可能原因 | 解决 |
---|---|---|
登录失败 (PKCE storage) | 使用旧版本或错误的 key | 更新到最新 App;确认使用 anon key |
上传 403 | Bucket 未创建或策略缺失 | 按第 3 节检查 bucket + 4 条策略 |
上传后仍显示“本地较新” | 对象存储延迟/指纹未刷新 | 等待数秒或点“刷新同步状态” |
下载失败 404 | 文件尚未上传 | 先执行一次“上传”初始化 |
多设备不一致 | 另一设备未上传最新 | 另一端上传后此端下载/刷新 |
7. 安全与成本
- 仅使用
anon key
,永不写死service_role
- 私有 Bucket + RLS 策略 = 用户隔离
- 定期在“导出”生成 CSV 线下备份
- Supabase 免费额度(个人记账极低占用)即可长期使用
8. FAQ(精简)
Q: 我可以不自建吗? 可以,完全本地使用;想同步再配置。
Q: 自定义模式后能切回默认吗? 可以,且自定义配置保留。
Q: 首次全量上传会覆盖云端旧数据吗? 会覆盖对应账本文件,但只影响你自己的目录。
Q: 未来会支持差量同步吗? 计划中。
Q: 支持端到端加密吗? 规划中,将以可选方式提供。
9. 与其他方案对比(简要)
方案 | 自主可控 | 学习/运维成本 | 数据粒度 | 适合人群 |
---|---|---|---|---|
纯本地 (不自建) | ✅ | 最低 | 设备级 | 仅需本机 |
自建 Supabase (当前) | ✅✅ | 低 | 账本文件 | 想跨设备/备份 |
自建后端 + API 自写 | ✅✅✅ | 高 | 任意 | 重度技术玩家 |
10. 推广 & 参与
如果你觉得 BeeCount 的“可选云同步 + 自主托管”理念有价值:
- 给仓库一个 ⭐️ Star 支持项目持续演进
- 分享给需要记账但不想被数据“绑定”在平台上的朋友
- 提交 Issue:帮助我们发现 bug / 需求
- 提交 PR:实现 Roadmap 或文档改进
Roadmap 草案(择机推进):
- ✅ 自定义 Supabase 动态切换(已完成)
- ⏳ 多账本一键全量上传
- ⏳ 增量同步(diff)
- ⏳ 端到端加密(E2EE)
- ⏳ 更丰富统计与图表
11. 结语
BeeCount 不希望“绑定用户”,而是提供一套从纯离线到完全自托管的自由梯度。你可以今天离线记一笔,明天想同步了再 10 分钟自建;也可以永远不连接任何服务器。掌控感与透明度,正是开源记账应用应当具备的底色。
如果本文对你有帮助,欢迎 Star / 转发;也欢迎在 Issue 中分享你的自建经验。
—— BeeCount 项目组