live-sfu-demo/design.md

架构设计规范 — SyncLive

SyncLive（同步直播，对标 SyncTV）的整体架构与模块划分说明。

分层架构

浏览器 (SolidJS SPA)
        │  HTTP / SSE / WebRTC (信令经服务端反代，媒体直连 SFU)
        ▼
控制面 (Go)
  ├─ gRPC + JSON 网关        # protobuf 定义的统一控制契约
  ├─ 鉴权 (Casbin RBAC + JWT) # 登录、权限校验、用户管理
  ├─ 房间拓扑 (roomHub)       # 内存态 + 嵌入式 libSQL 持久化
  └─ 媒体面反代 (httputil)    # SRS / Cloudflare 信令与 HLS 反代
        │
        ▼
媒体面 (SFU Provider 抽象)
  ├─ Cloudflare Realtime      # 主 SFU（托管，低延迟扇出）
  └─ SRS                      # 本地/对照 SFU（WHIP/WHEP + HLS/FLV 同出）

模块职责

• api/：protobuf 控制面契约（SyncLive 服务），单一事实来源，经 buf generate 生成 Go 代码到 gen/。
• internal/config/：运行参数与环境变量加载，含正式环境密钥校验（Validate）。
• internal/db/：嵌入式 libSQL 持久化（房间分发拓扑），仅 file:/:memory: 模式。
• internal/auth/：Casbin RBAC 模型与策略、JWT 签发校验、用户存储。
• internal/sfu/：SFU 后端 Provider 抽象（Cloudflare / SRS），统一 BackendInfo 与能力查询。
• internal/server/：HTTP/gRPC 服务装配、JSON 网关、房间与聊天 SSE（含 GET /api/rooms/events 全局房间 SSE 与 GET /api/room/{room}/events 单房间拓扑 SSE）、媒体反代、静态 UI 嵌入。
• cmd/server/：进程入口，装配配置、服务与优雅关闭。
• web/：前端单页应用（SolidJS + TanStack + Ark UI + Tailwind v4），构建产物由 Go embed 内联。

设计约束

• 控制面与媒体面分离：浏览器只与服务端交换 SDP/信令，SFU 凭证不出服务端。
• 多 SFU 后端可同时承载同一路发布（分流），拓扑由 WatchRoom / SSE 实时广播。
• 持久化默认嵌入式、零外部依赖；远程 libSQL 仅作可选项。
• 正式环境密钥必须显式配置，禁止内置弱密码与不安全默认密钥。