集群架构

Monibuca V6 集群方案基于 Origin-Edge 模型设计，节点间通过 QUIC 协议实现低延迟高可靠通信，支持自动节点发现、流智能转发和负载均衡。

架构总览

flowchart TB
  DNS["DNS/LB<br/>用户入口"]
  DNS --> EBJ["Edge-BJ<br/>北京边缘"]
  DNS --> ESH["Edge-SH<br/>上海边缘"]
  DNS --> EGZ["Edge-GZ<br/>广州边缘"]
  subgraph OC["Origin Cluster"]
    O1["Origin-1"]
    O2["Origin-2"]
    O3["Origin-3"]
  end
  EBJ -->|QUIC Relay| OC
  ESH -->|QUIC Relay| OC
  EGZ -->|QUIC Relay| OC

角色定义

角色	职责
Origin	接收推流端的直接推流，是流的源头。提供流数据给 Edge 节点
Edge	接收观众端的拉流请求。本地无流时自动从 Origin 回源

角色非固定

每个 Monibuca 节点既可以是 Origin 又可以是 Edge，角色由流的实际发布位置决定。同一节点对于 A 流是 Origin（本地推流），对于 B 流可能是 Edge（需要回源）。

QUIC 通信

集群节点间使用 QUIC 协议通信，利用其特性优势：

为什么选择 QUIC

特性	TCP	QUIC
连接建立	1-3 RTT（含 TLS）	0-1 RTT
队头阻塞	整个连接阻塞	仅单个流阻塞
多路复用	需要 HTTP/2	原生支持
连接迁移	不支持	支持（IP 变更不断连）
拥塞控制	全连接共享	每流独立

通信层次

flowchart TB
  App["Application Layer<br/>HTTP /cluster/api 控制面"]
  Relay["Relay Layer<br/>音视频数据传输"]
  Quic["QUIC Transport<br/>quinn 连接管理"]
  Tls["TLS 1.3<br/>自签名证书 / 自动证书管理"]
  App --> Relay --> Quic --> Tls

• HTTP 控制面：节点发现、心跳（POST /cluster/api/heartbeat）、节点/会话查询；地址为 cluster.sync.address / seed_servers（与 global.http.listenaddr 端口一致，默认 8180）
• Relay 层：音视频帧数据的高速传输，直接在 QUIC 流上传输
• 传输层：基于 quinn 库实现的 QUIC 连接管理，自动证书生成

全局 gRPC 非集群控制面

global.tcp.listenaddr（如 :50051）是 Monibuca 主进程的 gRPC 服务，不参与集群心跳与种子发现。勿将 :50051 写入 sync.address 或 seed_servers。

节点发现与健康检查

种子节点发现

新节点启动时连接配置中的种子节点（seed_servers），获取集群拓扑信息：

sequenceDiagram
  participant N as 新节点
  participant S as 种子节点
  participant O as 各节点
  N->>S: 我是 edge-3，请告诉我集群中有谁
  S->>N: origin-1, edge-1, edge-2, ...
  N->>O: 建立 QUIC 连接

心跳机制

sequenceDiagram
  participant A as Node A
  participant B as Node B
  A->>B: heartbeat（每 5 秒）
  B->>A: heartbeat_ack

每次心跳携带节点摘要信息：

• CPU 使用率
• 内存使用率
• 带宽使用
• 当前流数量
• 订阅者数量

故障检测

基于心跳超时进行三级故障检测：

状态	条件	行为
Healthy	心跳正常	正常参与集群
Suspect	连续 suspect_threshold 次未响应	标记可疑，降低权重
Offline	连续 offline_threshold 次未响应	标记离线，清理会话

节点被标记为 Offline 后触发：

1. SessionRegistry 清除该节点的所有流注册信息
2. RelayManager 断开该节点的所有 Relay 连接
3. AllocationManager 不再将请求分配到该节点

流转发（Relay）

回源流程

sequenceDiagram
  participant V as 观众
  participant E as Edge
  participant Reg as SessionRegistry
  participant O as Origin-1
  V->>E: 请求 live/camera01
  Note over E: 本地没有此流，查询 SessionRegistry
  Reg->>E: 该流在 Origin-1
  E->>O: 建立 QUIC Relay 连接
  O->>E: 通过 QUIC 传输音视频数据
  E->>V: 分发到本地订阅者

Relay 生命周期

1. 建立：Edge 检测到本地无流，通过 QUIC 向 Origin 发起 Relay 请求
2. 传输：Origin 的 RingBuffer 数据通过 QUIC 流传输到 Edge
3. 健康检查：定期检测 Relay 连接状态（每 health_check_interval 秒）
4. 释放：当 Edge 上的最后一个订阅者离开后，等待 release_delay 秒后释放 Relay

故障恢复

当 Relay 连接断开时：

1. RelayManager 检测到连接异常
2. 等待 retry_delay 秒后重试
3. 最多重试 max_retry_attempts 次
4. 如果 Origin 节点已离线，查询 SessionRegistry 寻找新的 Origin
5. 所有重试失败后，Edge 上的流被标记为不可用

负载均衡

分配策略

AllocationManager 通过 POST /cluster/api/allocate/publish|play 为新请求选择最优节点，综合考虑：

1. 节点健康状态：只选择 Online 状态的节点
2. 负载指标：CPU 使用率、内存、带宽、流数量、延迟的加权打分

allocate/play 还会附带会话目录中的源站提示（origin_server_id / origin_addr / origin_quic_addr / relay_required），告知调用方在所选节点播放是否会触发 Edge 回源 Relay。

建议型 API

分配与重定向都是建议型控制面 API：只返回决策 JSON，不会自动重定向客户端或建立 Relay。调用方需自行把客户端指向所选节点的媒体端点；客户端在 Edge 实际播放时，Edge 会通过订阅钩子自动 ensure_relay 回源。

重定向决策

当本节点负载超过阈值时，GET /cluster/api/redirect/decision 返回更优节点的建议（should_redirect / target / candidates，并附带同样的源站提示字段）：

sequenceDiagram
  participant C as 调用方
  participant E as Edge-BJ
  C->>E: GET /cluster/api/redirect/decision?stream_path=live/camera01
  Note over E: CPU 90% exceeds threshold 85%
  E->>C: should_redirect=true, target=edge-sh
  Note over C: 自行将观众引导至 Edge-SH 媒体端点

重定向阈值配置：

cluster:
  routing:
    cpu_threshold: 85.0           # CPU 使用率阈值
    bandwidth_threshold: 8000.0   # 带宽阈值（Mbps）
    subscriber_threshold: 2000    # 订阅者数量阈值

部署模式

单 Origin + 多 Edge

最常见的部署模式，适合中小规模：

# Origin 配置
cluster:
  sync:
    server_id: "origin-1"
    address: "10.0.1.1:8180"
    seed_servers: ["10.0.1.1:8180"]

# Edge 配置
cluster:
  sync:
    server_id: "edge-bj-1"
    address: "10.0.2.1:8180"
    seed_servers: ["10.0.1.1:8180"]  # 指向 Origin

多 Origin + 多 Edge

大规模部署，多个 Origin 分担推流负载：

# Origin-1
cluster:
  sync:
    server_id: "origin-1"
    address: "10.0.1.1:8180"
    seed_servers: ["10.0.1.1:8180", "10.0.1.2:8180"]

# Origin-2
cluster:
  sync:
    server_id: "origin-2"
    address: "10.0.1.2:8180"
    seed_servers: ["10.0.1.1:8180", "10.0.1.2:8180"]

# Edge
cluster:
  sync:
    server_id: "edge-1"
    address: "10.0.2.1:8180"
    seed_servers: ["10.0.1.1:8180", "10.0.1.2:8180"]

级联 Edge

Edge 节点也可以作为其他 Edge 的上游，形成多层级联：

flowchart LR
  Ingest["推流"] --> Origin --> L1["Edge-L1<br/>区域中心"] --> L2["Edge-L2<br/>城市节点"] --> Viewer["观众"]

适合全国大规模分发场景。

运维命令

集群 HTTP API 前缀为 /cluster/api/，基地址与 global.http.listenaddr 一致（非 gRPC global.tcp）。

查看本节点状态

GET /cluster/api/status/local

查看节点列表

GET /cluster/api/servers

查看会话目录

GET /cluster/api/sessions

查看本节点 Relay

GET /cluster/api/relay/sessions

Admin「集群管理」页基于上述接口的当前快照展示派生告警与 Origin→Relay 拓扑（30s 轮询），不是历史事件存储。

更多接口见 Cluster 插件 文档。