Monibuca v5

中文

English

中文

English

切换深色模式

级联功能 ​

级联功能是 Monibuca 的高级特性，允许多个 Monibuca 实例之间建立级联关系，实现流媒体的分布式部署和负载分担。通过级联功能，可以构建多级流媒体分发网络，提高系统的可扩展性和可靠性。

功能特点 ​

  • QUIC协议通信：基于QUIC协议实现高性能、低延迟的数据传输
  • 自动注册机制：下级节点可以自动向上级节点注册
  • 安全认证：支持基于密钥的安全认证机制
  • 流转发：支持流媒体数据的上下级转发
  • 状态管理：实时监控级联节点的在线状态
  • HTTP代理：支持HTTP API请求的级联转发
  • 数据库存储：级联配置信息持久化存储
  • 访问控制：提供细粒度的访问控制机制

架构说明 ​

级联功能包含两个核心组件：

级联服务器（CascadeServerPlugin） ​

  • 作为上级节点，接受下级节点的连接
  • 管理下级节点的注册和状态
  • 提供流转发和API代理服务
  • 支持下级节点的自动注册

级联客户端（CascadeClientPlugin） ​

  • 作为下级节点，连接到上级节点
  • 支持自动推流到上级节点
  • 提供拉流代理功能

配置说明 ​

级联服务器配置 ​

在配置文件中配置级联服务器：

yaml
cascadeserver:
  # QUIC监听地址配置
  quic:
    listenaddr: ":44944"  # 级联服务器监听端口
  
  # 是否允许下级节点自动注册
  autoregister: true      # 默认为true，允许自动注册
  
  # 访问控制配置
  relayapi:
    allow:                # 允许转发的路径前缀
      - "/api/"
      - "/flv/"
    deny:                 # 禁止转发的路径前缀
      - "/api/admin/"

级联客户端配置 ​

在配置文件中配置级联客户端：

yaml
cascadeclient:
  # 启用级联客户端
  enable: true
  
  # 上级服务器地址
  server: "192.168.1.100:44944"
  
  # 连接密钥（可选）
  secret: "your-secret-key"
  
  # 是否自动推流到上级
  autopush: true
  
  # 访问控制配置
  relayapi:
    allow:                # 允许转发的路径前缀
      - "/api/"
    deny:                 # 禁止转发的路径前缀
      - "/api/admin/"
  
  # 按需拉流配置
  onsub:
    pull:
      ".*": "m7s://$0"    # 正则表达式匹配流路径，$0表示完整匹配

配置项详细说明 ​

级联服务器配置项 ​

配置项类型必填默认值说明
quic.listenaddr字符串是":44944"QUIC协议监听地址和端口
autoregister布尔值否true是否允许下级节点自动注册
relayapi.allow字符串数组否[]允许转发的路径前缀列表
relayapi.deny字符串数组否[]禁止转发的路径前缀列表

级联客户端配置项 ​

配置项类型必填默认值说明
enable布尔值否false是否启用级联客户端
server字符串是-上级服务器地址（IP:端口）
secret字符串否-连接密钥，用于身份验证
autopush布尔值否false是否自动推流到上级节点
relayapi.allow字符串数组否[]允许转发的路径前缀列表
relayapi.deny字符串数组否[]禁止转发的路径前缀列表
onsub.pull映射否{}按需拉流配置，键为正则表达式，值为拉流URL模板

部署架构示例 ​

简单两级级联 ​

上级节点 (192.168.1.100:44944)
├── 下级节点A (192.168.1.101)
├── 下级节点B (192.168.1.102)
└── 下级节点C (192.168.1.103)

配置示例：

上级节点配置：

yaml
cascadeserver:
  quic:
    listenaddr: ":44944"
  autoregister: true

下级节点配置：

yaml
cascadeclient:
  enable: true
  server: "192.168.1.100:44944"
  autopush: true

多级级联架构 ​

总部节点 (HQ)
├── 区域节点A (Region-A)
│   ├── 边缘节点A1
│   └── 边缘节点A2
└── 区域节点B (Region-B)
    ├── 边缘节点B1
    └── 边缘节点B2

功能使用 ​

流转发 ​

当下级节点配置了 autopush: true 时，所有发布到下级节点的流都会自动转发到上级节点。

按需拉流 ​

下级节点可以通过 onsub.pull 配置按需从上级节点拉取流：

yaml
cascadeclient:
  server: "192.168.1.100:44944"
  secret: "your-secret-key"
  onsub:
    pull:
      ".*": "m7s://$0"              # 匹配所有流路径，从上级拉取对应流
      "live/(.*)": "m7s://live/$1"  # 匹配 live/ 前缀的流

这种配置方式使用正则表达式匹配流路径，当有订阅者请求某个流时，如果本地没有该流，会自动从上级节点拉取。

API转发 ​

启用API转发功能后，可以通过级联服务器访问下级节点的API：

http
GET /api/relay/{instanceId}/api/stream/list

其中 {instanceId} 是下级节点的实例ID。

API接口 ​

级联服务器提供了完整的管理API：

获取下级节点列表 ​

http
GET /api/cascade/clients

响应示例：

json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "edge-node-1",
      "ip": "192.168.1.101",
      "online": true,
      "created_time": "2025-01-01T00:00:00Z",
      "updated_time": "2025-01-01T12:00:00Z"
    }
  ]
}

创建下级节点 ​

http
POST /api/cascade/clients
Content-Type: application/json

{
  "name": "edge-node-2",
  "secret": "node-secret-key"
}

更新下级节点 ​

http
PUT /api/cascade/clients/{id}
Content-Type: application/json

{
  "name": "updated-node-name",
  "secret": "new-secret-key"
}

删除下级节点 ​

http
DELETE /api/cascade/clients/{id}

安全配置 ​

密钥认证 ​

为提高安全性，建议为每个下级节点配置独立的密钥：

服务器端创建客户端：

bash
curl -X POST http://server:8080/api/cascade/clients \
  -H "Content-Type: application/json" \
  -d '{"name": "edge-node-1", "secret": "unique-secret-key"}'

客户端配置对应密钥：

yaml
cascadeclient:
  server: "server:44944"
  secret: "unique-secret-key"

网络安全 ​

  1. 防火墙配置：确保只开放必要的端口
  2. VPN/专线：在公网环境建议使用VPN或专线连接
  3. IP白名单：配置访问控制白名单

监控和运维 ​

状态监控 ​

通过API接口可以实时监控级联状态：

bash
# 检查所有下级节点状态
curl http://server:8080/api/cascade/clients

# 通过下级节点代理访问其API
curl http://server:8080/api/relay/1/api/stream/list

日志监控 ​

级联相关的日志会包含以下关键信息：

  • 节点连接和断开事件
  • 认证成功和失败记录
  • 流转发状态
  • 错误和异常信息

性能调优 ​

  1. QUIC参数调优：根据网络环境调整QUIC连接参数
  2. 并发控制：合理设置最大连接数
  3. 缓冲区优化：根据带宽调整缓冲区大小

故障排查 ​

常见问题 ​

  1. 连接失败

    • 检查网络连通性
    • 确认端口是否开放
    • 验证密钥配置

  2. 认证失败

    • 检查密钥是否正确
    • 确认服务器端是否允许自动注册

  3. 流转发异常

    • 检查流路径配置
    • 确认网络带宽是否充足
    • 查看相关错误日志

调试模式 ​

启用调试日志获取更详细的信息：

yaml
log:
  level: debug

相关资源 ​

配置示例 ​

  • 级联配置示例 - 完整的配置示例和部署指南
  • Docker Compose 部署 - 容器化部署示例
  • 多级级联配置 - 复杂网络拓扑配置

性能优化 ​

  • 性能调优指南 - 详细的性能优化配置
  • 硬件配置建议 - 不同规模部署的硬件推荐

测试和监控 ​

  • 集成测试 - 自动化测试套件
  • 故障排除指南 - 常见问题解决方案
  • 监控配置 - 实时监控和告警设置

数据库 ​

  • 数据库配置 - PostgreSQL 初始化脚本
  • 级联状态管理 - 级联连接状态跟踪

最佳实践 ​

  1. 网络规划：合理规划级联网络拓扑，避免单点故障
  2. 负载均衡：在多个上级节点间分散负载
  3. 监控告警：设置节点状态监控和告警机制
  4. 定期维护：定期清理离线节点和过期数据
  5. 安全更新：及时更新密钥和安全配置
  6. 性能测试：定期进行负载测试和性能评估
  7. 文档维护：保持网络拓扑和配置文档的更新

注意事项 ​

  1. 版本兼容性：确保上下级节点使用兼容的Monibuca版本
  2. 时钟同步：保持各节点时钟同步，避免时间戳问题
  3. 资源限制：合理配置资源限制，防止级联风暴
  4. 数据一致性：在多级级联中注意数据一致性问题
  5. 网络稳定性：确保级联节点间网络连接的稳定性
  6. 备份策略：制定数据备份和恢复策略

快速开始 ​

如果您是初次使用级联功能，建议按以下顺序进行：

  1. 阅读配置示例了解基本配置
  2. 使用 Docker Compose 快速搭建测试环境
  3. 运行集成测试验证功能
  4. 参考性能调优指南优化配置
  5. 遇到问题时查阅故障排除指南

通过级联功能，Monibuca可以构建大规模、高可用的分布式流媒体网络，满足不同场景下的部署需求。

基于 AGPL 许可发布

版权所有 © 2025 Monibuca 团队