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

自建 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 创建项目

1. 打开 https://supabase.com → 登录 / 注册
2. New Project → 选择离你最近 Region
3. 设置数据库密码（只在数据库管理时用；客户端不会用到）
4. 等待项目初始化完成

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

1. Project → Storage → "New bucket"
2. 名称：beecount-backups
3. 访问权限：建议 Private（更安全）；Public 也能用但不推荐
4. 创建完成

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 → 我的 → 云服务：

1. 点击“新增 / 修改 自定义 Supabase”
2. 粘贴 SUPABASE_URL 与 SUPABASE_ANON_KEY
3. 保存后自动登出（防止旧 session 混用）
4. 登录/注册（邮箱）
5. “同步”区域点击“上传”执行首次全量上传（每个账本一次）
6. 可选：开启“自动同步”
7. 随时可以“切回默认”且自定义配置不会丢失，再次进入可一键启用

提示：首次上传完成后，状态将变为“已同步”；若看到“本地较新”再点一次刷新即可。

---

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 项目组