集群部署插件

Cluster 插件为 Monibuca 提供多节点集群能力，支持 Origin-Edge 架构、节点自动发现、流自动转发（Relay）、智能负载均衡和故障转移。节点间通信基于 QUIC 协议实现低延迟高可靠传输。

启用插件

Cargo.toml

features = ["cluster"]

架构概述

┌─────────────┐     QUIC     ┌─────────────┐
│   Origin    │◄────────────►│   Edge-1    │
│  (node-1)   │              └─────────────┘
│             │     QUIC     ┌─────────────┐
│  推流端接入  │◄────────────►│   Edge-2    │
└─────────────┘              └─────────────┘
                    QUIC     ┌─────────────┐
               ◄────────────►│   Edge-3    │
                             └─────────────┘

• Origin 节点：接收推流，作为流的源头
• Edge 节点：接收拉流请求，当本地不存在流时自动从 Origin 回源
• 每个节点既可以是 Origin 也可以是 Edge，角色由流的实际位置决定

配置说明

cluster:
  sync:
    enabled: true
    server_id: "node-1"                      # 唯一节点标识
    address: "192.168.1.10:8001"             # 本节点通信地址
    seed_servers:                             # 种子节点列表
      - "192.168.1.10:8001"
      - "192.168.1.11:8001"
      - "192.168.1.12:8001"
    heartbeat_interval: 5                    # 心跳间隔（秒）
    sync_interval: 30                        # 全量同步间隔（秒）
    heartbeat_ttl: 15                        # 心跳超时时间（秒）
    suspect_threshold: 2                     # 标记为可疑的未响应次数
    offline_threshold: 3                     # 标记为离线的未响应次数

  routing:
    cpu_threshold: 85.0                      # CPU 使用率触发重定向的阈值（%）
    bandwidth_threshold: 8000.0              # 带宽触发重定向的阈值（Mbps）
    subscriber_threshold: 2000               # 订阅者数量触发重定向的阈值

  allocation:
    ticket_ttl: 30                           # 分配票据有效期（秒）
    candidate_limit: 3                       # 每次分配的候选节点数量

  relay:
    establish_timeout: 10                    # 建立 Relay 连接超时（秒）
    release_delay: 10                        # 空闲 Relay 释放延迟（秒）
    max_retry_attempts: 3                    # 最大重试次数
    retry_delay: 2                           # 重试间隔（秒）
    health_check_interval: 5                 # 健康检查间隔（秒）

  role: []                                   # 角色配置（可选）

关键配置说明

sync — 节点同步

字段	说明
server_id	集群中唯一的节点标识符，建议使用有意义的命名如 origin-1、edge-beijing-1
address	本节点的 gRPC 通信地址，其他节点通过此地址连接
seed_servers	种子节点地址列表，新节点通过种子节点发现集群中的其他节点
heartbeat_interval	心跳发送间隔，用于探测节点存活状态
suspect_threshold	连续未收到心跳响应达到此次数后，节点被标记为 Suspect
offline_threshold	连续未收到心跳响应达到此次数后，节点被标记为 Offline，触发会话失效和 Relay 清理

routing — 路由策略

当节点负载超过阈值时，Redirect Manager 会将新的订阅请求重定向到负载更低的节点：

• CPU 阈值：节点 CPU 使用率超过 cpu_threshold 时触发重定向
• 带宽阈值：节点出口带宽超过 bandwidth_threshold 时触发重定向
• 订阅者阈值：单节点订阅者数量超过 subscriber_threshold 时触发重定向

relay — 流转发

Edge 节点拉取 Origin 节点的流时，通过 Relay 机制建立连接。配置项控制连接超时、重试策略和健康检查频率。

核心组件

Cluster 插件内部由以下管理器协同工作：

组件	职责
SyncManager	节点发现、心跳检测、状态同步
TransportManager	QUIC 传输层管理，维护节点间连接
SessionRegistry	流会话注册表，记录流在哪个节点发布
RelayManager	流转发管理，建立和维护跨节点的流传输
AllocationManager	资源分配，为新请求选择最优节点
RedirectManager	负载均衡重定向决策
ClusterHooks	事件钩子，响应流的发布/取消发布/订阅/取消订阅事件
ClusterGrpcServer	gRPC 服务端，处理节点间通信请求

工作流程

流发布

1. 推流端向 Origin 节点推流
2. ClusterHooks 监听 StreamEvent::Created，将流信息注册到 SessionRegistry
3. SyncManager 通过心跳将流信息同步到集群其他节点

流订阅（Edge 回源）

1. 拉流请求到达 Edge 节点
2. Edge 本地未找到流，查询 SessionRegistry 确定 Origin 节点
3. RelayManager 通过 QUIC 从 Origin 建立 Relay 连接
4. Origin 的流数据通过 Relay 传输到 Edge，Edge 向客户端分发

节点故障

1. SyncManager 检测到某节点心跳超时
2. 达到 suspect_threshold 后标记为可疑，达到 offline_threshold 后标记为离线
3. SessionRegistry 失效该节点的所有流会话
4. RelayManager 清理该节点的所有 Relay 连接
5. 客户端重新请求时，AllocationManager 分配新的可用节点

部署示例

最小集群（1 Origin + 2 Edge）

Origin 节点配置（node-1）：

cluster:
  sync:
    enabled: true
    server_id: "origin-1"
    address: "10.0.0.1:8001"
    seed_servers: ["10.0.0.1:8001"]

Edge 节点配置（node-2）：

cluster:
  sync:
    enabled: true
    server_id: "edge-1"
    address: "10.0.0.2:8001"
    seed_servers: ["10.0.0.1:8001"]

Edge 节点配置（node-3）：

cluster:
  sync:
    enabled: true
    server_id: "edge-2"
    address: "10.0.0.3:8001"
    seed_servers: ["10.0.0.1:8001"]

种子节点

seed_servers 只需要包含至少一个已启动的节点地址即可。新节点加入后会自动发现集群中的其他节点。建议将 Origin 节点作为种子节点。

更详细的集群架构设计请参阅 集群架构。