26 KiB

Raw Permalink Blame History

SyncLive 业务逻辑文档

版本：2026-08-22 · 基于 main 分支代码整理 · 对标 SyncTV 的直播分流姐妹项目

1. 项目定位

SyncLive = Sync + Live（一起播·一起看直播），对标 SyncTV（Sync + TV 一起看）。

一句话：一路推流，多端同步扇出。控制面 protobuf/gRPC，媒体面 WebRTC + HLS/FLV。
双 SFU 分流：同一路发布可同时落到 Cloudflare Realtime（主 SFU，托管扇出） 与 SRS（本地对照，WHIP/WHEP/HLS/FLV 三协议同出）。
设计约束：浏览器只与服务端交换 SDP/信令，SFU 凭证不出服务端；房间拓扑持久化到嵌入式 libSQL，无外部依赖即可开箱。

publisher ──WHIP/tracks.new──▶ Cloudflare Realtime ──▶ viewer(s)
          └────WHIP──────────▶ SRS ─┬─▶ WHEP  (0.2-0.5s 低延时)
                                   ├─▶ HLS   (5-10s，切片 /live/*.m3u8)
                                   └─▶ FLV   (http-flv)

2. 总体架构

浏览器 (SolidJS SPA, TanStack Router/Query, Ark UI, Tailwind v4)
   │ HTTP / SSE / WebRTC（信令经服务端反代，媒体直连 SFU）
   ▼
控制面 (Go, :8088 HTTP + :9090 gRPC)
   ├─ gRPC + JSON 网关 (protojson，见 api/sync_live.proto)
   ├─ 鉴权 (Casbin RBAC + JWT + UserStore)
   ├─ 房间拓扑 (roomHub 内存 + libSQL 持久化 stream_targets)
   ├─ 房间成员/权限/播放列表 (room.Service + room.Store)
   ├─ 聊天弹幕 (chatHub 内存广播 + 滑动窗口限流)
   └─ 媒体面反代 (httputil: /rtc/v1/* → SRS, /api/cf/* → Cloudflare, /live/* → SRS HLS)
   ▼
媒体面 (SFU Provider 抽象)
   ├─ Cloudflare Realtime Provider (REST Client + BackendInfo)
   └─ SRS Provider (WHIP/WHEP 信令 + HLS 静态资源)
   ▼
数据层
   ├─ libSQL 嵌入式 file:./data/sync-live.db (WAL)
   └─ data/users.json (用户库，bcrypt 哈希)

目录映射：

目录	职责
`api/sync_live.proto`	控制面唯一契约，经 `buf generate` 到 `gen/`
`internal/config`	环境变量加载 + `Validate()` 密钥校验 + `ProviderList()`
`internal/db`	嵌入式 libSQL 打开/迁移/CRUD (stream_targets, rooms_v2 等)
`internal/auth`	JWT 双令牌、用户文件存储、Casbin Enforcer、中间件
`internal/room`	房间/成员/角色/权限/播放列表的领域模型与存储
`internal/sfu/cloudflare`	Cloudflare Realtime REST 客户端
`internal/sfu/srs`	SRS Provider 元信息
`internal/server`	HTTP/gRPC 装配、网关、反代、SSE、聊天、Manage 面
`cmd/server`	进程入口与优雅关闭
`web/src`	SolidJS 前端，构建产物 `internal/server/static` 被 Go embed
`deploy`	`docker-compose.yml` + `srs.conf`

3. 技术栈

后端：Go 1.25, google.golang.org/grpc + protobuf, casbin/casbin/v2, golang-jwt/jwt/v5, tursodatabase/go-libsql, golang.org/x/crypto/bcrypt
前端：SolidJS + TanStack Router/Query/Virtual + Ark UI + Tailwind v4 + Vite + hls.js + lucide-solid + playwright (截图)
SFU：Cloudflare Realtime (rtc.live.cloudflare.com/v1), SRS 6 (:1935/:1985/:8080/:8000)
持久化：libSQL file 模式，MaxOpenConns=1，WAL

4. 核心业务模块

4.1 房间 (Room)

模型 internal/room/room.go：

字段	含义
`name`	主键，URL `?room=` 指定的房间名
`display_name/description`	展示用
`creator`	创建者 username
`status`	`active / closed / banned`，状态机 `CanTransitionTo`
`is_public`	是否公开可发现
`password_hash`	可选房间密码 (bcrypt)
`require_approval`	入房需审批 → 成员 `pending`
`max_members`	上限默认 100
`settings_json`	`RoomSettings` JSON，含细粒度权限覆盖
`auto_play`	`enabled/mode/delay`，`sequential/repeat_one/repeat_all/shuffle`
`category_id/cover_file_id/label_ids`	分类/标签/封面 (兼容 SyncTV)

房间服务 internal/room/service.go：

CreateRoom：建 rooms_v2 + 写入 creator 为 RoleCreator 的成员记录
JoinRoom：校验 banned/closed、密码、人数上限、重复加入、封禁；require_approval=true 时置 MemberPending
EnsurePermission/CheckPermission：按 RoomSettings 与成员 PermissionSet 判定单项权限；closed/banned 房间仅允许 view_members/view_chat_history
UpdateMemberRole/Kick/Ban/Leave/ApproveJoin/RejectJoin/TransferOwnership：均校验 PermManageMembers/PermRemoveMembers 与 Role.CanManage 等级

成员模型 internal/room/member.go + role.go：

角色 RoleCreator(1) > RoleAdmin(2) > RoleMember(3) > RoleGuest(4)，Rank() 分 100/80/50/10
状态 MemberActive / Banned / Pending / Kicked
权限位 PermissionSet uint64，在 added/removed/admin_added/admin_removed 四列上做增量覆盖

4.2 鉴权与 RBAC (Auth)

用户存储 internal/auth/store.go + data/users.json：

文件锁 + 内存 map，Create 时 bcrypt 哈希、Verify 比对
BootstrapAdmin：用户库为空且 BOOTSTRAP_ADMIN_USER/PASS 已设时创建首个 admin（可选 BOOTSTRAP_ADMIN_ROLE=root 提升为 super admin）
字段：username / hash / role / status(active|banned) / created_at

JWT internal/auth/jwt.go：

JWTManager{secret, ttl=2h, refreshTTL=7d, issuer="sync-live"}，HS256
Sign(username, role) → access token (TokenType=access)；SignRefresh → refresh token
Verify / VerifyRefresh / IssuePair / Refresh；Validate() 要求 JWT_SECRET 非空，否则拒绝启动

Casbin internal/auth/model.conf + policy.csv + enforcer.go：

模型：r=sub,obj,act | p=sub,obj,act | g=_,_ | e=some(p.eft==allow) | m=g(r.sub,p.sub) && r.obj==p.obj && r.act==p.act
策略表（节选）：
- root/admin/publisher/viewer/guest 五档，guest 仅 config:read + srs:streams + room:chat
- viewer 可 room:subscribe/watch/chat
- publisher 可 room:publish/stop
- admin/root 可 room:manage + user:list/manage + system:manage
Enforcer.AddUserRole 在登录/改角色时同步 g 关系

中间件 internal/auth/middleware.go：

从 Authorization: Bearer / Cookie(token|access_token|refresh_token) / ?token= 提取 token
注入 context.Context 的 AuthedUser{Username, Role, Token}
AuthorizeMiddleware(obj, act, needAuth)：guest 放行 config:read + srs:streams + room:chat，其余走 Enforce

4.3 房间分发拓扑 (roomHub + stream_targets)

内存 Hub internal/server/rooms.go：

roomHub{rooms map[name]*roomEntry, db *sql.DB}，roomEntry{targets map[backend]*StreamTarget, subs map[chan]struct{}}
setTarget(room, backend, target)：写入内存 → broadcast(room) → 异步 db.SaveTarget
removeTarget：删 backend，空房间且无订阅者则删 entry + db.DeleteTarget
subscribe(room)：每房间 8 缓冲 channel，broadcast 非阻塞 fan-out
broadcastEvent(room, type, payload)：复用同一订阅通道，以 {"type": "...", "payload": ...} 信封推送 playlist_update / playback 等通用事件
newRoomHubWithDB 启动时 db.LoadAll 恢复全量房间

持久化 internal/db/db.go：

Open(dsn) 仅允许 file: / :memory:，自动 MkdirAll + Migrate
表：
- stream_targets(room, backend PK, session_id, stream, publish_token, url, published_at) + idx_room
- rooms(name PK, created_at, updated_at) (轻量索引)
- rooms_v2 / room_members / room_bans / room_join_requests / room_categories / room_labels / user_bans / user_registration_requests
SaveTarget = INSERT OR REPLACE + 维护 rooms 占位；DeleteTarget 空房间时删 rooms

控制面 API internal/server/service.go + gateway.go：

GetConfig：按 SFU_PROVIDER 顺序组 BackendInfo[] + candidate + token_required
Publish(room, backend, identity)：
- cloudflare：CreateSession(room) → GetSession → target{session_id}；未配置时直接报错
- srs：stream=live-<room> + signStreamToken(secret, stream, identity, "publish", 2h) → target{stream, publish_token, url=/rtc/v1/whep/?app=live&stream=...}
- 统一 hub.setTarget 并广播
Subscribe(room, backend)：
- cloudflare：新建 viewer session，返回 session_id + publisher_session_id + ice_servers
- srs：返回 stream + ice_servers(stun)，观看侧 WHEP 与 HLS 共用同一 stream
StopStream(room, backend)：cloudflare 删发布 session + hub.removeTarget
WatchRoom (gRPC stream) / GET /api/room/{room}/events (SSE)：首包即时推送 targets，后续 fan-out + 20s 心跳全量重推
handleRoomsQuery GET /api/rooms/query：支持 page/page_size/search/status/creator/is_public/sort_by/sort_direction，优先走 room.Store.QueryRooms (DB)，否则回退内存 hub

4.4 媒体面反代与 SFU

SRS internal/server/proxy.go + deploy/srs.conf：

srsProxyHandler：SRS_API_BASE (默认 :1985) 的 WHIP/WHEP 信令反代；SFU_TOKEN_REQUIRED=1 时校验 ?token= 为 role=publish 且 room 一致的 HS256 JWT
srsHlsProxyHandler：SRS_HTTP_BASE (默认 :8080) 的 HLS/FLV 静态切片反代，挂 GET/HEAD /live/，自动补 CORS Allow-Origin: *，OPTIONS 204
SRS 配置：http_server :8080 切片落盘 objs/nginx/html，http_api :1985 信令，rtc_server :8000 媒体，vhost __defaultVhost__ { rtc + http_remux(flv) + hls(fragment 10s, window 60s) }

Cloudflare internal/sfu/cloudflare/client.go + provider.go：

Provider{client, appID, stun, configured}，BackendInfo{kind=CLOUDFLARE, name="Cloudflare Realtime", configured, primary=true}
cfProxyHandler：将 /api/cf/* 转 CF_BASE_URL/apps/<CF_APP_ID>/*，注入 Authorization: Bearer CF_APP_SECRET，浏览器只做 tracks/new SDP 交换

前端媒体链路：

推流：RTCPeerConnection → createOffer → POST /rtc/v1/whip/?app=live&stream=live-<room>&token=... (信令经网关) → setRemoteDescription(answer)，成功后展示 hlsUrl=/live/<stream>.m3u8 + flvUrl
观看：
- WHEP：POST /rtc/v1/whep/?app=live&stream=... 同流程，ontrack → <video>
- HLS：video.canPlayType('application/vnd.apple.mpegurl') 走原生，否则 hls.js loadSource/attachMedia；观看页三档切 cloudflare / srs(whep) / srs-hls

4.5 聊天弹幕

hub internal/server/chat.go：

chatMessage{id, room, user, role, message, color, host, ts}；chatHub{rooms map[room]map[chan]struct{}, recentMsgs map[room][]*chatMessage}，recentLimit=50
subscribe(room) 16 缓冲；broadcast 进 recentMsgs 并裁剪；recent(room) 快照回放
空房间无订阅者时清 recentMsgs，防内存无界
GET /api/room/{room}/chat (SSE)：进场回放 recent + 25s ping；POST /api/room/{room}/chat 与 POST /api/room/{room}/broadcast (主播专用，host=true) 均经 chatHub.broadcast
限流 chatRateLimiter(limit=5, window=3s)，key=room/user/ip (broadcast 另缀 /broadcast/)，滑动窗口 + 分钟级 cleanup
clientIP 取 X-Forwarded-For[0] / X-Real-IP / RemoteAddr

权限：POST /chat 需 room:chat (guest 亦可)；POST /broadcast 需 room:publish (publisher/admin)，走 authWrap(..., needAuth=true)

4.6 播放列表与同步播放

internal/server/playlist.go + internal/room/playlist.go：

PlaylistItem{room, url, title, added_by}，PlaybackState{room, position, playing, rate, current_item, updated_by}
GET /api/room/{room}/playlist 列件；POST (需 PermControlStream) 增件并 broadcastEvent("playlist_update", items)；DELETE ?id= 删件同广播
GET /api/room/{room}/playback 读状态（无则 rate=1）；POST/PUT 需 PermControlStream，rate<=0 归一，落库后 broadcastEvent("playback", ps)，观看端经同一 SSE 连接按 event: playlist_update / playback 分发

4.7 房间内权限位

internal/room/permission.go：

16 项：send_chat / view_chat_history / view_members / subscribe / watch_room / publish / stop_stream / broadcast / manage_members / add_members / remove_members / manage_permissions / manage_room / delete_room / delete_chat_messages / control_stream
PermissionSet uint64 位集，Grant/Revoke/Has/Names
默认集：
- PermDefaultCreator = All
- PermDefaultAdmin = 除 delete_room 外大部分
- PermDefaultMember = chat/view/subscribe/watch/publish/stop
- PermDefaultGuest = view_chat/view_members/subscribe/watch；PermGuestAssignable = Guest + send_chat
RoomSettings.Admin/Member/GuestPermissions() 在 Default* 上叠加 added/removed 增量

4.8 管理后台 (Manage)

internal/server/manage.go 挂于 /api/manage/*，均 authWrap(needAuth=true)：

GET /api/manage/overview：汇总计数
GET/POST /api/manage/rooms：列/建房间（含 is_public/require_approval/max_members/password/display_name/description）
GET/PUT/PATCH/DELETE /api/manage/rooms/{room}：详情/改设置/删房
GET/POST /api/manage/rooms/{room}/members、PUT/DELETE .../members/{user}、POST .../perms、POST .../approve|reject、POST .../transfer：成员增删改、权限覆盖、审批、转让房主 (RoleCreator 互转)
GET /api/manage/permissions[/{room}]：权限矩阵
GET/PUT /api/manage/rooms/{room}/settings、POST .../join|leave：房间设置与自助进出

5. 关键流程时序

5.1 登录 / 注册 / 鉴权

POST /api/auth/login|register {username,password,role?} → UserStore.Verify/Create → JWT.Sign → Set-Cookie: token=... HttpOnly + {token,user,expires_at}
后续请求带 Cookie 或 Authorization: Bearer，AuthorizeMiddleware → JWT.Verify → 注入 AuthedUser → Enforcer.Enforce(sub,obj,act)
POST /api/auth/refresh 用 refresh_token 换新 access；GET /api/auth/me 返回当前用户与 expires_at/issued_at
未登录 guest 默认仅 config:read 与 srs:streams 与 room:chat 放行，其余 401/403

5.2 房间生命周期

POST /api/rooms {name} 或 POST /api/manage/rooms → hub.createRoom (内存占位)；若走 room.Service.CreateRoom 则同时落 rooms_v2 + room_members(creator)
GET /api/rooms | GET /api/rooms/query?... 分页查；GET /api/manage/rooms/{room} 看成员与 targets(live)；GET /live/*.m3u8 经网关拉 HLS 无需订阅
转让：POST /api/manage/rooms/{room}/transfer {target} 需当前 RoleCreator，事务内改 rooms_v2.creator 并互换 creator↔admin 角色
关闭/封禁：RoomStatus 流转 active↔closed/banned，EnsurePermission 据此限权

5.3 发布 (Publish)

前端 → POST /api/publish {room, backend} (需 room:publish)
     → Service.Publish 按 backend 分流
       ├─ cloudflare: CreateSession(room) → target{session_id}
       └─ srs: stream=live-<room>, token=HS256(room,identity,publish,2h) → target{stream,token,url}
     → hub.setTarget(room, backend, target) → SSE 广播 RoomEvent{targets}
     → 返回 {session_id/stream/publish_token/ice_servers/target}
前端 → RTCPeerConnection offer → POST /rtc/v1/whip/?app=live&stream=...&token=... (SRS 反代校验) 或 POST /api/cf/.../tracks/new (CF 反代注入 Bearer)
     → setRemoteDescription(answer) → 推流成功，展示 HLS/FLV 链接

5.4 订阅 / 观看

前端 → POST /api/subscribe {room, backend} (需 room:subscribe)
     → hub.findTarget(room, backend) 取发布侧 target
       ├─ cloudflare: CreateSession(room) viewer → {session_id, publisher_session_id, ice_servers}
       └─ srs: {stream, ice_servers}
前端 → 按 backends[].configured 展示线路，未配置标「未配置」
     ├─ cloudflare: tracks/new location=remote
     ├─ srs-whep: POST /rtc/v1/whep/?app=live&stream=live-<room> → ontrack
     └─ srs-hls:  GET /live/live-<room>.m3u8 → hls.js / 原生
     → 同时订阅 GET /api/room/{room}/events (SSE) + GET /api/room/{room}/chat (SSE)，拓扑/弹幕/播放状态同链路按 event type 分发

5.5 弹幕与主播广播

观众 POST /api/room/{room}/chat {message,color} (room:chat)
  → 取身份 user/role/id (guest 可发)
  → chatRL.allow(room/user/ip, 5/3s) 限流
  → chatHub.broadcast → SSE fan-out (event: chat) → 前端 danmaku 叠加

主播 POST /api/room/{room}/broadcast {message,color} (room:publish, 需 Bearer)
  → 同限流 key=room/broadcast/user/ip
  → chatMessage{host:true} → 同一 hub 广播，观众/主播端同可见

5.6 停止

POST /api/stop {room, backend} (room:stop) → cloudflare 删 session_id + hub.removeTarget(room, backend) → 广播空 targets → 前端自动切离或提示下播

6. 数据模型与契约

6.1 Protobuf 契约 `api/sync_live.proto`

服务 SyncLive：GetConfig / ListRooms / Publish / Subscribe / StopStream / WatchRoom(stream) / Login / Register / GetMe / ListUsers / UpdateUserRole
枚举 BackendKind: UNSPECIFIED(0) / CLOUDFLARE(1) / SRS(2)
消息：BackendInfo{kind,name,configured,primary}, IceServer{urls,username,credential}, StreamTarget{backend,session_id,stream,publish_token,url,published_at}, Room{name,targets[]}, RoomEvent{room,targets[]}, UserInfo{username,role,created_at}, Login/Register/GetMe/ListUsers/UpdateUserRole 族

6.2 libSQL 表

stream_targets：房间分发的事实表，PRIMARY KEY(room,backend)
rooms / rooms_v2：rooms 为轻量拓扑索引，rooms_v2 为完整房间档案（含 settings_json）
room_members(room,user_id PK, username, role, status, added/removed/admin_added/admin_removed, joined_at, version) + 两索引
room_bans / room_join_requests / room_categories / room_labels / user_bans / user_registration_requests
增量兼容：启动时 ALTER TABLE rooms_v2 ADD COLUMN category_id/cover_file_id/label_ids 忽略已存在错误

6.3 用户库 `data/users.json`

map[username]*User{username, hash(bcrypt), role, status, created_at}，文件锁读写，BOOTSTRAP_ADMIN_* 冷启动种子

7. API 清单

7.1 JSON 网关 (同 HTTP 端口，protojson)

方法	路径	鉴权	说明
GET	`/api/config`	`config:read` guest可	后端能力与 `candidate/token_required`
GET	`/api/rooms`	`room:list`	全量房间 (hub)
GET	`/api/rooms/query?...`	`room:list`	分页查询 (DB 优先)
GET	`/api/rooms/events`	`room:list` SSE	全局房间变更（create/update/delete/sync，`event: rooms`），供 /rooms 实时刷新
POST	`/api/rooms`	`room:list`	创建占位
POST	`/api/publish`	`room:publish`	发布 (多后端)
POST	`/api/subscribe`	`room:subscribe`	订阅
POST	`/api/stop`	`room:stop`	下播
GET	`/api/srs/streams`	`srs:streams` guest可	代理 `SRS :1985 /api/v1/streams/`
GET	`/api/room/{room}/events`	`room:watch` SSE	房间拓扑
GET	`/api/room/{room}/playlist`	`room:watch`	列播放列表
POST	`/api/room/{room}/playlist`	`room:watch` + `control_stream`	增件
DELETE	`/api/room/{room}/playlist?id=`	同上	删件
GET	`/api/room/{room}/playback`	`room:watch`	读同步状态
POST/PUT	`/api/room/{room}/playback`	同上	写同步状态
GET	`/api/room/{room}/chat`	`room:chat` SSE guest可	弹幕订阅 + recent 回放
POST	`/api/room/{room}/chat`	`room:chat` guest可	发弹幕
POST	`/api/room/{room}/broadcast`	`room:publish`	主播广播 (`host:true`)

7.2 认证

方法	路径	说明
POST	`/api/auth/login`	登录，签 access+refresh，种 HttpOnly Cookie
POST	`/api/auth/register`	注册，`ALLOW_REGISTER=1` 时放行，`admin/publisher` 需 admin 授权否则降为 viewer
POST	`/api/auth/logout`	清 Cookie
POST	`/api/auth/refresh`	用 refresh 换 access
GET	`/api/auth/me`	当前用户
GET	`/api/auth/users`	列用户 (admin)
POST	`/api/auth/users/role`	改角色 (`only root can grant root`, admin 不能提权他人为 admin/root)
POST	`/api/auth/users/ban	unban`
GET	`/api/auth/check`	前端权限探针

7.3 管理面 `/api/manage/*`

见 4.8 节，覆盖 overview/rooms/rooms/{room}/members/permissions/settings/join/leave/transfer 全链路。

7.4 媒体反代

方法	路径	目标	说明
ANY	`/rtc/v1/*`	`SRS_API_BASE (:1985)`	WHIP/WHEP 信令，可选 `?token` 校验
ANY	`/api/cf/*`	`CF_BASE_URL/apps/<CF_APP_ID>/*`	Cloudflare Realtime，注 Bearer
GET/HEAD	`/live/*`	`SRS_HTTP_BASE (:8080)`	HLS/FLV 切片，补 CORS

7.5 gRPC `:9090`

同 SyncLive 服务，UnaryAuthInterceptor + StreamAuthInterceptor 校验 room/user/config/srs/system 等 obj:act。

8. 权限矩阵

8.1 全局 Casbin (policy.csv)

角色	能力
`root`	全量：`config:read, room:list/publish/subscribe/stop/watch/chat/manage/delete, user:list/manage, srs:streams, system:manage`
`admin`	除 `system:manage/room:delete` 外全量
`publisher`	`config:read + room:list/publish/subscribe/stop/watch/chat + srs:streams`
`viewer`	`config:read + room:list/subscribe/watch/chat + srs:streams`
`guest`	`config:read + srs:streams + room:chat` (弹幕可发，拉流只看 HLS)

8.2 房间内位权限 (PermissionSet)

见 4.7 表，房间设置可在默认集上按 admin/member/guest 三档增删位，且受 Role.CanManage 等级约束。关键校验入口 room.Service.EnsurePermission。

9. 配置与部署

9.1 环境变量 (env > 默认)

变量	默认	说明
`HTTP_PORT/GRPC_PORT`	`8088/9090`	控制面端口
`JWT_SECRET`	(必填)	正式环境必须显式配置，否则 `Validate` 拒绝启动
`SFU_TOKEN_SECRET`	同 JWT	推流 JWT 密钥，空则复用 JWT
`SFU_TOKEN_REQUIRED`	`0`	`1` 时 WHIP 强制 `?token` 校验
`SFU_PROVIDER`	`cloudflare,srs`	后端顺序
`SRS_API_BASE/SRS_HTTP_BASE/SRS_APP/SRS_CANDIDATE`	`http://localhost:1985 / :8080 / live / 127.0.0.1`	SRS 链路
`CF_APP_ID/CF_APP_SECRET/CF_BASE_URL/CF_STUN_URL`	(空) / `https://rtc.live.cloudflare.com/v1` / `stun:stun.cloudflare.com:3478`	Cloudflare 链路
`TURSO_DATABASE_URL/DATABASE_URL`	`file:./data/sync-live.db?cache=shared&_journal_mode=WAL`	仅 file/`:memory:`，拒 `libsql://`
`AUTH_USER_FILE/CASBIN_MODEL/CASBIN_POLICY`	`data/users.json / internal/auth/model.conf / policy.csv`	认证文件
`ALLOW_REGISTER`	`1`	是否开放注册
`BOOTSTRAP_ADMIN_USER/PASS/ROLE`	(空)	冷启动种子，仅空库生效
`SMTP_/EMAIL_VERIFY_/OAUTH_*/AUTHBOSS_ENABLED`	(多为 `0`/空)	邮件/验证/OAuth 预留开关

9.2 本地启动

cp .env.example .env  # 填 JWT_SECRET 等
cd deploy && SRS_CANDIDATE=127.0.0.1 docker compose up -d srs
go run ./cmd/server               # http://localhost:8088  /publish?room=xxx /watch?room=xxx /login /manage
# 前端热更新
cd web && pnpm i && pnpm dev      # :5173
pnpm build                         # 产到 internal/server/static (Go embed)

9.3 SRS 部署要点

http_server :8080 切片目录与 hls_path 一致；hls_fragment 10 / window 60；公网部署 SRS_CANDIDATE=公网IP 并重建容器
生产可不暴露 8080，仅保留 1985/8000，前端统一经 8088 /live/* 拉流
HLS 首屏 10-20s，重试 curl /live/<stream>.m3u8 与 docker exec ls objs/nginx/html/live 排障

10. 前端

路由 web/src/app/router.tsx：TanStack Router + RootRoute(Layout) + lazy(code-split)，路由 / /publish?room= /watch?room= /room?room= /rooms /users /manage /login，均为 SPA 回退 index.html
状态：TanStack Query 封装 api.ts 的 fetch /api/* (protojson)；SSE 封装 sse.ts/chat.ts，GET /api/room/{room}/events 与 /chat 并行订阅，按 event: room/chat/playlist_update/playback 分发
媒体：webrtc.ts 封装 WHIP/WHEP 的 RTCPeerConnection 流程，hls.ts 封装 hls.js 回退
组件：components/danmaku.tsx 叠加层，components/manage/* 管理后台分 Overview/Rooms/Permissions/System/UsersInline
构建：vite.config.ts 输出 ../internal/server/static，internal/server/server.go:embed static 内联，GET / /publish /watch /login /manage 均回 static/index.html

11. 安全与限流

正式环境密钥强校验：缺 JWT_SECRET 或 SFU_TOKEN_REQUIRED 却无 SFU_TOKEN_SECRET 直接退错
密码：用户 bcrypt，房间密码 bcrypt (HashRoomPassword)
推流 token：token.go 自实现 HS256(b64url header + payload).hmacSHA256(secret)，{room,identity,role,iat,exp}，TTL 2h
弹幕限流：每 room/user/ip 5 条 / 3s 滑动窗口，超限 429，后台分钟级清过期 key；单条 500 字符截断
鉴权覆盖：HTTP authWrap 与 gRPC Unary/StreamInterceptor 双轨，guest 白名单最小化

12. 关联文档与验证

推流链路详述：docs/streaming-pipeline.md（含 SRS srs.conf 全量、反代代码、前端 publishSRS/watchSRS/watchHLS 选型表与 curl/ffplay 验证步骤）
架构分层：design.md
协议契约：api/sync_live.proto + buf.gen.yaml
快速验证：发布页推流后 curl -i http://localhost:8088/live/live-demo.m3u8 / curl -I .../live-demo.flv / ffplay ...，SRS 日志与切片目录联合排障

维护提示：新增后端或房间字段时，同步更新 api/*.proto → gen/、internal/db.Migrate / room.Store.InitSchema、policy.csv 与本文件对应小节；房间拓扑的持久化与 SSE 广播是分流可见性的核心链路，改动前优先补 grpc_test.go / auth_test.go 用例。

26 KiB Raw Permalink Blame History Unescape Escape