从声网/即构迁移到 Monibuca

为什么从声网/即构迁移？

越来越多的企业正在寻找声网 (Agora) 和即构 (Zego) 的替代方案，主要原因包括：

• 成本问题：音视频云服务按分钟/带宽计费，业务量增长后费用急剧上升
• 数据安全：媒体数据经过第三方服务器，无法满足数据合规要求
• 可控性：依赖第三方 SDK 和服务，难以深度定制和排查问题
• 合规要求：政企客户要求私有化部署，不允许数据出境

Monibuca 是一款基于 Rust 的高性能开源流媒体引擎，提供了声网和即构的 API 兼容层，让你：

• 用完全相同的代码连接自建服务器
• 零修改成本完成迁移
• 享受零云服务费的私有化部署

---

一行代码完成迁移

从声网 Agora 迁移

// 修改前 — 使用声网 SDK
import AgoraRTC from "agora-rtc-sdk-ng";

// 修改后 — 使用 Monibuca 适配层（其余代码完全不变）
import { AgoraRTC } from "@monibuca/adapter-agora";

你现有的所有业务逻辑、事件监听、轨道操作代码 完全不需要改动。

从即构 Zego 迁移

// 修改前 — 使用即构 SDK
import { ZegoExpressEngine } from "zego-express-engine-webrtc";

// 修改后 — 使用 Monibuca 适配层（其余代码完全不变）
import { ZegoExpressEngine } from "@monibuca/adapter-zego";

---

迁移步骤

第一步：部署 Monibuca 服务器

# 下载 Monibuca
curl -fsSL https://monibuca.com/install.sh | bash

# 启动（默认监听 8080 端口）
./monibuca

第二步：安装适配层

# 如果你当前使用声网
npm uninstall agora-rtc-sdk-ng
npm install @monibuca/adapter-agora

# 如果你当前使用即构
npm uninstall zego-express-engine-webrtc
npm install @monibuca/adapter-zego

第三步：修改 import

全局替换 import 路径即可（见上方示例），业务代码无需改动。

第四步：修改连接参数

声网用户：将 join() 的第一个参数（原 appId）改为 Monibuca 服务器 WebSocket 地址

// 之前连接声网
await client.join("your-agora-app-id", "channel", token, uid);

// 改为连接 Monibuca
await client.join("ws://your-server:8080", "channel", null, uid);

即构用户：将构造函数的 server 参数改为 Monibuca 服务器地址

// 之前连接即构
const zg = new ZegoExpressEngine(appID, "wss://xxx.zego.im/ws");

// 改为连接 Monibuca
const zg = new ZegoExpressEngine(0, "ws://your-server:8080");

---

API 兼容范围

声网适配层覆盖的 API

类别	支持的方法
客户端	createClient, join, leave, publish, unpublish, subscribe, unsubscribe
轨道创建	createMicrophoneAudioTrack, createCameraVideoTrack, createScreenVideoTrack, createMicrophoneAndCameraTracks
设备管理	getCameras, getMicrophones, getPlaybackDevices, checkSystemRequirements
轨道控制	play, stop, close, setEnabled, setVolume, setDevice
事件	user-joined, user-left, user-published, user-unpublished, connection-state-change

即构适配层覆盖的 API

类别	支持的方法
房间	loginRoom, logoutRoom
推流	createZegoStream, createStream, startPublishingStream, stopPublishingStream
拉流	startPlayingStream, stopPlayingStream
设备	enumDevices, useAudioDevice, useVideoDevice
消息	sendBroadcastMessage
事件	roomStateChanged, roomUserUpdate, roomStreamUpdate, publisherStateUpdate, playerStateUpdate, publishQualityUpdate, playQualityUpdate, IMRecvBroadcastMessage

---

不支持的功能

以下功能属于声网/即构的云服务能力，不在适配层范围内：

• 云端录制（可使用 Monibuca MP4 插件替代）
• CDN 旁路推流（Monibuca 原生支持 RTMP/HLS 分发）
• 内容审核（可接入第三方服务）
• Token 认证（Monibuca 有自己的认证体系）
• 美颜/虚拟背景（Monibuca Web SDK 内置 AI 美颜和虚拟背景功能）

---

常见问题

性能和声网/即构相比如何？

Monibuca 使用 WHIP/WHEP 标准协议，端到端延迟通常在 200-500ms（与声网/即构同级别）。Rust 实现的服务端性能极高，单节点可支撑数千路并发。

需要自己维护服务器吗？

是的，Monibuca 是自部署方案。但好处是完全掌控数据、没有持续费用、可以按需扩展。适合有运维团队的企业。

可以逐步迁移吗？

可以。你可以在同一项目中同时使用原厂 SDK 和 Monibuca 适配层，按房间/频道灵活路由。

浏览器兼容性如何？

与声网/即构一致 — 支持所有现代浏览器（Chrome, Firefox, Safari, Edge）。底层都是 WebRTC。

---

详细 API 文档

查看完整的接口文档和使用示例：Web SDK 适配层 API 参考