BossConsole的Supabase后端架构指南:Edge Functions与数据库迁移如何支撑实时会话和组织管理
BossConsole的Supabase后端架构指南:Edge Functions与数据库迁移如何支撑实时会话和组织管理
如果你正在寻找 BossConsole 后端设计的入门讲解,这篇文章会带你快速看懂它的 Supabase 架构:桌面端(基于 JVM 与 Kotlin 的 AI Agent 控制台)如何只靠 Edge Functions + 数据库迁移,就实现了终端实时会话共享、全窗口应用共享和团队组织管理三大能力,而不需要自建任何服务器。
🧭 整体架构:三层结构
BossConsole 的后端全部集中在 supabase/ 目录下,分为三层:
- 数据库层:supabase/migrations/ 下 100+ 个按时间戳命名的 SQL 迁移文件,负责建表、行级安全策略(RLS)和安全函数(SECURITY DEFINER RPC);
- Edge Functions 层:supabase/functions/ 下的 Deno 函数,负责登录页渲染、API 路由和权限编排;
- 边缘代理层:infra/cloudflare/ 下的 Cloudflare Worker,把
cli.risaboss.com等友好域名透明代理到 Supabase。
上图为 BossConsole 内置 fluck 浏览器跑 Speedometer 3.1 基准测试的成绩截图,完整数据见 benchmark.md。
🔑 实时会话:从一张"只有链接"的表说起
terminal_sessions:存链接,不存内容
终端共享的核心迁移是 20260921120000_terminal_sessions.sql。它的设计哲学非常克制:表里只存分享链接和设备名,终端的实际输出、输入、转录内容永远不进数据库。链接自带端到端密钥(#k=),所以一行数据本身就是一张"凭据",只能被属主读取。
几个值得新手学习的技巧:
- 心跳时间戳由数据库打:触发器
terminal_sessions_touch()在每次 upsert 时用数据库时钟刷新last_seen_at,客户端时钟偏差不会让死会话"装活"; - 概率式清理:15 分钟未心跳的行,在约 10% 的写入请求中顺带清扫,不引入任何定时任务。
live-sessions:一个"零信任"的 Edge Function
20260801000000_organisation_tables.sql 之后的登录与列表服务由 supabase/functions/live-sessions/ 提供,入口在 index.ts:
- 用户在任意浏览器打开
cli.risaboss.com,通过**魔法链接(magic link)**登录,无需密码; /api/sessions不持有 service-role 密钥,而是把用户自己的 JWT 转发给 PostgREST,由数据库 RLS 判定"谁能看什么"——官方注释原话是:This function never holds a service-role key;- 内置分场景限流(OTP、会话列表、OAuth 各一套配额),见 app.ts;
- 所有 Cookie 路由拒绝跨站
Sec-Fetch-Site,防止其他站点"搭便车"。
上图来自 benchmarks/speedometer/ 的对比测试记录,展示同一基准在不同浏览器内核下的分数差异。
中继门票:一次性凭据如何进入 WebSocket 房间
终端中继(Cloudflare Durable Object)的准入由 supabase/functions/relay-admission/ 完成。流程在 20260927010000_terminal_relay_tickets.sql 中定义:
- 桌面端调用
mint_terminal_relay_ticket()领取一张 60 秒有效、只能用一次 的门票; - 数据库只存门票的 SHA-256 哈希,不存明文;
- Worker 调
consume_terminal_relay_ticket()原子核销,失败即拒绝连接。
详见 infra/cloudflare/terminal-relay/README.md。
🖥️ 应用共享:多表协同 + SFU 信令
全窗口共享由 20260928000000_application_sharing.sql 建立 8 张表:app_share_sessions(会话与代际)、app_share_tickets(view/control 角色门票)、app_share_peers(在线参与者)、app_share_control(输入租约,同一时刻只有一个控制者)、app_share_media(SFU 媒体通道)等。
配套的信令 Edge Function 在 supabase/functions/app-sharing/,它只传递认证后的信令消息——SFU 凭据和定位信息永远不会来自客户端。视频流本身走 Cloudflare Realtime SFU,数据库只负责"谁有资格加入"。
🏢 组织管理:多租户的 9 张表与三道安全防线
20260801000000_organisation_tables.sql 把 BOSS 从"单一全局租户"升级为真正的多租户:organisations、organisation_members、organisation_domains、organisation_invites 等 9 张表一次性到位。文件头部的注释值得每个做 SaaS 的人读一遍,它明确列出三个被防御的危险场景:
| 隐患 | 防御手段 |
|---|---|
| 全局权限函数"看不到组织",跨组织误判 | 所有组织级判定走 is_org_admin(org_id) 等显式成员函数 |
| 组织 slug 与全局角色名撞名 → 提权 | 保留 slug 黑名单 + 角色映射触发器拒绝系统角色 |
<slug>_user 继承链放大授权范围 |
按权限域而非 is_system 标志做白名单 |
后续 RLS 策略(20260801020000_organisation_rls.sql)故意只建 SELECT 策略——所有写操作必须经过 20260801030000_organisation_core_rpcs.sql 中的 SECURITY DEFINER 事务函数,"一个 PL/pgSQL 函数即一个事务",保证组织创建在 9 次插入间原子完成。
🧩 organisation Edge Function:组织门户的 Web 端
20260801000000_organisation_tables.sql 建好表之后,用户界面由 supabase/functions/organisation/ 提供:
- app.ts 挂载组织主页、管理后台、域名管理、加入申请、插件页等路由;
- routes/ 下每个文件对应一组页面(如 domains.ts),services/ 负责 DNS 校验、交接令牌等业务逻辑;
- 故意不加 CORS 中间件:所有页面都是同源 Cookie 认证,开放 CORS 等于把会话变成跨域数据泄露通道;
- HTML 只在自定义域名上渲染(Supabase 会把
*.supabase.co上的text/html改写为纯文本)。
20260801050000_organisation_handoff_tokens.sql 配合的一次性"身份交接令牌",让桌面端在无 JWT 的场景(如代管页面)也能安全地代表某个用户操作。
📚 新手可以借鉴的 5 个设计模式
- 迁移文件即文档:每个 SQL 文件头部都有大段"为什么"注释,比任何 wiki 都权威;
- RLS 是访问模型的主体,应用层不重复判断"谁可以看什么";
- Edge Function 尽量无状态、无密钥,把判定权下推到 PostgREST;
- 时间戳与清理交给数据库触发器,不依赖客户端时钟和外部 cron;
- 门票一律短时效 + 一次性 + 只存哈希,凭据泄露窗口以秒计。
相关文档:RBAC 指南、基础设施护栏审计、Secret 浏览器集成。
如果你想动手研究,可以从 supabase/tests/ 的 SQL 测试用例入手——几乎每条安全策略都有对应的回归测试守护。

