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/mediamtxMediaMTX 是一款支持 RTSP、RTMP、WebRTC、SRT、HLS、MPEG-TS、RTP 的多协议实时媒体服务器可以把一路摄像头流同时分发给不同协议的客户端也能做转发与录制。这篇指南按先定场景、再选路径、最后落地的顺序讲清 MediaMTX 跨平台部署的完整过程先给你一张按使用场景划分的决策表再讲与平台无关的通用要点最后是 Linux、Windows、macOS 三平台速览、容器化方案、树莓派边缘部署和一组高频排障问答看完就能在自己的环境里跑起来。1. 先看场景再选路径选型的第一步不是操作系统而是用途。按下面的表对号入座后面各节再展开对应路径的细节。场景推荐部署路径最低硬件主要注意点家庭监控1~2 路摄像头Linux 服务器或树莓派 4/5 官方 Docker 镜像双核 2GB RAM树莓派 4 建议 4GB摄像头只推流不取流时用sourceOnDemand省带宽办公室演示 / 培训Windows 10/11 直接运行mediamtx.exe四核 8GB程序目录避开中文与空格路径中小生产环境几十路并发Linux 裸机或 Docker 容器systemd/容器编排保证自启八核 16GB千兆网卡文件描述符上限要放开UDP 缓冲按需调大边缘设备 / 树莓派MediaMTX 树莓派 ARM 版官方交叉编译树莓派 4 以上2GB RAM 起步关闭用不到的协议录制写外接存储判断逻辑很简单要长期对外服务就选 Linux裸机或容器都行只是临时用就 Windows/macOS 直接跑二进制跑在树莓派上就用 ARM 构建版本。2. 三个平台通用的要点平台无关的事情只讲一次端口、配置结构、服务化。2.1 端口规划默认开启的监听端口如下规划防火墙规则时直接照着开即可rtpAddress是一个端口范围默认 8000/8001 起随并发增长不是单一端口。用途默认端口协议RTSP 接入8554TCPRTMP 接入1935TCPHLS 分发8888TCP/HTTPWebRTC 信令8889TCP/HTTPWebRTC 媒体ICE8189UDPSRT 接入8890UDP管理 API9997默认关闭TCP/HTTPPrometheus 指标9998默认关闭TCP/HTTPWebRTC 低延迟场景尤其注意 8889 和 8189 要同时放通缺一个 UDP 端口信令能通、媒体建立不了。2.2 配置文件骨架配置文件就两部分pathDefaults是所有流的默认值paths下每个 key 是一路流路径名的覆盖项。完整参数清单带注释的模板在仓库根目录的mediamtx.yml新建配置时建议从它裁剪而不是从零写。pathDefaults: source: publisher # 流由客户端推入也可改成 rtsp://... 由服务端拉取 record: false paths: cam1: source: rtsp://user:pass192.168.1.50:554/stream sourceOnDemand: yes record: yes上面这段把cam1配成有人看才去拉、并录制source写错地址时流会一直处于离线状态但服务本身不报错要查日志定位。2.3 环境变量覆盖与参数命名MediaMTX 支持用MTX_前缀的环境变量覆盖任意参数参数名转大写嵌套用_连接。比如把拉流源换成测试流不用改配置文件MTX_PATHS_TEST_SOURCErtsp://myurl ./mediamtx容器部署时这是最顺手的注入方式——镜像不动配置全走环境变量和挂载。2.4 服务化自启动 崩溃重启思路统一用平台的原生服务机制注册一个跑mediamtx 配置文件的进程并开启失败自动重启。Linux 用 systemd这是生产部署的标准动作单元文件核心就是启动命令、文件描述符上限和重启策略[Service] Usermediamtx WorkingDirectory/opt/mediamtx ExecStart/opt/mediamtx/mediamtx /opt/mediamtx/mediamtx.yml Restartalways RestartSec5 LimitNOFILE100000并发高的场景LimitNOFILE100000不是可选项默认值下几百个连接就会撞上文件描述符上限。Windows 下用 NSSM 做同样的事macOS 用 launchd思路完全一致注册、自启、崩溃拉起。3. 平台速览3.1 Linux生产环境的主力结论功能全、性能稳树莓派摄像头源也只在这里可用生产部署首选。发布版是静态编译的单二进制解压即可运行没有运行时依赖自己从源码编译用make build或make static。systemd 注册服务 Restartalways是标配见 2.4 节。UDP 收发量大时按实际并发调大udpReadBufferSize能直接降低丢包。多路并发建议同时放开系统层面的nofile限制而不只改 systemd 单元。最小可用配置示例rtsp: true rtmp: true webrtc: true paths: ipcam: source: rtsp://192.168.1.100:554/stream sourceOnDemand: yes3.2 Windows演示与桌面集成够用结论单文件即用适合临时演示和办公内网不建议跑长期高并发生产服务。解压发布包得到mediamtx.exe和mediamtx.yml当前目录运行即可。专属坑程序与配置文件所在路径不要包含中文和空格否则服务化注册和日志落盘都可能出问题出现异常时先挪目录再查配置。注册为 Windows 服务推荐 NSSMnssm install MediaMTX C:\mediamtx\mediamtx.exe C:\mediamtx\mediamtx.yml。需要 FFmpeg 当拉流源时把 ffmpeg 装进 PATHrunOnInit里的命令才不会找不到可执行文件。paths: webcam: source: udpmpegts://:5004 rtsp: true webrtc: true这里用 MPEG-TS/UDP 收流是为了绕开Windows 上没有现成摄像头源的问题让 FFmpeg 或摄像头推 UDP 5004 端口MediaMTX 负责协议转换。3.3 macOS开发机首选结论适合本地开发和联调摄像头权限是主要门槛。发布包区分 Apple Silicon 与 Intel下错架构装不上或跑不满性能。专属坑摄像头访问要在系统设置 → 隐私与安全性 → 摄像头里给终端/相关应用授权MediaMTX 本身不会弹出授权框表现为推流端黑屏或无流。开机自启用 launchd 配置KeepAlive效果等同 systemd 的Restartalways。局域网调试时注意系统防火墙首次运行会弹框允许入站连接否则 WebRTC 对端永远连不上。4. 容器化生产部署的默认选项结论跨平台一致性最好、回滚最省事MediaMTX Docker 部署应作为生产环境的默认路径而不是退而求其次。官方镜像bluenviron/mediamtx:1基于scratch构建内置 linux/amd64、armv6/v7/arm64 四个架构的二进制docker run时自动按宿主机架构选包同一份 Compose 从 x86 服务器到树莓派都能跑。容器内约定二进制在/mediamtx默认配置文件路径也是/mediamtx.yml挂载时对着放即可。一条命令先验证环境docker run --rm -it --networkhost bluenviron/mediamtx:1起来后 9997 端口若开启 API和日志应正常然后关掉它换成下面的 Compose 方式常驻。生产环境的完整写法services: mediamtx: image: bluenviron/mediamtx:1 restart: unless-stopped ports: - 8554:8554 # RTSP - 1935:1935 # RTMP - 8888:8888 # HLS - 8889:8889 # WebRTC 信令 - 8189:8189/udp # WebRTC 媒体 volumes: - ./mediamtx.yml:/mediamtx.yml - ./recordings:/mediamtx/recordings environment: MTX_LOGLEVEL: info注意8189必须声明/udp漏了这条 WebRTC 媒体就建不起来症状是浏览器能打开页面但黑屏。录制目录建议挂到宿主机固定路径容器重建不丢文件。4.1 补充树莓派等边缘设备结论MediaMTX 树莓派部署走 ARM 交叉编译或官方 arm64 镜像核心动作是砍功能 外置存储。构建仓库里make build_armv732 位系统或make build_arm64产物是单二进制拷上去就能跑也可以直接用官方 arm64 镜像。只留需要的协议把rtmp、srt、moq等设为false省下监听端口和少量内存。摄像头直接接树莓派时用内置源配置比拉流简单paths: camera: source: rpiCamera rpiCameraWidth: 1280 rpiCameraHeight: 720 rpiCameraFPS: 25 record: yes recordPath: /media/usb/recordings/%pathrecordPath指向外接 USB 盘SD 卡的写入寿命扛不住持续录制。日志级别降为warn、关掉api/metrics能再省一点开销。5. 高频问题排障每条按症状 → 先查什么 → 怎么处理展开覆盖部署中最常遇到的几类。启动报端口被占用。先查 8554/1935/8889 谁在用Linux 用sudo lsof -i :8554Windows 用netstat -ano | findstr 8554。是另一个 MediaMTX 实例就杀掉是别的软件就在配置文件里改掉对应*Address。WebRTC 客户端一直转圈建连。先查 8189/UDP 是否放通、服务器是否有公网可达 IPNAT 后面无法直达时在webrtcICEServers2里配置 STUN 或 TURN。source指向的拉流源一直离线。先确认 URL 能被人肉拉下来用 VLC 验证账号密码和地址自签名证书的场景要填sourceFingerprint否则 TLS 校验会静默失败。Windows 下服务注册成功但起不来。九成是路径问题把程序挪到无中文、无空格的目录如C:\mediamtx再看服务日志定位真实错误。macOS 摄像头有画面但流是黑的。去系统设置里给终端应用开摄像头权限后重启进程再确认 FFmpeg 取流参数与设备编号匹配。并发升高后 UDP 丢包。查dmesg/系统日志里有没有 socket 缓冲区溢出告警调大udpReadBufferSize同时确认writeQueueSize与内存余量是否匹配该参数决定每个连接的待发队列长度。管理 API 打不开。默认api: false是关着的先确认配置里打开了、9997 端口可达另外默认只有本机 IP 能访问 api/metrics远程访问要先在authInternalUsers里授权。6. 部署后动作与选型收束选型三句话长期对外服务选 Linux 裸机或容器临时演示选 Windows 或 macOS 直接跑二进制跑在树莓派上就用 ARM 构建版本并砍掉用不到的协议。四条收尾清单安全对外端口启用对应协议的 TLS如webrtcEncryption、rtspEncryptionAPI 与 metrics 只暴露给内网或加认证authInternalUsers里按最小权限配置。监控开启metrics: true用 Prometheus 抓取 9998 端口的连接数与字节速率日志落文件便于回溯。性能按并发调udpReadBufferSize、writeQueueSize和系统文件描述符上限这三个是调优的第一梯队。版本配置备份后升级升级前浏览仓库内的 release notes 与安装文档 确认有无破坏性变更MediaMTX 的参数偶尔重命名旧配置直接沿用可能静默失效。延伸阅读仓库内路径带完整注释的配置参考mediamtx.yml配置机制与环境变量说明docs/2-features/05-configuration.md功能总览目录docs/2-features/【免费下载链接】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），仅供参考