felis/lxc-streamutils
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

old backend core lib

Browse Source
This commit is contained in:
felis
2026-07-18 11:44:58 -07:00
parent 994854d104
commit f599672a30
36 changed files with 3776 additions and 276 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+1
View File
@@ -47,6 +47,7 @@ flowchart LR
| 组件实例与设置 | PostgreSQL | `InMemoryComponentStore` | 写入成功后刷新热路径缓存 |
| 礼物/表情目录 | Bilibili API | provider catalog | 刷新失败保留最近成功快照 |
| 实时消息 | provider | `EventHub` 有界广播 | 不作为业务持久化机制 |
| 点歌队列和评分 | PostgreSQL | OBS revision snapshot | handler 事务写入、RLS 隔离 |
| PWA 静态壳层 | Docker 镜像 | Cache Storage | 不包含 API 或用户数据 |
## 启动顺序
docs/components/README.md
+4 -3
View File
@@ -1,7 +1,7 @@
# 组件开发指南
组件是“一个直播源上的独立功能实例”。当前内建
`danmaku_overlay`，未来礼物墙、点歌姬或统计组件都应使用同一套契约。
组件是“一个直播源上的独立功能实例”。当前内建 `danmaku_overlay` 与
`song_request`，未来礼物墙或统计组件也应使用同一套契约。
## 一个组件由什么组成
@@ -55,4 +55,5 @@ Handler 面向“业务事实”。例如点歌请求、礼物累计或审计写
- 删除组件或轮换 token 时，关闭该组件 channel，使已有 socket 立即失效。
- 组件 WebSocket 不得暴露其他组件列表或控制 API。
当前组件的具体行为见 [`danmaku-overlay.md`](danmaku-overlay.md)。
当前组件的具体行为见 [`danmaku-overlay.md`](danmaku-overlay.md) 与
[`song-request.md`](song-request.md)。
docs/components/danmaku-overlay.md
+15
View File
@@ -14,6 +14,7 @@
| 字段 | 范围/单位 | 行为 |
| ------------------------ | ----------- | -------------------------- |
| `themeId` | 主题 ID | 选择已安装的完整视觉主题 |
| `fontScale` | 50–300% | 展开与收缩字号的统一比例 |
| `maxVisible` | 1–12 | 同时保留的消息卡数量 |
| `collapseAfterSeconds` | 2–120 秒 | 最新卡从展开态切换到紧凑态 |
@@ -28,6 +29,20 @@
后端的 `OverlaySettings::sanitize` 是最终边界。控制台 range input 只改善交互，不能取代服务端校验。
## 主题
主题同时封装配色、花纹素材、装饰变体、粒子组合与动画名称。当前内置主题为
`jade-scroll`（“青玉花卷”）；控制台仍以选择框呈现，新增主题后无需改变设置交互或卡片队列。
增加主题时需要同步完成三处注册：
1. 在后端 `OverlayThemeId` 中增加稳定 ID，使未知主题无法进入数据库。
2. 在 `apps/overlay/src/themes/` 增加主题定义，并注册到 `overlayThemes`。
3. 提供主题使用的 CSS 动画和素材；不要在 `Card` 中加入按主题 ID 分支。
旧组件没有 `themeId` 时会自动使用
`jade-scroll`。WebSocket 收到未知 ID 时前端也会安全降级到该主题，以支持前后端滚动部署。
## 卡片生命周期
1. 新事件插入队首，以卷轴动画横向展开。
docs/components/song-request.md
+25
View File
@@ -0,0 +1,25 @@
# `song_request` 点歌姬
每个账户自动拥有一个不可删除、不可重复创建的 `song_request`
实例，并与该账户的固定直播源绑定。组件只订阅规范化的
`live.danmaku`；业务状态由 PostgreSQL 保存，不依赖 OBS 是否在线。
## 弹幕命令
- `点歌 <歌名>`：合并首尾和连续空白，接受 1–80 字自由文本。当前或待唱队列中已有大小写不敏感的同名歌曲时忽略。
- `打分 <1-5>`：对事务执行时的当前歌曲评分。同一 Bilibili UID 只有一票，重复评分会覆盖旧分数。
首首点歌立即成为当前歌曲。完成或取消当前歌曲时，队首自动接替；置顶待唱项只把它移动为下一首，不打断当前歌曲。完成或取消后的歌名可以再次点播。
## 设置
`themeId`、`fontScale`、`scrollSpeedPixelsPerSecond` 和 `edgePauseSeconds`
控制 OBS 外观与往返滚动。`maxQueueSize`、`maxRequestsPerViewer` 与 `requestCooldownSeconds`
是可选防刷限制；值 `0` 表示不限制。
## OBS 与管理
OBS 顶部固定显示当前歌曲、点歌用户、平均分和评分人数，下面保存全部待唱横条。列表超过实际浏览器源高度时从顶部滚到底部，再返回顶部；布局不假设固定分辨率。
控制台的“打开点歌统计”进入会话保护页面。它每两秒刷新完整活动队列和近期历史；页面隐藏时停止轮询。管理者可以置顶或取消待唱项，也可以完成或取消当前歌曲。所有 REST 查询都从会话取得 owner，并由 PostgreSQL
RLS 再次限制组件归属。
docs/protocol.md
+34 -16
View File
@@ -33,14 +33,18 @@ log。WebSocket 建立后，客户端必须在 8 秒内发送第一帧：
{
"version": 1,
"type": "authenticated",
"componentId": "08d31d19-3e4b-4c11-9cf7-9bd786a39465"
"componentId": "08d31d19-3e4b-4c11-9cf7-9bd786a39465",
"componentKind": "song_request"
}
```
之后立即发送
`overlay.settings.snapshot`，再开始发送实时事件。token 无效、被轮换或属于其他组件时，服务端以 policy
之后立即发送通用的 `component.settings.snapshot`，再发送该 kind 的状态快照和实时事件。弹幕姬还会发送
`overlay.settings.snapshot` 兼容帧。token 无效、被轮换或属于其他组件时，服务端以 policy
close 结束连接。
设置快照中的 `themeId` 是稳定的主题标识，目前支持
`jade-scroll`。消费者应把未知主题降级为自身默认主题，不能因主题发布顺序不同而中断实时消息。
## 版本化事件信封
```json
@@ -65,19 +69,33 @@ close 结束连接。
## 事件类型
| `type` | 主要 payload | 说明 |
| --------------------------- | --------------------------------------------- | ---------------------- |
| `overlay.settings.snapshot` | `settings` | 认证后当前设置快照 |
| `overlay.settings.updated` | `settings` | 控制台保存后的实时设置 |
| `live.danmaku` | `viewer`, `text`, `segments` | 普通文字和表情分段 |
| `live.enter` | `viewer` | 进房事件 |
| `live.gift` | `viewer`, `gift`, `quantity`, `sourceEventId` | 一次可记账的礼物事件 |
| `live.gift.combo` | `viewer`, `gift`, `quantity`, `comboId` | 同一连击的视觉更新 |
| `live.superchat` | `viewer`, `message`, `price`, `sourceEventId` | 醒目留言 |
| `live.guard.buy` | `viewer`, `guardName`, `quantity`, `price` | 舰长购买 |
| `live.like` | `viewer` | 点赞 |
| `live.share` | `viewer` | 分享 |
| `live.unknown` | `command`, `metadata` | 有界且已清理的未知事件 |
| `type` | 主要 payload | 说明 |
| ----------------------------- | --------------------------------------------- | ---------------------- |
| `component.settings.snapshot` | `settings` | 所有组件的设置快照 |
| `component.settings.updated` | `settings` | 所有组件的设置更新 |
| `overlay.settings.snapshot` | `settings` | 认证后当前设置快照 |
| `overlay.settings.updated` | `settings` | 控制台保存后的实时设置 |
| `live.danmaku` | `viewer`, `text`, `segments` | 普通文字和表情分段 |
| `live.enter` | `viewer` | 进房事件 |
| `live.gift` | `viewer`, `gift`, `quantity`, `sourceEventId` | 一次可记账的礼物事件 |
| `live.gift.combo` | `viewer`, `gift`, `quantity`, `comboId` | 同一连击的视觉更新 |
| `live.superchat` | `viewer`, `message`, `price`, `sourceEventId` | 醒目留言 |
| `live.guard.buy` | `viewer`, `guardName`, `quantity`, `price` | 舰长购买 |
| `live.like` | `viewer` | 点赞 |
| `live.share` | `viewer` | 分享 |
| `live.unknown` | `command`, `metadata` | 有界且已清理的未知事件 |
## 点歌姬状态
`song_request` 认证后按顺序接收：
1. `song.queue.snapshot.begin`：包含 `snapshotId`、`revision`、当前歌曲和待唱总数。
2. 零到多个 `song.queue.snapshot.page`：每页最多 100 个待唱项。
3. `song.queue.snapshot.end`：提交该快照。
后续 `song.queue.changed` 携带连续 revision，`operation` 为 `added`、`promoted`、
`completed`、`cancelled` 或
`rating-updated`。客户端发现 revision 缺口必须重连取得新快照，不能猜测缺失队列状态。
礼物目录价格的原始单位是人民币的千分之一。`gift.totalPrice` 保留该整数单位，`gift.priceCny`
是供展示使用的人民币数值。