房间系统

Monibuca V6 的房间系统由四部分组成：

1. Room 服务（引擎内置）— 提供房间核心生命周期管理
2. Live 插件 — 直播间扩展功能
3. Meeting 插件 — 会议室扩展功能
4. CustomerService 插件 — 1v1 客服通话功能

Room 是内置服务，不是插件

Room 服务直接集成在引擎内部（src/room/），通过 room feature 条件编译启用。它不实现 Plugin trait，而是由引擎直接管理其初始化和生命周期。Live、Meeting 和 CustomerService 作为独立插件，通过 RoomApi trait 向 Room 服务注册异步回调（RoomCallbacks）。

启用方式

# 启用 Room 服务（必须）
# room feature 在 Cargo.toml 中以条件编译的方式启用

# 启用直播间插件
features = ["live"]

# 启用会议室插件
features = ["meeting"]

# 启用客服通话插件
features = ["customer-service"]

# 同时启用
features = ["live", "meeting", "customer-service"]

架构设计

graph TB
    subgraph RS["Room Service (引擎内置)"]
        Core["房间创建/销毁/加入/离开<br/>WebSocket/心跳/鉴权/上报"]
        API["RoomApi trait + ExtensionManager<br/>插件注册 RoomCallbacks 异步回调<br/>插件操作房间: 广播/锁定/静音/踢人/封禁/大厅"]
    end

    subgraph Plugins["插件扩展"]
        Live["LiveExtension (直播间)<br/>manages_own_sessions: true"]
        Meeting["MeetingExtension (会议室)<br/>manages_own_sessions: false"]
    end

    Core --> API
    API --> Live
    API --> Meeting
    API --> CS["CustomerServiceExtension (客服通话)<br/>manages_own_sessions: true<br/>max_users: 2"]
    API --> CS["CustomerServiceExtension (客服通话)<br/>manages_own_sessions: true<br/>max_users: 2"]
    Live -->|"room_api.broadcast_to_room()<br/>room_api.add_ban()<br/>room_api.remove_user()"| RS
    Meeting -->|"room_api.set_room_locked()<br/>room_api.set_lobby_enabled()<br/>room_api.admit_user()"| RS
    CS -->|"room_api.broadcast_to_room()<br/>room_api.remove_user()"| RS

Room 服务核心功能

• 房间的创建、加入、离开、销毁
• 用户管理与鉴权（外部 HTTP 验证）
• WebSocket 连接管理与实时信令
• 心跳检测（超时自动踢出）
• 聊天速率限制
• 行为上报与统计

RoomApi — 插件与引擎的唯一契约

插件通过 EngineContext.room_api() 获取 Arc<dyn RoomApi>，用于：

注册回调（在 init() 时）：

• register_callbacks(RoomType::Live, RoomCallbacks { ... })
• 回调在房间生命周期事件发生时被引擎异步调用

操作房间（在回调或 HTTP handler 中）：

• broadcast_to_room() — 广播消息
• set_room_locked() / set_room_recording() — 房间状态
• remove_user() — 踢人
• add_ban() / remove_ban() — 封禁
• add_chat_mute() / remove_chat_mute() — 聊天静音
• set_lobby_enabled() / admit_user() / reject_user() — 等候室

WebSocket 连接

客户端通过 WebSocket 连接到房间服务，进行实时信令通信：

ws://host:port/room/{room_id}?token={auth_token}

WebSocket 消息采用 JSON 格式，通过 action 字段区分消息类型：

{
  "action": "join_room",
  "room_id": "100001",
  "user_id": "user_001",
  "user_name": "张三"
}

通用信令

Action	方向	说明
join_room	C→S	加入房间
leave_room	C→S	离开房间
heartbeat	C→S	心跳保活
chat	C→S	聊天消息（经速率限制后广播）
action	C→S	权限操作（锁定、录制、踢人等）
media_state	C→S	更新媒体状态
user_joined	S→C	有用户加入房间
user_left	S→C	有用户离开房间
room_closed	S→C	房间已关闭
error	S→C	错误通知

未匹配的消息类型会透传到 ExtensionManager，由插件注册的 on_message 回调处理。

消息处理时序

sequenceDiagram
    participant C as Client
    participant H as RoomWsHandler
    participant RS as RoomService
    participant EM as ExtensionManager
    participant Ext as Plugin Extension

    C->>H: ws: { action, room_id, ... }

    alt action = "join"
        H->>RS: verify_user()
        RS-->>H: ok
        H->>RS: Room.add_user()
        H->>EM: on_user_join callback
    else action = "leave"
        H->>EM: on_user_leave callback
        H->>RS: Room.remove_user()
    else action = "chat"
        H->>RS: rate_limit → Room.broadcast_text()
    else action = "action"
        H->>H: permission check → ActionExecutor
    else other (custom)
        H->>EM: on_message callback
        EM->>Ext: plugin parses as LiveEvent / MeetingEvent
    end

---

直播间插件（Live）

Live 插件为直播场景提供丰富的互动功能。

功能列表

• 直播间生命周期：准备中（Preparing）→ 直播中（Living）→ 暂停（Paused）→ 结束（Ended）
• 连麦系统：支持主播与观众连麦互动
• 礼物系统：礼物发送、连击（Combo）支持，通过 RoomApi.broadcast_to_room() 广播
• PK 对战：主播间 PK 对战功能
• 机器人观众：模拟观众（用于测试）
• 数据持久化：直播间数据存储到数据库
• 管控能力：通过 RoomApi 实现踢人、封禁、聊天静音

直播间信令

Action	方向	说明
start_live	C→S	开始直播
stop_live	C→S	结束直播
pause_live	C→S	暂停直播
resume_live	C→S	恢复直播
send_gift	C→S	发送礼物
gift_received	S→C	礼物通知（广播）
send_danmaku	C→S	发送弹幕
link_mic_request	C→S	申请连麦
link_mic_accept	C→S	接受连麦
link_mic_reject	C→S	拒绝连麦
link_mic_end	C→S	结束连麦
pk_invite	C→S	发起 PK 邀请
pk_accept	C→S	接受 PK
pk_end	C→S	结束 PK

礼物系统

{
  "action": "send_gift",
  "room_id": "100001",
  "gift_id": "rocket",
  "count": 1,
  "combo_id": "combo_abc123"
}

礼物支持连击（Combo），客户端在短时间内多次发送同一礼物时使用相同的 combo_id，服务端会累计连击次数并通过 RoomApi.broadcast_to_room() 广播。

配置

live:
  gift:
    combo_timeout: 5            # 连击超时时间（秒）
    max_combo_count: 999        # 最大连击次数
  link_mic:
    max_participants: 6         # 最大连麦人数
    timeout: 30                 # 连麦邀请超时（秒）

---

会议室插件（Meeting）

Meeting 插件为视频会议场景提供完整的会议管理功能。

功能列表

• 议程管理：会议议程的创建和控制
• 计时器：会议和发言计时
• 实时转写：语音转文字（需外部 ASR 服务）
• AI 会议总结：自动生成会议纪要
• 任务提取：从会议内容中提取待办任务
• 录制控制：通过 RoomApi.set_room_recording() 控制录制
• 等候室（Lobby）：通过 RoomApi.set_lobby_enabled() + admit_user() / reject_user() 管理

会议室信令

Action	方向	说明
start_meeting	C→S	开始会议
end_meeting	C→S	结束会议
mute_participant	C→S	静音参与者（通过 RoomApi）
unmute_participant	C→S	取消静音
kick_participant	C→S	踢出参与者（通过 RoomApi）
raise_hand	C→S	举手
lower_hand	C→S	放下手
start_recording	C→S	开始录制（通过 RoomApi）
stop_recording	C→S	停止录制
start_transcription	C→S	开始转写
share_screen	C→S	共享屏幕
lock_room	C→S	锁定/解锁房间（通过 RoomApi）
toggle_lobby	C→S	开关等候室（通过 RoomApi）
admit_user	C→S	允许进入（通过 RoomApi）
reject_user	C→S	拒绝进入（通过 RoomApi）
ban_user	C→S	封禁用户（通过 RoomApi）
participant_muted	S→C	参与者被静音通知
participant_kicked	S→C	参与者被踢出通知
transcription_result	S→C	转写结果推送

参会者控制

主持人（Host）拥有完整控制权限：

{
  "action": "mute_participant",
  "room_id": "meeting_001",
  "target_user_id": "user_005",
  "mute_audio": true,
  "mute_video": false
}

配置

meeting:
  max_participants: 50          # 最大参会人数
  enable_lobby: true            # 启用等候室
  enable_recording: true        # 允许录制
  enable_transcription: false   # 启用转写
  timer:
    max_duration: 7200          # 会议最大时长（秒）
    warning_before_end: 300     # 结束前 N 秒提醒

---

客服通话插件（CustomerService）

CustomerService 插件为 1v1 客服通话场景提供专业支持。

功能列表

• 1v1 通话：每个会话固定 2 人（客服 + 用户），max_users: 2
• 会话管理：创建、分配坐席、关闭、统计
• 免登录用户端：用户通过链接直接进入，无需注册
• 音频混音：客服端可混入本地音频文件（背景音乐、提示音）
• 满意度评价：通话结束后用户可进行星级评价

客服通话信令

Action	方向	说明
accept_call	C→S	客服接受通话
end_call	C→S	挂断通话
transfer_call	C→S	转接至其他坐席
hold_call	C→S	保持通话
resume_call	C→S	恢复通话
call_accepted	S→C	通话已被接听
call_ended	S→C	通话已结束
call_transferred	S→C	通话已转接

配置

customer_service:
  max_sessions: 1000          # 最大并发会话数
  session_timeout: 3600       # 会话超时时间（秒）
  enable_recording: false     # 启用通话录制

详细的 HTTP API 接口说明请参考 客服通话 API。 完整的功能说明请参考 客服通话插件。

---

上报与统计

Room 服务内置了完整的三级上报系统，自动采集房间内的音视频质量数据和用户行为数据，为运营和排障提供数据支撑。

核心亮点

上报系统是 V6 的重要能力升级。通过心跳上报实时采集码率/帧率/丢包等质量指标，结合 Admin 仪表盘，开发者可以快速定位音视频问题，运营人员可以掌握全站直播状态。详细说明请参考 监控与运营。

三级上报

上报类型	触发方式	核心内容	存储表
心跳上报	周期性（每数秒）	音视频码率、帧率、分辨率、丢包率、卡顿、网络 RTT	report_heartbeats + report_heartbeat_downstream
离房上报	用户离开时	会话时长、设备信息、SDK 版本、入房上下文	report_leave_rooms
KV 上报	事件触发	进房/推流/拉流等 15+ 事件的成功率与耗时	report_kv

数据查询 API

端点	说明
GET /room_stats/{room_id}	单房间详细统计（心跳+离房+KV），支持 start_time / end_time 参数
GET /all_room_stats	全站聚合统计，包含所有房间会话和汇总信息
GET /daily_stats	每日趋势数据（开播场次、用户数、峰值在线、直播时长）

Admin 仪表盘集成

上报数据驱动 Admin 后台的三大仪表盘：

• 流详情（Stream Detail）：单条流的实时码率/帧率波形图 + 历史趋势图
• 房间分析（Room Report）：发送端-接收端配对码率对比、卡顿分析、事件时间轴
• 直播大盘（Live Dashboard）：全站实时概览、7 日趋势、风险检测、热度排行

数据保留配置

room:
  live:
    report_retention_days: 15   # 保留最近 15 天（0 = 永久保留）

后台清理任务自动删除过期记录。上报数据通过 ReportStorage 持久化到数据库，数据库不可用时自动回退到内存存储。