当前位置：首页 > news >正文

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

news 2025/9/23 9:31:30

自建 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 自写	✅✅✅	高	任意	重度技术玩家