MediaMTX：三步跑通跨协议流转发，RTSP 转 HLS 全程不改配置

MediaMTX：三步跑通跨协议流转发，RTSP 转 HLS 全程不改配置

【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx

摄像头只吐 RTSP，网页端却要低延迟播放；直播要存录像还要能回看；同一路流想同时喂给多个不同协议的客户端——这些问题指向的是同一个东西：一台协议转换中枢。MediaMTX 流媒体服务器用 Go 写成，编译后是单个可执行文件、没有运行时依赖，负责把音视频流在 RTSP、RTMP、HLS、WebRTC、SRT、MoQ 这些协议之间来回转发，顺带支持录像和回放。好消息是：默认配置就能用，你不用先啃完文档才敢动手。

五分钟，三步跑通

1. 启动容器

Docker 是最省事的部署方式，生产环境推荐用镜像，它就是最新稳定版。这里只开两个端口：8554 用来推 RTSP，8888 用来读 HLS，够跑通验证了。

docker run --rm -it \ -p 8554:8554 -p 8888:8888 \ bluenviron/mediamtx:1

默认配置下 RTSP 8554、RTMP 1935、HLS 8888、WebRTC 8889、SRT 8890 都是开着的，这里只是没把它们全部映射到宿主机。

2. 推一条流

拿任意本地视频文件当推流源，经 FFmpeg 推进 8554：

ffmpeg -re -stream_loop -1 -i file.mp4 -c copy \ -f rtsp rtsp://localhost:8554/mystream

-re按实时速率发帧，-stream_loop -1无限循环，-c copy只改封装不重新编码。推上去的流叫mystream，这个名字以后就是你的"路径名"。

3. 确认画面出来

浏览器打开http://localhost:8888/mystream，几秒内看到file.mp4的画面，说明 RTSP 进、HLS 出这条跨协议链路已经通了。不想开浏览器就用 VLC 直接拉rtsp://localhost:8554/mystream，能看到就说明同一路径同时支持两种协议读取。容器终端里滚出这条路径的 publish/read 日志，也可以当作侧证。

原理速览：一路流经过哪些环节

一句话版本：每路流对应一个路径（path），发布端把数据写进路径，任意读取端从同一路径按自己的协议取走；MediaMTX 在中间只做协议层面的拆包和重新封装，码流本身不动——所以不转码、不重新编码，同一路流被多少客户端、用多少种协议读都不互相影响，流一停路径就自动回收。

全部行为由mediamtx.yml驱动，配置在运行中被修改时会被自动检测到并热生效，已连接的客户端尽量不被断开（机制见 internal/confwatcher/）。

想读源码，看三处就够：

• internal/core/path_manager.go：路径的生命周期中枢，认证、录像、转发等策略都从这里分发
• internal/servers/：各协议的接入端，rtsp/、rtmp/、hls/、webrtc/、srt/、moq/各占一个子目录
• internal/protocols/：协议与封装格式的编解码实现，负责把协议数据帧和内部媒体流互相转换

场景实战：遇到这种需求，改哪一行

摄像头接网页，低延迟看

需求：安防摄像头只说 RTSP，前端想低延迟播放。

在mediamtx.yml的paths下加两条：

paths: my_camera: source: rtsp://user:pass@摄像头IP:554/stream1

做完得到两个地址：http://主机:8889/my_camera（WebRTC，低延迟）和http://主机:8888/my_camera（HLS，默认lowLatency变体，延迟在秒级）。MediaMTX 会持续从摄像头拉流，你只负责分发。

录像怎么开，回看怎么开

需求：直播要留档，事后还能按时间段回看。

paths: my_camera: record: yes

文件按recordPath模板（默认./recordings/%path/%Y-%m-%d_%H-%M-%S-%f_%z）自动分段落盘，格式在recordFormat里二选一：fmp4或mpegts，保留期由recordDeleteAfter控制（默认 1 天）。要回看的话再全局加一行playback: true，9996 端口的回看服务会列出/list和/get两个接口，浏览器直接指向get返回的 fMP4 地址就能拖动播放，细节见 docs/2-features/10-playback.md。

流不常在线：有人看才拉

需求：源端带宽贵或者不稳定，不想 24 小时挂着空拉。

paths: my_camera: source: rtsp://... sourceOnDemand: yes

效果：第一个读者进来才开始拉流，读者全部离开一段时间后自动断开，省下的就是这段空拉带宽。

把流推给别家系统

需求：同一路流还要分发给下游的录制或转推平台。

paths: my_camera: forward: - rtsp://user:pass@外部主机:554/mystream

forward是个列表，可以写多行，支持 RTSP、RTMP、SRT、MoQ、WebRTC WHIP 等目标地址。

进阶配置：打开什么，得到什么

上公网前，先把认证配上

默认authMethod: internal，账号写在配置里。最小可用的锁法：

authInternalUsers: - user: cam1 pass: 某个密码 permissions: - action: publish path: my_camera - action: read

publish、read、playback三种动作可以分别授权，path支持正则（波浪号前缀）和ips白名单，能把权限钉到具体路径。已有身份体系就别再造账号：authJWTJWKS指向 JWKS 地址走 JWT，或authHTTPAddress指向一个回调接口走 HTTP 校验，每次动作实时裁决。

监控和在线管理：两个端口的事

metrics: true # 9998 api: true # 9997

metrics: true之后，9998 端口出 Prometheus 格式的指标，接上你的监控面板就能量化观察每路流的长期状态；api: true之后，9997 端口的 Control API 允许在线增删路径、查看路径当前状态，改配置不用走文件——接口定义见 docs/5-references/2-control-api.md。

单机带宽不够：多节点怎么拆

核心思路是动态注册：用runOnDemand让路径在被读时才启动推流进程，或者用 Control API 把远端流的 URL 注册成本机路径，让多台边缘节点各自承接就近的读者。完整分布式拓扑画在 docs/2-features/19-scalability.md，照着拼即可。

常见问题：现象、原因、解法

Docker 里 RTSP 连得上、拉不到数据现象：容器内客户端 RTSP 握手正常，但就是没有媒体数据。 原因：RTSP over UDP 依赖包里的真实源地址和端口来定位会话，容器网络栈会改写这些信息，服务端认不出这个客户端。 解法：启动时加-e MTX_RTSPTRANSPORTS=tcp强制走 TCP；或者用--network=host绕过容器网络。

WebRTC 握手成功，画面是黑的现象：浏览器里 8889 的页面连接显示成功，但没有画面。 原因：握手走 HTTP，媒体走 UDP；客户端拿到的候选地址对它是不可达的——webrtcAdditionalHosts没填，或 UDP 8189 被防火墙挡了。 解法：把宿主机对客户端可见的 IP 填进webrtcAdditionalHosts，并放行 UDP 8189。

iOS 等 Apple 设备上 LL-HLS 不出画面现象：HLS 地址在其他播放器正常，iPhone、iPad 上黑屏。 原因：Apple 设备要求 HTTPS 才启用 LL-HLS 的低延迟特性。 解法：hlsEncryption: true配上server.key和server.crt；本地调试想先出画面的话，临时把hlsVariant切成mpegts。

改了配置没生效现象：编辑了mediamtx.yml，行为还是旧的。 原因：热重载靠文件监听自动检测，前提是容器里挂载的那份文件就是你正在改的那份；用环境变量传的参数不在监听范围内。另外监听地址这类项本来就不支持热改。 解法：核对挂载路径，改完保存文件即自动生效；监听地址变了就重启容器。

推了流，HLS 地址却打不开现象：ffmpeg 那边一直在推，8888 的页面却报错。 原因：HLS 服务是只读端，不能用它推流；你大概率把验证用错了方向。 解法：推流验证走rtsp://localhost:8554/路径名（VLC 拉一下即可），或者看容器日志里有没有 publish 记录。

去哪里继续挖

完整配置参考在 docs/5-references/1-configuration-file.md，Control API 在 docs/5-references/2-control-api.md，安装方式全集见 docs/1-kickoff/2-install.md。录像、回看、热重载分别有 09-record.md、10-playback.md、05-configuration.md；协议转换的边界在 07-remuxing-reencoding-compression.md，多节点拓扑在 19-scalability.md，各协议的发布和读取指南在 docs/3-publish/ 与 docs/4-read/。

学习路径建议：先把"五分钟"那三步真正跑一遍，再按当前最痛的场景翻对应章节，改任何配置项之前先到参考文档里对一下它的取值边界。

【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx