监控与运营

Monibuca V6 内置了全链路监控与运营分析体系，覆盖从单条流的码率帧率实时观测，到全站直播间的运营大盘。无需对接第三方监控系统，开箱即用。

核心能力一览

维度	能力	说明
流级监控	实时码率 / 帧率 / GOP 可视化	逐帧波形图 + 历史趋势图
房间级分析	发送端 ↔ 接收端配对分析	码率、卡顿、丢包、分辨率全维度
直播运营大盘	全站实时概览 + 7 日趋势	开播数、观众、峰值、收入一目了然
告警与风险	异常检测 + 风险分级	零观众检测、卡顿率、丢包飙升
数据导出	CSV 导出 + JSON API	对接 BI 系统和自定义分析

三级上报体系

Monibuca V6 的数据采集分为三个层级，各自承担不同职责：

graph LR
    subgraph Client["客户端 SDK"]
        HB["HeartbeatReport<br/>（周期上报）"]
        LR["LeaveRoomReport<br/>（离房上报）"]
        KV["KVReport<br/>（事件计数）"]
    end

    subgraph Server["Room Service"]
        RS["ReportStorage"]
        DB["SQLx 数据库"]
        MEM["内存回退"]
    end

    HB -->|每数秒| RS
    LR -->|离开时| RS
    KV -->|事件触发| RS
    RS --> DB
    RS -.->|DB 不可用| MEM

1. 心跳上报（HeartbeatReport）

客户端在房间内持续周期上报，是最核心的质量数据来源：

指标类别	采集内容
视频	码率（bps）、帧率（fps）、分辨率（W×H）、编解码器、已处理/丢弃帧数、卡顿次数与时长
音频	码率（bps）、采样率、声道数、编解码器、音量电平
网络	RTT（往返延迟）、码率、丢包率
设备	终端类型、设备名称、操作系统版本、网络类型（WiFi/4G/5G）

每条心跳包含：

上行（upstream）：发布者自身的音视频指标
下行（downstream）数组：每个订阅者的接收指标

数据存储在 report_heartbeats + report_heartbeat_downstream 表中，支持时间范围查询。

2. 离房上报（LeaveRoomReport）

用户离开房间时提交完整会话快照：

房间 ID、用户 ID
会话起止时间、在房时长（joining_duration_ms）
加入请求状态、退出指令时间
SDK 版本、设备信息
ClientJoinInfo 入房上下文快照

存储在 report_leave_rooms 表中，用于会话粒度的回溯分析。

3. KV 上报（KVReport）

以键值对形式记录标准化事件计数，覆盖 15+ 关键操作：

事件分组	追踪内容
`ENTER_ROOM` / `EXIT_ROOM`	进出房成功率、耗时
`PUBLISH` / `SUBSCRIBE`	推/拉流成功率、耗时
`START_AUDIO` / `START_VIDEO`	音视频开启成功率
`ICE_CONNECT`	WebRTC ICE 连接成功率
`SIGNAL_CHANNEL_SETUP`	信令通道建立耗时
`START_MICROPHONE` / `START_CAMERA`	设备打开成功率
`PING`	心跳往返耗时

每个事件组包含：尝试次数（attempt）、成功率（success_rate）、平均耗时（cost_ms）。

流级实时监控（Stream Detail）

Admin 后台的流详情页提供对单条流的深度实时观测，是排查音视频质量问题的核心工具。

双模式展示

模式	适用场景	数据来源
历史统计（Stats）	回溯分析趋势变化	定期采样，ECharts 折线图
实时波形（Realtime）	逐帧级别排查	SSE 实时推送，SVG 波形图

统计模式图表

音频码率 + 帧率：kbps 折线叠加 fps 曲线
视频码率 + 帧率：kbps 折线叠加 fps 曲线
视频 GOP 趋势：GOP（Group of Pictures）大小变化
下行码率分布：所有订阅者的总体下行码率

实时波形模式

实时模式通过 SSE（Server-Sent Events） 逐帧推送数据，以 SVG 柱状图渲染：

🔴 红色柱：视频关键帧（I 帧），柱高与帧大小成正比
🔵 蓝色柱：普通视频帧（P/B 帧）
支持暂停/恢复 SSE 流，便于截取特定时段数据

订阅者快照

同时展示当前每个订阅者的实时状态：

指标	说明
插件名 & 类型	拉流协议来源
同步模式	音视频同步策略
缓冲时间	播放缓冲深度
已处理帧数	音频/视频各自的累计帧数
丢帧数	被丢弃的帧数量
迟到帧数	晚到的帧数量

典型排障场景

问题	观察方式
推流端码率不足	视频码率折线长期低于预期
关键帧间隔过大	GOP 趋势图出现异常尖峰
订阅者卡顿	订阅者丢帧数持续增长
编码器异常	实时波形中出现连续小帧或 I 帧丢失

房间级质量分析（Room Report）

Admin 后台的房间分析页面向 QoS 排障和用户体验分析，支持对已结束的会话进行深入回溯。

会话发现与筛选

合并 leave_reports + heartbeat_reports 自动发现历史会话
支持关键词搜索、用户数范围、日期范围筛选
可导出会话列表为 CSV 文件

用户角色智能识别

根据心跳上报模式自动识别用户角色：

角色	识别依据
🎙 主播	有上行推流数据
👁 观众	仅有下行数据
🎧 坐席	客服场景中的操作端
👤 访客	客服场景中的用户端

码率分析面板

UserBitratePanel 提供两种视角：

发送端视角：查看用户上行码率随时间的变化
接收端视角：查看该用户从各发送端接收的下行码率
支持切换：全部指标 / 仅视频 / 仅音频

发送端 ↔ 接收端配对分析

这是最强大的排障工具——PairDetailView 展示一对发送者与接收者之间的完整传输链路：

┌─────────┐          网络链路          ┌─────────┐
│  发送端  │ ──── 码率/帧率/丢包 ────▶ │  接收端  │
│         │                            │         │
│ 编码器   │   ◀──── RTT/丢包 ────     │ 解码器   │
│ 采集帧率 │                            │ 播放帧率 │
│ 采集码率 │                            │ 播放码率 │
└─────────┘                            └─────────┘

分析维度	发送端指标	接收端指标
视频	采集帧率、编码码率	播放帧率、解码码率
视频质量	分辨率（W×H）	卡顿次数/时长、丢包率
音频	采集音量、采样率	播放音量、声道数
网络	上行码率	RTT、总码率、丢包率

所有图表通过 ECharts Group Sync 联动——拖动任一图表的时间轴，其余图表同步跟随，方便交叉对比。

事件时间轴

在码率图上叠加关键事件标记：

用户加入/离开
推流开始/停止
角色切换

直播运营大盘（Live Dashboard）

Admin 后台的直播大盘面向运营人员和管理者，提供全站维度的实时概览和趋势分析。

实时概览

指标	说明
直播间总数	全部房间数（含已结束）
当前开播	状态为 Living 的房间数
全站在线观众	所有房间观众总和
总点赞数	当前累计点赞
礼物收入	当前累计礼物价值

今日统计

指标	说明
今日开播场次	当天新开直播数
今日开播房间	当天去重房间数
今日累计用户	进入过房间的去重用户数
峰值在线	当天最高同时在线人数
总直播时长	所有直播累计时长

7 日趋势图

以日为粒度展示以下指标的趋势变化：

📈 开播场次趋势
📈 累计用户趋势
📈 峰值在线趋势

数据源自 report_live_daily_stats 表的每日聚合数据。

三视角分析

大盘提供三个分析 Tab：

运营视角

直播间列表：状态（准备中/直播中/暂停/已结束）、观众数、互动数据
热度排行：基于 (观众数 × 3 + 点赞数) 的热度公式
各状态房间数量分布

风险视角

异常检测：自动识别潜在问题房间
风险分级：高/中/低/正常
风险原因标注：卡顿率异常、码率骤降、零观众等
支持按风险等级筛选

系统视角

监控覆盖率：被监控的房间占比
健康率：流可用性健康度
零观众检测：直播中但无人观看的房间
数据保留策略：当前配置的数据保留天数

自动刷新

大盘以 10 秒间隔自动轮询，支持静默刷新（后台更新数据）和全量刷新（刷新 UI）两种模式，确保运营人员看到的数据始终是最新的。

指标上报插件（Report Plugin）

除了 Room 服务内置的上报系统外，V6 还提供独立的 Report 插件用于流级别的实时指标聚合：

API 端点

方法	路径	说明
`POST`	`/metrics`	提交指标上报
`GET`	`/rooms`	获取所有房间聚合指标
`GET`	`/metrics/{room_id}`	获取指定房间聚合指标
`GET`	`/metrics/{room_id}/{user_id}`	获取指定用户指标
`GET`	`/history/{room_id}`	获取房间历史指标

房间聚合指标

指标	说明
在线用户数	当前房间内用户
上行总码率	所有发布者码率之和
下行总码率	所有订阅者接收码率之和
平均帧率	房间内发布者平均帧率
卡顿率	出现卡顿的用户占比

数据保留窗口为 1 小时，每 5 分钟自动清理过期数据。

数据存储与保留

存储架构

┌──────────────────┐
│  ReportStorage   │
│                  │
│  ┌────────────┐  │
│  │ SQLx Pool  │──│──▶ report_heartbeats
│  │ (primary)  │  │    report_heartbeat_downstream
│  └────────────┘  │    report_leave_rooms
│        │         │    report_kv
│        │ 失败    │    report_live_daily_stats
│        ▼         │
│  ┌────────────┐  │
│  │ In-Memory  │  │
│  │ (fallback) │  │
│  └────────────┘  │
└──────────────────┘

主存储：SQLx 异步数据库持久化，支持时间范围查询
回退存储：数据库不可用时自动切换到内存 HashMap，保证数据不丢失
写入通过 异步 mpsc 通道，不阻塞主业务线程

数据保留策略

room:
  live:
    report_retention_days: 15   # 保留最近 15 天数据
                                # 0 = 永久保留

后台清理任务定期运行，自动删除过期记录
Admin 日期选择器自动禁用超出保留期的日期

系统指标

Room Service 内置了系统级性能指标采集（MetricsCollector），使用原子计数器实现无锁记录：

类别	指标	说明
API	请求数、错误数、延迟（p50/p95/p99）	HTTP 接口性能
WebSocket	消息数、广播数	信令通道负载
数据库	查询数、延迟（p50/p95/p99）	持久化性能
缓存	命中数、未命中数、命中率	缓存效率
系统	内存使用、CPU、活跃任务数、运行时长	资源占用

基于这些指标实时计算健康状态：

状态	含义
🟢 Healthy	所有指标正常
🟡 Degraded	部分指标超阈值，服务可用但需关注
🔴 Unhealthy	关键指标异常，需立即处理

与外部系统集成

JSON API

所有监控数据均可通过 HTTP JSON API 获取，方便对接外部 BI、告警、数据分析系统：

端点	说明
`GET /room_stats/{room_id}`	单房间详细统计（支持时间范围）
`GET /all_room_stats`	全站聚合统计
`GET /daily_stats`	每日趋势数据
`POST /submit_report`	外部服务上报入口