Monibuca流别名（Stream Alias）实战：1行配置实现多路径访问同一视频流-育师

Monibuca流别名（Stream Alias）实战：1行配置实现多路径访问同一视频流

【免费下载链接】monibucaMonibuca（简称 m7s）是一款纯 Go 开发的开源流媒体服务器开发框架。项目地址: https://gitcode.com/langhuihui/monibuca

Monibuca（简称 m7s）是一款纯 Go 开发的开源流媒体服务器开发框架，其内置的**流别名（Stream Alias）**功能堪称"流路径管理神器"：只需 1 行 YAML 配置或一条 HTTP 请求，就能让同一路视频流被多个不同路径访问，还能实现直播中无缝切换广告、导播台式的流内容替换，全程观众无感知。

🎯 流别名能解决什么痛点？

在直播、视频监控、导播等业务中，你经常会遇到这些场景：

路径太长：内部流路径是live/camera-10086/2026-10-03，想给客户端一个短路径live/main；
路径要变：前端域名或业务目录调整，客户端地址不能动，希望服务端悄悄把流"搬"到新路径；
无缝插播：直播中插入广告，希望观众停留在固定地址上，内容在"直播流 ↔ 广告流"之间无缝切换，不黑屏、不卡顿、无需刷新播放器。

Monibuca 的流别名功能就是为此设计的：它为同一路上行流建立"别名映射"，所有拉流（RTMP、RTSP、HTTP-FLV、HLS、WebRTC 等协议）统一按别名解析，一次配置，多路径直达。

📝 方式一：1 行配置，正则别名开箱即用

在 Monibuca 的全局配置中，StreamAlias字段是一个正则表达式 → 目标流路径的映射（见 server.go 中的ServerConfig定义）：

global: streamAlias: "^cam/(\d+)$": "live/camera-$1"

就这 1 行！它的含义是：任何人拉流cam/101时，服务器自动将其解析为真实流live/camera-101，$1等分组引用让一条规则覆盖整个"系列流"，无需为每路流单独配置。

其核心逻辑在 alias.go 的processAliasOnStart中：订阅路径未命中普通流时，依次匹配StreamAlias中的正则规则，命中后动态生成别名并建立持久化映射。配置机制说明可参考 doc_CN/arch/config.md。

💡 提示：正则别名在第一次有客户端访问时被"物化"为一条真实的别名记录，之后便与 API 创建的别名享受完全相同的能力。

🚀 方式二：HTTP API 动态管理别名

不想改配置文件重启？Monibuca 提供了标准 REST API（接口定义见 pb/global.proto）：

① 创建/修改别名——POST /api/stream/alias

curl -X POST http://localhost:8080/api/stream/alias \ -H "Content-Type: application/json" \ -d '{"streamPath": "live/camera-101", "alias": "live/main", "autoRemove": false}'

② 查询别名列表——GET /api/stream/alias/list

{ "code": 0, "data": [ {"streamPath": "live/camera-101", "alias": "live/main", "autoRemove": false, "status": 1} ] }

③ 删除别名—— 只传alias、不传streamPath即可：

curl -X POST http://localhost:8080/api/stream/alias \ -H "Content-Type: application/json" \ -d '{"alias": "live/main"}'

其中status字段表示别名当前状态：1表示已关联到正在推流的 Publisher，2表示存在同名原始流（见 alias.go 中的GetStreamAlias实现）。

🎬 实战：直播无缝插播广告（导播级玩法）

这是流别名最"杀手级"的应用——固定观众地址，后端随时换内容：

创建别名，指向主直播流：alias: live/show→streamPath: live/main；
需要插播广告时，同一个别名改指向广告流：streamPath: ads/ad1；
广告播完，再把别名切回live/main。

# 插入广告：同一别名秒级改指向，观众无感知 curl -X POST http://localhost:8080/api/stream/alias \ -d '{"streamPath": "ads/ad1", "alias": "live/show", "autoRemove": false}'

切换瞬间，Monibuca 会自动把订阅该别名的所有客户端平滑转移到新流（TransferSubscribers机制，见 alias.go 的processAliasOnStart），主播端推流完全不受影响。配合autoRemove: true还能让临时别名在流结束后自动清理，防止资源泄漏。完整案例与广告轮播脚本见 doc_CN/stream_alias_usage.md。

⚙️ 三大关键机制详解

持久化存储：配置了数据库后，别名会写入stream_alias表（StreamAliasDB模型，见 alias.go），重启服务器后自动恢复（server.go 的initStreamAlias），无需担心配置丢失；
断流自愈：原始流中断时，别名依然"占位"。等新的 Publisher 重新推上来，别名自动接管并唤醒等待中的订阅者，观众侧体验为"短暂重连"而非"流不存在"；
参数透传：别名支持携带 URL 查询参数，订阅时客户端参数会覆盖别名保存的同名参数（alias.go），方便做鉴权、时移等细粒度控制。