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。

部署

先复制配置并生成独立密钥：

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

Compose 将 config.toml 只读挂载到 /app/config.toml，应用通过 --config 读取它。容器使用 host 网络，默认只在 127.0.0.1:9719 监听，供同机 Nginx 访问；不要把 9719 直接暴露到公网。

容器默认以 1000:1000 非 root 身份、只读根文件系统运行，并丢弃全部 Linux capabilities。请将 config.toml 设为 chmod 600，并确保容器用户可读；如宿主机用户不是 1000:1000，启动前设置 APP_UID 与 APP_GID。

[database].url 指向 PostgreSQL。应用启动时自动执行版本化迁移，数据库保存账户、一次性邀请码、TOTP 注册状态、可撤销会话、恢复码摘要、用户直播源、组件设置、OBS 令牌摘要和审计记录。租户表同时使用 owner 复合外键与 PostgreSQL RLS 约束，HTTP API 也始终从当前会话取得 owner，客户端不能自行指定其他用户。

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

首次初始化与登录

首次部署且数据库中尚无账户时，打开：

https://danmaku.luoxingci.com/control/setup

填写系统管理员用户名和 config.toml 中的 admin.password，扫描页面生成的 TOTP 二维码，再输入验证器中的 6 位动态码完成初始化。页面只显示一次恢复码，请立即离线保存。

admin.password 只是“允许创建第一个系统管理员”的一次性 bootstrap proof：

它不会保存为账户密码，也不能用于日常登录。
第一个账户创建后，bootstrap 接口永久拒绝再次初始化。
所有账户都是 passwordless 账户，以“用户名 + TOTP”登录；丢失验证器时可使用一次性恢复码。
会话使用随机令牌，数据库只保存摘要，可在服务端到期或撤销。

系统管理员可在 /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 配置填写：

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 地址

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] 调整。

README.md Unescape Escape

洛星瓷直播组件服务

后端结构

部署