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
MediaMTX 是一个开箱即用的零依赖直播媒体服务器与媒体代理，用单个可执行文件就能发布、读取、录制和回放 RTSP、RTMP、WebRTC、HLS、SRT、MoQ 协议的音视频流，并自动完成协议之间的转换。想接一路摄像头给多个播放器同时看，它是目前最短的实现路径。
📌 一分钟看懂：MediaMTX 是什么、适合谁
MediaMTX 的定位是"媒体路由器"：一路流从某个协议进来，它负责分发给所有协议、所有读者。
| 角色 | 用它做什么 |
|---|---|
| 安防/监控工程师 | 把 RTSP 摄像头转成 WebRTC/HLS，网页和手机直接看，不用转码 |
| 直播开发者 | 一路推流（RTMP/RTSP/SRT）同时供多协议拉流，省掉自建多套服务器 |
| 新手 | 不用装依赖、不用写代码，改一个 YAML 就能跑 |
它的核心行为只有四条：
- 每路流对应一个"路径"（path），路径名即流名，所有协议共用同一个名字；
- 输入和输出协议可以不同，比如 RTSP 推入、HLS 读出；
- 支持把流录制为 fMP4 或 MPEG-TS 文件存盘，事后可通过回放接口下载；
- 修改配置文件时热加载生效，不断开已有连接。
适合谁：需要在一个进程里解决多协议分发、录播、鉴权问题的团队；不适合需要复杂转码、AI 分析的场景——它只做封装层（remuxing），不改码流。
🚀 安装、启动并验证 MediaMTX
整个流程分三步：拿到二进制、启动、打开内置网页验证。
第一步：获取可执行文件。MediaMTX 不依赖任何运行时，产物就是一个mediamtx（Windows 为mediamtx.exe）。可以先克隆项目仓库，查看默认配置模板和文档：
git clone https://gitcode.com/GitHub_Trending/me/mediamtx cd mediamtx仓库根目录的mediamtx.yml就是默认配置。要运行，还需从项目的发布包（Releases 页）下载与你的系统匹配的独立二进制；各安装方式的详细步骤见 安装文档。
第二步：启动。默认配置零修改即可运行：
./mediamtx启动后，它按mediamtx.yml的默认值监听各协议端口：
| 协议 | 端口 |
|---|---|
| RTSP（TCP） | 8554 |
| RTMP（TCP） | 1935 |
| HLS（HTTP） | 8888 |
| WebRTC（HTTP） | 8889 |
| SRT（UDP） | 8890 |
| MoQ（HTTP/QUIC） | 8892 / 8893 |
| WebRTC ICE（UDP） | 8189 |
第三步：验证。打开浏览器访问http://localhost:8889，会看到 MediaMTX 内置的 WebRTC 网页播放器；访问http://localhost:8892则是内置的 MoQ 网页客户端。页面能打开，说明服务器已正常工作。此时还没有流可播，这是正常的——下一步才推流。
⚙️ 看懂最小可用配置：mediamtx.yml 里只需理解两块
mediamtx.yml很长，但新手阶段只需要理解"全局开关"和"路径"两块，其余参数保持默认即可。
第一块：全局开关。每个协议都是协议名: true/false的形式，配一个xxAddress指定端口。例如想关掉 RTMP，把rtmp: true改成false即可。日志用logLevel（error/warn/info/debug）和logDestinations（stdout/file/syslog）控制。
第二块：路径。这是配置的核心，分两层：
paths: demo: # 路径名即流名 source: publisher # 流由客户端推入 record: true # 开启录制pathDefaults段是全路径的默认值（默认source: publisher，即等待客户端推流），paths段按路径名覆盖。source还能直接写成外部地址，如rtsp://摄像头IP/stream，此时 MediaMTX 变成主动拉流；支持 RTSP、RTMP、SRT、HLS、MoQ、UDP+MPEG-TS 等多种来源写法，完整清单见 配置参数参考。
两个省事的特性值得记住：
- 热加载：保存配置文件即生效，不用重启，已有连接不受影响；
- 环境变量覆盖：任意参数可用
MTX_参数大写名覆盖，如MTX_RTSPADDRESS="127.0.0.1:8554" ./mediamtx，Docker 部署时特别方便。
另外注意：默认鉴权允许任何用户推流和拉流，只在本地回环 IP 开放 API。要暴露到内网或公网前，请配置authInternalUsers，或用外部 HTTP / JWT 鉴权。
🎬 跟练实战：推入第一路流，用三种方式读出来
这个案例走一遍完整链路：FFmpeg 推 RTSP → 服务器转换 → RTSP/HLS/文件三种方式消费，同时验证录制功能。
1. 配置路径并开启录制。编辑mediamtx.yml，保存后热加载自动生效：
paths: demo: source: publisher record: true recordPath: ./recordings/%path/%Y-%m-%d_%H-%M-%S recordSegmentDuration: 5m2. 用 FFmpeg 把一个 MP4 循环推成直播流。这条命令以原始码率（-c copy）通过 RTSP 推到本机 8554 端口的demo路径：
ffmpeg -re -stream_loop -1 -i demo.mp4 -c copy -f rtsp rtsp://localhost:8554/demo推流端也可以在推流软件里换成 RTMP：地址填rtmp://服务器IP:1935/demo，流名demo。
3. 多协议读出同一路流。路径名不变，换协议换端口即可，这就是"自动协议转换"的实际效果：
- VLC 播放 RTSP：
vlc --network-caching=50 rtsp://localhost:8554/demo - FFmpeg 拉 RTSP 存文件：
ffmpeg -i rtsp://localhost:8554/demo -c copy out.mp4 - HLS：用浏览器或 FFplay 访问 8888 端口下
demo路径对应的 m3u8 地址，具体地址格式见 HLS 读取文档
4. 检查录制。流在播期间，./recordings/demo/目录下会按recordSegmentDuration切出 fMP4 分片文件。全部读者断开后，分片收尾成完整段。
做完这一步，你已经掌握了 MediaMTX 的完整闭环：推入、转换、读取、录制。
🛠️ 避坑：启动、跨网、配置三类高频问题
按"症状 → 原因 → 修法"看这四个最常见的问题。
问题 1：启动报端口被占用。原因：8554（RTSP）、1935（RTMP）与常见服务冲突。 修法：改mediamtx.yml中对应xxAddress，或临时用MTX_RTSPADDRESS=":9554" ./mediamtx覆盖。
问题 2：Docker 里 RTSP 推流偶发失败。原因：Docker 网络栈会替换入站 UDP 包的来源 IP/端口，RTSP 的 UDP 传输依赖它。 修法：按官方安装文档设置MTX_RTSPTRANSPORTS=tcp禁用 UDP 传输，或改用--network=host运行容器。
问题 3：同一内网能播，跨网段/跨 NAT 的 WebRTC 连不上。原因：客户端收不到可达的服务器地址，ICE 握手中缺少公网信息。 修法：在配置里给webrtcAdditionalHosts填上客户端实际访问的公网 IP；若本地端口不通，再配webrtcICEServers2引入 STUN/TURN。
问题 4：改了配置不生效，或录制文件越积越多。原因：热加载在"尽可能"的前提下生效，个别结构性改动需要重启；录制默认只保留 1 天，长期运行后磁盘行为由recordDeleteAfter控制。 修法：关键改动后重启一次最稳妥；按存储预算调整recordSegmentDuration与recordDeleteAfter（设为0s则不自动删除）。
更多疑难可以开着logLevel: debug复现问题，日志里带连接 ID，方便对照行为。
🧭 往下走：监控、回放与更多扩展
跑通第一路流之后，建议按这个顺序扩展：
- 全量参数：配置参数参考 列出了每个参数的默认值与说明，遇到不认识的配置名直接查这里；
- Control API 与 metrics：把
api: true（端口 9997）和metrics: true（端口 9998）打开，就能用 HTTP 管理路径、用 Prometheus 抓取mediamtx_前缀指标做告警； - 回放：把
playback: true（端口 9996）打开，即可通过/list和/get接口按时间段下载已录制的流，fMP4 格式可直接放进浏览器<video>标签； - 协议进阶：架构文档 解释了路径管理器、路径、录制器三大组件的关系，是理解"流到底怎么被路由"的入口。
MediaMTX 的设计哲学是把复杂留在服务端：你只需要记住"路径名即流名"这一条规则，剩下的协议、端口、格式转换都由它兜底。从今天的demo路径出发，换一行source配置就能接入真实摄像头，这套上手路径可以直接照搬到生产环境。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
