Monibuca 流别名功能技术实现文档
1. 功能概述
流别名（Stream Alias）是 Monibuca 中的一个重要功能，它允许为已存在的流创建一个或多个别名，使得同一个流可以通过不同的路径被访问。这个功能在以下场景特别有用：
- 为长路径的流创建简短别名
- 动态修改流的访问路径
- 实现流的重定向功能
2. 核心数据结构
2.1 AliasStream 结构
go
type AliasStream struct {
*Publisher // 继承自 Publisher
AutoRemove bool // 是否自动移除
StreamPath string // 原始流路径
Alias string // 别名路径
}2.2 StreamAlias 消息结构
protobuf
message StreamAlias {
string streamPath = 1; // 原始流路径
string alias = 2; // 别名
bool autoRemove = 3; // 是否自动移除
uint32 status = 4; // 状态
}3. 核心功能实现
3.1 别名创建和修改
当调用 SetStreamAlias API 创建或修改别名时，系统会：
- 验证并解析目标流路径
- 检查目标流是否存在
- 处理以下场景：
- 修改现有别名：更新自动移除标志和流路径
- 创建新别名：初始化新的 AliasStream 结构
- 处理订阅者转移或唤醒等待的订阅者
3.2 Publisher 启动时的别名处理
当一个 Publisher 启动时，系统会：
- 检查是否存在指向该 Publisher 的别名
- 对于每个匹配的别名：
- 如果别名的 Publisher 为空，设置为新的 Publisher
- 如果别名已有 Publisher，转移订阅者到新的 Publisher
- 唤醒所有等待该流的订阅者
3.3 Publisher 销毁时的别名处理
Publisher 销毁时的处理流程：
- 检查是否因被踢出而停止
- 从 Streams 中移除 Publisher
- 遍历所有别名，对于指向该 Publisher 的别名：
- 如果设置了自动移除，则删除该别名
- 否则保留别名结构
- 处理相关订阅者
3.4 订阅者处理机制
当新的订阅请求到来时：
- 检查是否存在匹配的别名
- 如果存在别名：
- 别名对应的 Publisher 存在：添加订阅者
- Publisher 不存在：触发 OnSubscribe 事件
- 如果不存在别名：
- 检查是否有匹配的正则表达式别名
- 检查原始流是否存在
- 根据情况添加订阅者或加入等待列表
4. API 接口
4.1 设置别名
http
POST /api/stream/alias请求体：
json
{
"streamPath": "原始流路径",
"alias": "别名路径",
"autoRemove": false
}4.2 获取别名列表
http
GET /api/stream/alias响应体：
json
{
"code": 0,
"message": "",
"data": [
{
"streamPath": "原始流路径",
"alias": "别名路径",
"autoRemove": false,
"status": 1
}
]
}5. 状态说明
别名状态（status）说明：
- 0：初始状态
- 1：别名已关联 Publisher
- 2：存在同名的原始流
6. 最佳实践
使用自动移除（autoRemove）
- 当需要临时重定向流时，建议启用自动移除
- 这样在原始流结束时，别名会自动清理
别名命名建议
- 使用简短且有意义的别名
- 避免使用特殊字符
- 建议使用规范的路径格式
性能考虑
- 别名机制采用高效的内存映射
- 订阅者转移时保持连接状态
- 支持动态修改，无需重启服务
7. 注意事项
别名冲突处理
- 当创建的别名与现有流路径冲突时，系统会进行适当处理
- 建议在创建别名前检查是否存在冲突
订阅者行为
- 别名修改时，现有订阅者会被转移到新的流
- 确保客户端能够处理流重定向
资源管理
- 及时清理不需要的别名
- 合理使用自动移除功能
- 监控别名状态，避免资源泄露