Butterbase KV 存储与 Realtime 实时订阅指南如何用 WebSocket 快速构建直播 UI【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-ossButterbase 的 KV 存储与 Realtime 实时订阅是两款开箱即用的后端能力KV 提供按 Key 快速读写的键值存储会话、计数器、锁、功能开关Realtime 则通过 WebSocket 把数据库表的每次 INSERT / UPDATE / DELETE 实时广播给前端。两者组合起来你就能以极低的成本构建数据一改、界面立变的直播数据 UI无需自己维护消息队列或轮询接口。先搞懂KV 存什么Realtime 管什么很多人分不清这两者的分工一张表说清楚你想做的事该用什么存会话 Token、购物车、向导进度KV自动过期免清理页面浏览量、限流计数KVincr原子自增分布式锁、防重复扣款KVsetnx原子占位功能开关 / A/B 配置改值不发布KV数据库行变化后前端秒级刷新Realtime聊天室、直播评论、多人协作光标Realtime订阅 Presence官方给出的选型建议很直接KV 适合按 Key 访问、会自然过期、不需要关系查询的数据消息队列、pub/sub、流式场景交给 Realtime。完整的场景对照见 kv.md 的 When to use KV 小节。KV 快速上手写入、过期与原子操作在 Serverless 函数里KV 通过ctx.kv直接调用Key 自动按应用隔离不需要手动加前缀。最常见的三类操作// 存一个 1 小时后过期的会话 await ctx.kv.set(session:abc123, { userId: u_1 }, { ttl: 3600 }); // 原子计数器不存在时从 0 开始自增 const views await ctx.kv.incr(counter:page:/home); // 分布式锁Key 不存在才写入成功TTL 就是锁的租约时长 const acquired await ctx.kv.setnx(lock:order:99, ctx.requestId, { ttl: 30 });几个新手常踩的点默认 TTL 是 30 天不传ttl时 Key 会在 30 天后自动过期传{ ttl: null }表示永不过期见 kv.md 的 TTL 小节。默认 Key 都是私有的浏览器/移动端默认读不到 KV必须显式开放。用一行expose即可把某个命名空间开放给前端且支持{user.id}模板让每个用户只访问自己的 Key// 每个用户只能读写自己的 profile别人访问一律 403 await ctx.kv.expose(profile:{user.id}, { read: owner, write: owner });会话、锁、限流、幂等键、功能开关五种高频模式都有可复制的完整配方推荐直接看 kv-recipes.md。不想写代码也可以在终端执行butterbase kv set feature:new-checkout on下一行代码都不用改功能开关即时生效CLI 命令实现在 kv.ts。Realtime 实时订阅三步开启 WebSocket 推送Realtime 的原理是给表装上数据库触发器行变化通过pg_notify广播到 WebSocket 连接数据面迁移见 007_realtime.sql配置表见 022_realtime_config.sql。第 1 步CLI 一键开启butterbase realtime enable messages命令会列出每张表的配置状态之后butterbase realtime config随时可查实现见 realtime.ts。第 2 步前端建立 WebSocket 连接浏览器端把用户 JWT 放在查询参数即可RLS 会限制用户只收到自己有权查看的行const ws new WebSocket(wss://api.butterbase.ai/v1/app_abc123/realtime?token${token}); ws.onopen () { ws.send(JSON.stringify({ type: subscribe, table: messages })); };第 3 步按字段过滤只收你要的变化订阅时可以加filter只有列值完全相等的变化才会推送——比如直播场景里只关注当前频道的评论{ type: subscribe, table: messages, filter: { channel_id: abc } }服务端会持续推送change事件含op、record、old_record、timestamp另有heartbeat保活。协议全貌见 realtime.md。构建直播 UI让数据变化秒级驱动界面如果不想裸写 WebSocket 协议TypeScript SDK 的RealtimeClient已经把连接—订阅—断线重连—心跳检测全部封装好见 realtime-client.ts// 订阅带过滤条件的变化断线后自动重连并重放订阅 bb.realtime.on(messages, { channel_id: abc }, (change) { if (change.op INSERT) addMessageToUI(change.record); });客户端内置指数退避重连最长 30 秒间隔和 45 秒心跳超时检测重连后会自动重新订阅所有表并恢复 Presence 跟踪省去大量样板代码。进阶直播弹幕与多人协作的 PresenceRealtime 除了数据变化广播还内置两条对直播 UI 特别实用的通道Presence 在线状态发送presence_track并附带元数据昵称、光标坐标等服务端会把presence_join/presence_update/presence_leave/presence_state广播给所有跟踪者——协作白板光标、直播间谁在看都靠它协议示例见 realtime.md。注意 Presence 是内存态服务重启会重置。WebSocket 自定义事件给函数绑定websocket触发器后前端发一条{ type: event, event: chat_message, payload: {...} }函数处理完把event_response原路返回——相当于一条低延迟的请求—响应旁路适合弹幕审核、点赞计数这类逻辑。两个新手要留意的限制事件是行级全量推送暂不支持列过滤重连瞬间可能丢事件客户端应在重连后重新拉取一次状态兜底见 realtime.md。相关文件速查内容路径KV 概念与 API 详解services/docs/src/content/docs/core-concepts/kv.mdRealtime 协议与示例services/docs/src/content/docs/core-concepts/realtime.mdKV 可复制配方集services/docs/src/content/docs/guides/kv-recipes.mdCLIrealtime enable/config/disablepackages/cli/src/commands/realtime.tsSDKRealtimeClient 实现packages/sdk/src/realtime/realtime-client.ts数据面 Realtime 迁移db/data-plane/007_realtime.sql一句话总结短期状态找 KV实时推流找 Realtime——先开表、再连 WebSocket、加上 filter 与 Presence一个会动的直播 UI 就完成了。【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考