系统架构

Monibuca V6 是一个使用 Rust 编写的高性能流媒体服务器引擎。本文介绍其整体架构设计。

架构图

Monibuca v6 的架构可以从两个互补的视角理解，两张图都嵌在下方：

• 运行时视角（媒体数据流）：一帧数据从推流端经过协议接入、原子写入、零拷贝 RingBuffer，到万级订阅者分发的完整生命周期；附 QUIC 集群级联通道。
• 编译期视角（Crate 依赖）：HTTP 三套表面层、引擎内置服务、29 个可插拔 crate、monibuca-sdk、codec 基础层之间的编译期依赖图；附三种插件加载模式。

运行时 · 媒体数据流

运行时 · 媒体数据流

一帧从推流端到万级订阅者的完整生命周期：协议接入 → 原子写 → 零拷贝 RingBuffer → Dispatcher 单读广播，附 QUIC 集群级联通道。

4 视图：媒体主链路 · 插件契约 · 控制与运维面 · QUIC 集群级联
14 节点 · 11 连线 · 16 仓库证据锚点

全屏查看 →

编译期 · Crate 依赖

编译期 · Crate 依赖

HTTP 三套表面层、引擎内置服务、29 个可插拔 crate、monibuca-sdk、codec 基础层之间的编译期依赖图，附三种插件加载模式。

4 视图：主依赖链 · HTTP 表面层 · 插件生态 · SDK 契约
14 节点 · 13 连线 · 4 src/ 边界 · 5 plugins 子层

全屏查看 →

补充：完整全景观图（手写版） —— 单图集成 26 插件全清单、codec 8 模块、HTTP 表面层三版本、底部 Architecture Notes。

核心模块

核心模块位于 src/core/，负责流媒体引擎的底层数据结构和处理逻辑：

模块	文件	职责
buffer	buffer.rs	Lock-free SPMC 环形缓冲区，用于帧存储
frame	frame.rs	AVFrame 音视频帧数据结构
track	track.rs	音视频轨道管理（VideoTrack / AudioTrack）
publisher	publisher.rs	推流者，管理轨道和订阅者列表
subscriber	subscriber.rs	订阅者，从 RingBuffer 消费帧数据
dispatcher	dispatcher.rs	帧分发器，单次读取广播到所有订阅者
pool	pool.rs	对象池（BytesPool、ObjectPool、ThreadLocal 池）
task	task.rs	分层任务系统，支持层级取消
proxy	proxy.rs	拉流/推流代理（Pull Proxy / Push Proxy）
recorder	recorder.rs	流录制框架（FLV / MP4 / fMP4 / HLS）
transformer	transformer.rs	流转换器（订阅源流 → 处理 → 发布新流）
playback	playback.rs	回放速度控制和时间戳缩放
storage	storage.rs	异步存储 trait（io_uring ready）

HTTP API 表面层

管理类 HTTP API 采用多表面（Surface）并存架构：各表面负责 HTTP 形状（路径、方法、JSON 字段、状态码），共享同一套应用层 AppFacade，再委托给 StreamManager 与插件服务。gRPC 管理接口同样经 AppFacade 转发，避免业务逻辑重复。

表面	前缀	说明
V5CompatSurface	/api/*	v5 兼容层，保留历史路径与响应信封；现有集成方默认使用
V6Surface	/v6/api/*	v6 原生 REST API，新集成推荐
ZegoCompatSurface	/zego/api/*	ZEGO Action 风格兼容层（api-compat-zego feature）
gRPC	—	与 HTTP 共用 AppFacade

统一注册入口：src/server/http_plugins/register.rs 中的 register_http_plugins()。启动时按 Cargo feature 挂载各表面（如 api-v5-compat、api-v6）。

迁移约定：遗留客户端继续使用 /api/*；新功能优先在 /v6/api/* 提供，v5 层以兼容优先演进（追加字段、避免破坏性变更）。

Crate 结构

Monibuca V6 采用 Cargo Workspace 组织代码，拆分为多个独立 crate：

monibuca/                      # 主 crate（引擎 + 二进制）
├── src/
│   ├── core/                  # 核心数据结构
│   ├── manager/               # StreamManager / PluginManager
│   ├── api/                   # AppFacade + HTTP 表面层（v5 / v6 / zego）
│   ├── config/                # 配置管理
│   ├── grpc/                  # gRPC API（经 AppFacade）
│   ├── server/http_plugins/   # HTTP 插件与表面层注册
│   └── room/                  # 内置房间服务
├── crates/
│   ├── codec/        # codec crate — 编解码 + 枚举 + trait
│   ├── monibuca-sdk/          # SDK crate — 插件开发 SDK
│   ├── monibuca-sdk-macros/   # SDK 过程宏
│   ├── m7s-config-framework/  # 配置框架
│   └── m7s-config-macros/     # 配置框架宏
└── plugins/                   # 25 个插件 crate
    ├── rtmp/
    ├── rtsp/
    ├── flv/
    ├── hls/
    ├── webrtc/
    └── ...

Crate 依赖关系

flowchart BT
  plugins["plugins/*<br/>各插件只依赖 SDK"] --> engine["monibuca (engine)<br/>主引擎 crate"]
  engine --> sdk["monibuca-sdk<br/>插件开发的唯一契约层"]
  sdk --> codec["codec<br/>最底层，零依赖其他 monibuca crate"]

• codec: 定义所有共享类型 — AVFrame、VideoCodec、AudioCodec、VideoFrameType、trait 接口（PublisherApi / SubscriberApi / StreamManagerApi）
• SDK: 封装 codec 并提供插件注册、HTTP 路由、配置 Schema 等开发工具
• 主 crate: 引擎实现，包含 StreamManager、Dispatcher、RingBuffer 等核心逻辑
• plugins/: 各协议和功能插件，仅依赖 SDK crate

插件系统架构

Monibuca V6 支持三种插件加载模式：

模式	说明	特点
内置插件	官方预编译二进制	性能最优，默认模式，通过 config.yaml 启用
动态加载	plugins_dir 目录	.so/.dylib/.dll 运行时加载
WASM 沙箱	实验性	隔离运行，安全性最高

官方发布的预编译包已内置全部官方插件，用户通过配置文件按需启用，无需从源码编译引擎。

技术栈

组件	库	用途
异步运行时	Tokio	事件驱动并发
互斥锁	parking_lot	高性能 Mutex / RwLock
并发哈希表	DashMap	lock-free 流注册表
原子指针交换	ArcSwap	无锁 IDR 列表、订阅者列表
QUIC 传输	Quinn	WebTransport / QUIC 协议支持
零拷贝字节	Bytes	帧数据零拷贝共享
WebRTC	rustrtc	WebRTC 协议栈
gRPC	Tonic	API 服务
数据库	SQLx	录制索引、配置持久化
序列化	Serde + serde_json/serde_yaml	配置和 API 数据格式

性能设计原则

1. Lock-free 优先: RingBuffer 的写操作使用 fetch_add 原子指令，读操作通过 ArcSwap 实现无锁访问
2. 零拷贝: 帧数据通过 Arc<AVFrame> 共享，订阅者之间不复制数据
3. 单次读取广播: Dispatcher 只从 RingBuffer 读取一次帧数据，然后广播给所有订阅者
4. 背压控制: 使用 bounded channel，慢速订阅者丢帧而不阻塞其他订阅者
5. 对象池复用: BytesPool 和 ThreadLocal 池减少热路径上的内存分配