MediaMTX 快速上手：单二进制多协议直播流分发、录制与回放服务器-开发者社区

MediaMTX 快速上手：单二进制多协议直播流分发、录制与回放服务器

【免费下载链接】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、Web 前端却只认 WebRTC 或 LL-HLS 时，两者之间总需要一个中间层做桥接。MediaMTX 是一个开箱即用的实时流媒体服务器：单个零依赖二进制文件，负责把 RTSP、RTMP、HLS、WebRTC、SRT、MoQ 等协议的流发布、读取、录制和回放，并在协议之间做转封装，不做转码。

🧰 MediaMTX 项目速览：它是什么、工程上有什么特征

定位是"媒体路由器"：每条流绑定一个路径（path），发布端写入路径、读取端从同一路径读出，中间完成协议转换；同一条流可被多个客户端用不同协议同时读取，互不影响。
单二进制、零运行时依赖：Go 编写，不需要数据库和解释器，Linux、macOS、Windows 通用，官方 Docker 镜像为bluenviron/mediamtx:1。
默认全开，开箱即用：RTSP 8554、RTMP 1935、HLS 8888、WebRTC 8889、SRT 8890 五个端口默认监听，首次启动不用改任何配置。
行为全部由mediamtx.yml一个 YAML 文件驱动，且支持热重载：文件变更由文件监听（internal/confwatcher/）自动检测，多数路径级参数改动不中断现有连接。
路径动态存在：一条路径同时挂一个发布源和任意多个读取端，认证、录制、转发策略都从路径层分发。

🚀 五分钟跑起 MediaMTX：Docker 最小启动步骤

生产环境推荐 Docker 镜像，一条命令起服务（MTX_RTSPTRANSPORTS=tcp是为避免容器网络干扰 RTSP 的 UDP 传输）：

docker run --rm -it \ -e MTX_RTSPTRANSPORTS=tcp \ -p 8554:8554 -p 1935:1935 \ -p 8888:8888 -p 8889:8889 \ -p 8890:8890/udp -p 8189:8189/udp \ bluenviron/mediamtx:1

成功长什么样：容器进程持续驻留、日志里各协议监听器依次启动、没有任何端口绑定错误。

再准备一条推流源，用 FFmpeg 把任意 MP4 以 RTSP 推入 8554 端口：

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

成功长什么样：ffmpeg 持续输出转发帧信息且进程不报错退出。

验证方式：浏览器打开http://localhost:8888/mystream，能看到画面即说明 RTSP 发布到 HLS 读取的链路已通；用 VLC 拉rtsp://localhost:8554/mystream也能读到同一条流——同一路径、两种协议，这就是它的基本用法。

🎬 MediaMTX 核心能力拆解：四类场景各需要一段配置

把 RTSP 摄像头接进网页，按需拉流

安防摄像头只说 RTSP，你想在浏览器里低延迟观看，又不想写转发程序。给路径配一个source，MediaMTX 就负责持续拉流并做协议适配，你得到一个 WebRTC 播放页http://主机:8889/路径名和一个 LL-HLS 地址http://主机:8888/路径名；加上sourceOnDemand: yes后有人读才拉流、没人读自动断开，省带宽：

paths: cam1: source: rtsp://user:pass@192.168.1.64:554/stream1 sourceOnDemand: yes

直播录像自动分段，按时间段回放

需要保留录像备查时，路径级开启录制即可。文件按recordPath模板分段落盘（默认每小时一个段），recordDeleteAfter控制保留期；再全局打开playback: true，9996 端口的回放服务提供/list?path=cam1列出可回放时间段、/get返回 fMP4 流，可直接放进<video>标签（见 docs/2-features/10-playback.md）：

pathDefaults: record: yes recordFormat: fmp4 recordDeleteAfter: 1d playback: true playbackAddress: :9996

一条流同时推给多个外部平台

流要分发给别家系统时，forward列表支持 RTSP、RTMP、SRT、MoQ、WebRTC WHIP 等目标，一条路径可配多个目标，无需二次部署：

paths: cam1: forward: - dest: rtmp://live.example.com/app/streamkey - dest: srt://host:port?streamid=streamid

公网暴露前限制发布账号，顺便打开监控

流暴露到公网前需要控制谁能推流。默认authMethod: internal，凭据写在配置里，按publish/read/playback三种动作分配权限，可用正则和ips白名单限制到具体路径；长期运行后再用metrics: true打开 9998 端口的 Prometheus 指标，配合api: true（9997 端口）的 Control API 在线增删路径、查看状态：

authInternalUsers: - user: publisher pass: changeme permissions: - action: publish

🗺️ 看清 MediaMTX 如何运转：路径层与协议转换的数据流

三个目录构成主干：internal/servers/ 是各协议接入端，rtsp、rtmp、hls、webrtc、srt、moq 各占一个子目录，负责握手和数据收发；internal/protocols/ 是协议编解码实现，以及 hls、mpegts 等格式的读写，把协议数据帧与内部媒体流互相转换；internal/core/path_manager.go 是路径管理中枢。数据流是单向的漏斗：协议接入层把发布端帧流解复用成内部媒体流，路径层把它扇出给所有读取端和录制器，每个读取端所在协议层再各自封装成目标协议发出。想看懂一条流的完整生命周期，顺着 path_manager 的 reader/publisher 分发逻辑读即可。

🛠️ MediaMTX 常见配置误区：现象、原因、解法

现象：Docker 里用 UDP 读 RTSP 流读不到或中途断原因：容器网络会改写入站 UDP 包的源地址和端口，RTSP 服务器无法正确匹配数据报解法：启动时加-e MTX_RTSPTRANSPORTS=tcp强制 TCP，或改用--network=host绕过容器网络栈
现象：WebRTC 握手成功但画面黑屏原因：8889 只覆盖 HTTP 握手，媒体面走 UDP 8189，客户端拿不到可达的服务端地址时 ICE 失败解法：把客户端可达的宿主机 IP 填入webrtcAdditionalHosts，并确认 8189/udp 已放行
现象：iPhone 播放 LL-HLS 不出画面原因：hlsVariant默认lowLatency，LL-HLS 在 Apple 设备上要求 HTTPS 才能正常工作解法：hlsEncryption: yes并配置hlsServerKey/hlsServerCert，本地调试可先把hlsVariant切到mpegts
现象：改了mediamtx.yml但部分参数不生效原因：热重载只应用可运行时变更的参数（录制、转发、source 等），协议监听地址等全局项不在其列解法：先跑./mediamtx --validate-conf=mediamtx.yml校验文件，全局参数变更重启进程生效
现象：本机 WebRTC 正常，外网访问失败原因：服务器在 NAT 之后，客户端无法发现可达地址解法：在webrtcICEServers2配置 STUN/TURN 服务器帮助双方交换地址

📚 下一步：文档入口与学习路径

安装方式与四种镜像变体（含 FFmpeg、树莓派摄像头支持）：docs/1-kickoff/2-install.md
全部配置项及默认值参考：docs/5-references/1-configuration-file.md
多节点分布式拓扑与 CDN 扩展：docs/2-features/19-scalability.md

建议的学习路径：先按"五分钟跑起来"跑通一条 RTSP 发布到 HLS 读取的最小链路，再按保留需求开启record与playback；确认要把服务放到公网后，依次配置authInternalUsers与 HTTPS，最后再引入 Control API 和 metrics 做运维，避免一开始就把所有开关都打开。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考