集群部署插件

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

启用插件

预编译二进制已内置该插件，在 config.yaml 中设置 enable: true 即可。

架构概述

┌─────────────┐     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:8180"             # HTTP 控制面地址（与 global.http.listenaddr 一致）
    seed_servers:                             # 种子节点列表（同为 HTTP 地址，非 gRPC :50051）
      - "192.168.1.10:8180"
      - "192.168.1.11:8180"
      - "192.168.1.12:8180"
    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	本节点 HTTP 控制面地址（host:port，通常为 global.http.listenaddr），用于 /cluster/api/heartbeat 等
seed_servers	种子节点的 HTTP 控制面地址列表；不要填 global.tcp.listenaddr（gRPC，如 :50051）
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	事件钩子，响应流的发布/取消发布/订阅/取消订阅事件
Cluster HTTP API	控制面 REST（/cluster/api/*），含心跳与节点/会话查询

与全局 gRPC 区分

global.tcp.listenaddr（默认 :50051）是 Monibuca 独立 gRPC 服务，与集群 sync.address / seed_servers 无关。集群节点发现与心跳走 HTTP 控制面（默认端口 8180）。

常见配置错误

cluster.sync.address 必须填 global.http.listenaddr 对外可达的 host:port（例如 HTTP 为 :1985 则写 192.168.x.x:1985），不要填 global.tcp.listenaddr 的 gRPC 端口（如 :50051）。
填错时日志里的 control_addr=...:50051 是如实打印配置值，不是程序误用 gRPC；会话同步会请求 http://对端:50051/cluster/api/... 并失败。
跨节点音视频走 global.quic.listenaddr（如 :8002），与 sync.address 也不同。

工作流程

流发布

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

流订阅（Edge 回源）

1. 拉流请求到达 Edge 节点
2. Edge 查询 SessionRegistry / SyncManager 目录，确定 Origin 节点
3. Edge 向 Origin 发送 POST /cluster/api/relay/pull，Origin 接受后通过 QUIC 建立 Relay
4. Origin 从本地 StreamManager 订阅 FLV 帧并经 QUIC 推送；Edge 写入 cluster 插件 Publisher，再向客户端分发

节点故障

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:8180"
    seed_servers: ["10.0.0.1:8180"]

Edge 节点配置（node-2）：

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

Edge 节点配置（node-3）：

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

种子节点

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

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

HTTP API（集群管理）

默认基地址：http://localhost:8180，路由前缀：/cluster/api/

统一成功响应：

{
  "code": 0,
  "message": "success",
  "data": {}
}

1) 本节点状态

GET /cluster/api/status/local

响应（示例）：

{
  "code": 0,
  "message": "success",
  "data": {
    "server_id": "node-1",
    "address": "192.168.1.10:8180",
    "has_sync": true,
    "node_count": 3,
    "session_count": 25,
    "relay_session_count": 2,
    "active_relay_sessions": 1
  }
}

可选配置 sync.internal_api_key：设置后，所有 /cluster/api/* 请求需携带请求头 X-Cluster-Api-Key（或 Authorization: Bearer <key>）。

2) 节点列表

GET /cluster/api/servers

返回所有可见节点摘要列表。

3) 心跳上报

POST /cluster/api/heartbeat
Content-Type: application/json

请求体：

{
  "summary": {
    "server_id": "node-2",
    "address": "192.168.1.11:8180"
  }
}

字段	类型	必填	说明
summary.server_id	string	是	节点 ID
summary.address	string	是	节点地址

响应 data（v6）：

{
  "summaries": [
    { "server_id": "origin-1", "address": "192.168.1.10:8180", "quic_addr": "..." }
  ]
}

Edge 等节点应合并响应中的 summaries 与 sessions，并在 sync_interval 周期内对种子执行 GET /cluster/api/servers 与 GET /cluster/api/sessions 拉取全量目录。推流/断流后 Edge 会向种子 POST /cluster/api/sessions/sync 推送会话增量；订阅/取消订阅时向种子 POST /cluster/api/sessions/participation 推送参与方增量（action: subscribe / unsubscribe）。

4) 节点全量同步

POST /cluster/api/servers/sync
Content-Type: application/json

请求体：

{
  "summaries": [
    { "server_id": "node-1", "address": "192.168.1.10:8180" },
    { "server_id": "node-2", "address": "192.168.1.11:8180" }
  ]
}

5) 会话列表

GET /cluster/api/sessions

返回集群中的流会话列表（按 stream_path 排序）。

6) 订阅参与方同步

POST /cluster/api/sessions/participation
Content-Type: application/json

{
  "stream_path": "live/test",
  "node_id": "edge-1",
  "action": "subscribe"
}

action 为 subscribe 或 unsubscribe。接收方将远端 node_id 记入该流的 subscribe_nodes。当 node_id 等于本地 server_id 且流在远端 Origin 上发布时，本节点会通过 attach_or_ensure_relay_session 建立或复用 Relay。参与方事件会向目录中所有已知节点 HTTP 地址广播（不仅限于 seed_servers）。

7) Edge 回源拉流（Relay Pull）

POST /cluster/api/relay/pull
Content-Type: application/json

请求体（Edge → Origin）：

{
  "request_id": "uuid",
  "stream_path": "live/test",
  "requestor_id": "edge-1",
  "quic_addr": "192.168.1.11:44944",
  "session_id": "uuid",
  "timestamp": 1710000000000
}

响应 data 为 PullStreamResponse：accepted 为 true 时 Origin 已接受拉流并开始 QUIC Relay；quic_addr 为 Origin 侧 QUIC 端点。

8) 本节点 Relay 会话列表

GET /cluster/api/relay/sessions

返回本节点正在管理的 Relay 会话（state、subscriber_count、frame_count、source_quic_addr 等），供 Admin 集群页「Relay」Tab 展示。

9) 发布分配决策

POST /cluster/api/allocate/publish
Content-Type: application/json

10) 播放分配决策

POST /cluster/api/allocate/play
Content-Type: application/json

以上两个接口请求体一致：

{
  "stream_path": "live/test",
  "protocol": "webrtc",
  "limit": 3
}

字段	类型	必填	说明
stream_path	string	是	流路径
protocol	string	否	协议名，默认 unknown
limit	int	否	候选节点上限

11) 重定向决策

GET /cluster/api/redirect/decision?stream_path=live/test&protocol=webrtc

参数	类型	必填	说明
stream_path	string	是	目标流路径
protocol	string	否	协议类型

错误响应

HTTP 状态码	场景
400	请求体错误或 stream_path 缺失
404	路由不存在
401	配置了 internal_api_key 但缺少或错误的 X-Cluster-Api-Key
503	分配器/重定向器不可用