自建 Supabase 云服务与 BeeCount 云同步详解

自建 Supabase 云服务与 BeeCount 云同步详解

本文是 BeeCount 技术系列第 2 篇，主题：如何 10 分钟完成自建 Supabase 云端并在 BeeCount 中启用“可选云同步”。无论你是只想做本地记账的普通用户，还是希望完全掌控数据的自托管玩家，本文都提供分层次的指导。
项目地址：https://github.com/TNT-Likely/BeeCount （欢迎 Star / Issue / PR）

0. 为什么要自建？（可选，而非必须）

BeeCount 的设计理念是：记账首先应当离线可用，其次才是“可选”云同步。因此应用默认即可离线使用，本地数据存储在设备内的 SQLite，不强制账号，也不强制服务器。只有当你满足以下任一需求时，自建才有价值：
需求是否适合自建说明多设备（手机 + 平板）同步✅同一 Supabase 项目即可同步异地/意外备份✅设备丢失仍可恢复数据绝对主权与隐私✅服务端完全由你掌控只在本机记账❌可直接忽略云同步功能总结：你可以“先用再决定”。不需要在第一次打开 App 就填任何“服务器地址”。
1. 整体架构概览

1. ┌────────────────┐       上传/下载        ┌────────────────────┐
2. │  BeeCount App  │  <------------------>  │  Supabase (Storage) │
3. │  (本地 SQLite) │                         │  + Auth (Email)     │
4. └────────────────┘                         └────────────────────┘
5.        ▲   │                                        ▲
6.        │   │ 指纹/差异计算                           │ RLS 策略限制
7.        │   └─────────────── 本地校验 ───────────────┘

复制代码

核心点：

• 仅使用 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 对象路径规范

1. 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 条策略：
读取

1. create policy "beecount_select_own"
2. on storage.objects for select
3. using (
4.   bucket_id = 'beecount-backups'
5.   and (storage.foldername(name))[1] = 'users'
6.   and (storage.foldername(name))[2] = auth.uid()::text
7. );

复制代码

上传

1. create policy "beecount_insert_own"
2. on storage.objects for insert
3. with check (
4.   bucket_id = 'beecount-backups'
5.   and (storage.foldername(name))[1] = 'users'
6.   and (storage.foldername(name))[2] = auth.uid()::text
7. );

复制代码

更新（可覆盖已有备份）

1. create policy "beecount_update_own"
2. on storage.objects for update
3. using (
4.   bucket_id = 'beecount-backups'
5.   and (storage.foldername(name))[1] = 'users'
6.   and (storage.foldername(name))[2] = auth.uid()::text
7. )
8. with check (
9.   bucket_id = 'beecount-backups'
10.   and (storage.foldername(name))[1] = 'users'
11.   and (storage.foldername(name))[2] = auth.uid()::text
12. );

复制代码

删除

1. create policy "beecount_delete_own"
2. on storage.objects for delete
3. using (
4.   bucket_id = 'beecount-backups'
5.   and (storage.foldername(name))[1] = 'users'
6.   and (storage.foldername(name))[2] = auth.uid()::text
7. );

复制代码

若选择 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上传 403Bucket 未创建或策略缺失按第 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 项目组

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！