proper productionize project

2026-07-15 23:54:53 -07:00
parent b8850c87a4
commit edb6d2b5b4
46 changed files with 11346 additions and 1560 deletions
@@ -1,31 +1,138 @@
-# 洛星瓷直播弹幕姬
+# 洛星瓷直播组件服务

-运行前复制带注释的 `config.toml.example` 为 `config.toml`，填入 CookieCloud、设置数据库和访问密钥，然后执行：
+这是一个多用户 Rust/Axum 直播组件后端。目前内建 `danmaku_overlay` 弹幕姬，后端已经按“直播源 → 强类型事件 → 组件实例”的方式拆分，后续可以继续增加礼物展示、点歌姬等组件。镜像构建阶段会编译 React 前端，运行时由 Rust 同域托管控制台和 OBS 页面。
+
+直播连接使用 [`blivedm_rs`](https://github.com/isomoes/blivedm_rs) 的 `blivedm` crate。项目在 `vendor/blivedm` 固定了保留原始 JSON 的小补丁，避免 UID、礼物价格和上游事件 ID 被简化消息结构丢弃。
+
+## 后端结构
+
+`src/main.rs` 只负责配置、组装、监听和优雅退出，可复用核心由 `src/lib.rs` 导出：
+
+- `live/` 中的 provider adapter 把 Bilibili 消息归一化为 `domain.rs` 的强类型事件；`SourceSupervisor` 保证每个用户的固定直播源只有一个 listener。
+- `components.rs` 注册组件定义、设置 schema/迁移、事件订阅、纯投影和独立副作用 handler；新礼物展示或点歌姬不需要修改弹幕姬队列核心。
+- `realtime.rs` 按 component UUID 建立独立广播通道，路由时同时校验 owner 与 source；副作用 handler 不依赖 OBS WebSocket 是否在线。
+- `auth.rs`、`repository.rs` 和 PostgreSQL RLS 共同实现身份、凭据、直播源、组件与 token 的用户隔离；`http_api.rs` 从服务端会话推导 owner，不接受客户端自报 owner ID。
+
+## 部署
+
+先复制配置并生成独立密钥：

 ```sh
 cp config.toml.example config.toml
+openssl rand -base64 32   # 填入 security.data_encryption_key
+openssl rand -hex 32      # 可作为一次性 admin.password
+openssl rand -hex 32      # 填入兼容字段 admin.session_secret
 docker compose up --build -d
 ```

-应用配置遵循 `blivedm_rs` 的 TOML/`--config` 形式；Compose 会以只读方式将 `config.toml` 挂载到容器并传入 `--config /app/config.toml`。配置段及字段说明直接写在 [config.toml.example](config.toml.example) 的注释中。
+Compose 将 `config.toml` 只读挂载到 `/app/config.toml`，应用通过 `--config` 读取它。容器使用 host 网络，默认只在 `127.0.0.1:9719` 监听，供同机 Nginx 访问；不要把 `9719` 直接暴露到公网。

-应用容器使用 host 网络并监听 `9719`。它通过 `[database].url` 连接 PostgreSQL，仅用于持久化 OBS 弹幕姬设置。应用会自动创建所需表；`[connection].room_id`、CookieCloud Key/UUID 与密码均为必填配置。
+容器默认以 `1000:1000` 非 root 身份、只读根文件系统运行，并丢弃全部 Linux capabilities。请将 `config.toml` 设为 `chmod 600`，并确保容器用户可读；如宿主机用户不是 `1000:1000`，启动前设置 `APP_UID` 与 `APP_GID`。

-服务端已迁移为 Rust/Axum，并使用 [`blivedm_rs`](https://github.com/isomoes/blivedm_rs) 发布的 `blivedm` crate 建立 Bilibili 认证弹幕连接；不再使用 Node 服务端或 `@laplace.live/ws`。为确保 UID、礼物价格和上游事件 ID 不会被库的简化消息结构丢弃，项目在 `vendor/blivedm` 固定了一个仅保留原始 JSON 的小补丁。应用从 CookieCloud 获取 Bilibili Cookie（必须包含 `SESSDATA`），用于获取认证 UID、直播间网关与 WebSocket 鉴权包。
+`[database].url` 指向 PostgreSQL。应用启动时自动执行版本化迁移，数据库保存账户、一次性邀请码、TOTP 注册状态、可撤销会话、恢复码摘要、用户直播源、组件设置、OBS 令牌摘要和审计记录。租户表同时使用 owner 复合外键与 PostgreSQL RLS 约束，HTTP API 也始终从当前会话取得 owner，客户端不能自行指定其他用户。

-## OBS 弹幕姬
+`security.data_encryption_key` 必须是独立生成并妥善备份的 32 字节 Base64 密钥。TOTP Secret 与每个用户的 CookieCloud Key/密码会在写入 PostgreSQL 前用它加密；丢失或擅自更换该密钥会导致已有账户和 CookieCloud 凭据无法解密。

-镜像会在构建阶段编译 `apps/overlay`，最终由 Rust/Axum **同域托管**：
+## 首次初始化与登录

- `/obs?token=你的_OBS_访问令牌`：透明背景的 OBS 浏览器源。它没有固定画布，按浏览器源的实际宽高自动在窄侧栏、常规卡片和低高度模式之间切换。
- `/control`：管理员控制台。使用 `admin.password` 登录后可改标题、字号、事件类别、最大条数、自动收缩、卷轴展开时长、动效、每卡粒子数量与速度、低性能模式和礼物高亮阈值；保存会实时广播给已打开的 OBS 源。
+首次部署且数据库中尚无账户时，打开：

-控制台的“复制 OBS 地址”会生成含只读令牌的完整地址。该令牌仅能订阅 `/ws`，不能访问管理或写入接口。常用 OBS 浏览器源尺寸可从 `360×600`、`440×760` 或 `600×1080` 开始；可按实际版面自由拖拽缩放，不会出现 1920×1080 的固定画布留白。
+```text
+https://danmaku.luoxingci.com/control/setup
+```

-每张消息卡片都会从六套花纹组合中稳定选取一套，轮换使用对称花枝、横向自然藤纹和雏菊花簇，并改变上下、左右、镜像、配色与局部背景；连续的新卡会主动避开相同款式，礼物连击更新则保持原样式不跳动。透明消息墙本身不铺设全局装饰背景。粒子数量与速度可在控制台调整；窄尺寸会自动减少粒子，低性能模式会关闭动态粒子。花边 SVG 已本地打包，来源和公版/CC0 许可记录在 `apps/overlay/public/assets/NOTICE.md`，OBS 运行时不会访问素材站点。
+填写系统管理员用户名和 `config.toml` 中的 `admin.password`，扫描页面生成的 TOTP 二维码，再输入验证器中的 6 位动态码完成初始化。页面只显示一次恢复码，请立即离线保存。

-后端会在启动时、之后每十分钟调用 Bilibili 的无需 Cookie 礼物面板接口缓存礼物图片、GIF、币种和价格。目录刷新失败时保留上一次成功缓存；缺失目录条目会安全降级为直播事件自带的名称与价格。
+`admin.password` 只是“允许创建第一个系统管理员”的一次性 bootstrap proof：

-直播弹幕中的普通混排表情和整条大表情会作为安全的文字/图片分段通过 WebSocket 推送。消息自带的图片地址优先；服务还会使用 CookieCloud 的 `SESSDATA` 刷新直播间表情目录，在消息只提供表情唯一标识时补齐图片。图片加载失败时前端会退回原始表情文字。
+- 它不会保存为账户密码，也不能用于日常登录。
+- 第一个账户创建后，bootstrap 接口永久拒绝再次初始化。
+- 所有账户都是 passwordless 账户，以“用户名 + TOTP”登录；丢失验证器时可使用一次性恢复码。
+- 会话使用随机令牌，数据库只保存摘要，可在服务端到期或撤销。

-刷新间隔和请求超时可通过 `[gifts]` 调整。`[overlay]` 与 `[overlay.events]` 是某个直播间第一次运行时的展示默认值；在 `/control` 保存后，数据库中的设置优先，因此更新 TOML 不会覆盖管理员已经调好的 OBS 样式。若希望重新采用 TOML 默认值，可删除该房间在 `overlay_settings` 表中的记录后重启。
+系统管理员可在 `/control/invitations` 创建和撤销邀请码。每个邀请码只能使用一次，并在创建时固定绑定一个尚未占用的 Bilibili `room_id`；注册者不能修改该房间，账户创建后房间绑定也不可更改。受邀用户打开注册链接，选择用户名、扫描自己的 TOTP 二维码并确认动态码即可完成注册。普通用户不能创建邀请码。
+
+每个用户在 `/control/` 配置自己的 CookieCloud 同步 UUID/Key 和密码，地址必须位于部署管理员配置的 `security.cookiecloud_allowed_hosts` 白名单。服务禁止 HTTP 重定向并安全编码 Key 路径，避免用户凭据导致服务端任意请求。服务会先验证凭据，再将敏感字段按用户独立加密保存；Cookie、Key 和明文密码不会返回浏览器，也不会与其他账户共享。CookieCloud 中需要存在 Bilibili `SESSDATA`。
+
+### 旧单用户配置迁移
+
+以下 TOML 段现在只用于第一次系统管理员初始化时的一次性兼容迁移：
+
+- `[connection].room_id`：绑定首个系统管理员的房间。
+- `[cookiecloud]`：导入首个系统管理员的用户级加密凭据。
+- `[obs].access_token`：导入首个默认弹幕组件的旧 OBS 令牌。
+- `[overlay]` 与 `[overlay.events]`：迁移旧 `overlay_settings`，没有旧记录时作为首个组件的回退值。
+
+迁移完成后，运行时以 PostgreSQL 中的用户、直播源、组件和凭据为准。以后修改这些旧段不会改变现有账户，也不会成为其他受邀用户的默认值；新用户使用邀请中绑定的房间，并在控制台填写自己的 CookieCloud。
+
+## 必须使用 HTTPS
+
+公开部署账号、TOTP 和会话功能时必须在 Nginx（或可信反向代理）终止 HTTPS，并保持 `security.secure_cookies = true`。下面是核心反代设置；证书路径按实际 Certbot 配置填写：
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 80;
+    server_name danmaku.luoxingci.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    http2 on;
+    server_name danmaku.luoxingci.com;
+
+    ssl_certificate     /etc/letsencrypt/live/danmaku.luoxingci.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/danmaku.luoxingci.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:9719;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+    }
+}
+```
+
+只有在本机、无敏感数据的纯 HTTP 开发环境中才能临时设置 `secure_cookies = false`。不要用该选项把登录页面直接发布到公网。
+
+## 控制台 PWA
+
+通过 HTTPS 打开 `/control/` 后，受支持的浏览器会在控制台顶部显示“安装到设备”。`/control` 会由服务端永久重定向到这个规范地址。安装后的应用使用独立窗口，并继续采用“用户名 + TOTP”登录；登录、注册与首次初始化在 PWA 内分别使用 `/control/login`、`/control/register` 和 `/control/setup`。原有 `/login`、`/register`、`/setup` 地址仍兼容普通浏览器书签。
+
+PWA 只控制 `/control/`，不会控制、缓存或刷新 `/obs/*` 浏览器源。离线缓存仅包含 React 应用外壳、本地图标和构建后带哈希的静态资源；账户、TOTP、邀请码、CookieCloud、组件设置、OBS 令牌、直播事件和所有 `/api/*` 响应始终在线直连且由服务端返回 `Cache-Control: no-store`。离线时写操作会在浏览器端直接拒绝，不会排队或在恢复网络后重放。
+
+部署新版本后，已打开的控制台会显示“更新可用”。更新不会自动接管或刷新页面，必须由用户点击确认；确认前请先保存设置以及只显示一次的邀请码、恢复码或刚轮换的 OBS 令牌。
+
+## 组件与 OBS 地址
+
+登录 `/control/` 后可以配置当前账户的直播源、管理组件、测试事件、调整弹幕样式，以及为每个组件单独生成或轮换只读 OBS 令牌。新的浏览器源地址格式是：
+
+```text
+https://danmaku.luoxingci.com/obs/<publicId>#token=<component-token>
+```
+
+`publicId` 是组件 UUID。`#token=...` 位于 URL fragment，不会随最初的 HTTP 请求发送到 Nginx；OBS 页面随后通过 WebSocket 的第一帧向 `/api/v1/components/<publicId>/stream` 完成认证。令牌只带 `events:subscribe` 权限，不能调用管理或写入接口；轮换后旧令牌立即失效。
+
+旧格式 `/obs?token=...` 与 `/ws?token=...` 已移除，避免 bearer token 进入 Nginx 访问日志。升级后请在控制台为组件轮换令牌，并把旧 OBS 源替换为上述新地址；旧令牌一旦轮换便立即失效。
+
+OBS 页面保持透明根背景，不使用固定 1920×1080 画布，并根据浏览器源的实际宽高自动适配。常用尺寸可从 `360×600`、`440×760` 或 `600×1080` 开始，也可以在 OBS 中自由拖拽缩放。
+
+## 弹幕姬展示
+
+每张消息卡片会从六套花纹组合中稳定选择一套，轮换使用对称花枝、横向自然藤纹和雏菊花簇，并改变上下、左右、镜像、配色与局部背景。连续的新卡避免使用相同款式，礼物连击更新保持原样式；透明消息墙本身不铺设全局装饰背景。粒子数量与速度、字号、事件类别、最大条数、自动收缩、卷轴展开时长、动效强度、低性能模式和礼物高亮阈值均可按组件在控制台调整，并实时推送给对应 OBS 源。
+
+花边 SVG 已本地打包，来源及公版/CC0 许可记录在 `apps/overlay/public/assets/NOTICE.md`，OBS 运行时不会访问素材站点。
+
+后端会为每个活动直播源缓存 Bilibili 礼物图片、GIF、币种和价格。目录刷新失败时保留上一次成功缓存；缺失条目会降级为直播事件自带的名称与价格。刷新间隔和请求超时可通过 `[gifts]` 调整。
+
+普通混排表情和整条大表情会作为安全的文字/图片分段推送。消息自带图片地址优先；服务还会使用该用户 CookieCloud 中的 `SESSDATA` 刷新对应直播间的表情目录，在消息只提供唯一标识时补齐图片。加载失败时前端退回原始表情文字，刷新参数可通过 `[emoticons]` 调整。