MediaMTX 配置完全指南：配置文件、环境变量、Control API 与加密实践

MediaMTX 配置完全指南配置文件、环境变量、Control API 与加密实践【免费下载链接】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、HLS、WebRTC、SRT、MoQ 等协议发布、读取、转发和录制音视频流。本篇文章聚焦于 MediaMTX 的配置体系如何通过编辑mediamtx.yml配置文件、设置MTX_*环境变量以及调用 Control API 三种方式来管理服务器行为并深入讲解配置文件加密与热重载的实现原理。读完本文你将掌握 MediaMTX 从静态配置到运行时动态调整、再到安全加固的完整配置能力。配置体系概览一切以mediamtx.yml为基准MediaMTX 的所有配置参数都集中在一个 YAML 文件中定义即仓库根目录下的 mediamtx.yml。该文件对每一个参数都附有详细的注释说明是学习和查阅参数含义的第一手资料同时项目还维护了一份与最新发布版本同步的 配置参数参考文档供在浏览器中快速检索。从 mediamtx.yml 的内容结构可以看出配置分为几个大的逻辑区域全局设置日志logLevel、logDestinations、logFile、读写超时readTimeout、writeTimeout、UDP 报文参数udpMaxPayloadSize、udpReadBufferSize、连接回调命令runOnConnect、runOnDisconnect等认证相关authMethodinternal / HTTP / JWT 三种模式以及authInternalUsers、authHTTPAddress、authJWTJWKS等配套参数各协议服务器Control APIapi、Metricsmetrics、PPROFpprof、Playbackplayback、RTSPrtsp*、RTMPrtmp*、HLShls*、WebRTCwebrtc*、SRTsrt*、MoQmoq*各自的启用开关、监听地址、加密与 TLS 证书路径默认路径设置pathDefaults作用于所有路径的通用参数例如流来源source、按需拉流sourceOnDemand、转发forward、录制record*、钩子命令runOn*、树莓派摄像头rpiCamera*等路径设置paths以路径名为 key 的映射表可为特定路径或通过~前缀的正则表达式覆盖pathDefaults中的任意参数。文件末尾的all_others是一个特殊路径用于兜底所有未匹配的路径。下面我们将逐一介绍修改这些配置的三种官方途径。方式一编辑配置文件与热重载修改配置最直接的方式就是编辑mediamtx.yml文件本身。该文件已包含在 MediaMTX 的官方发布包中位于 Docker 镜像的根目录/mediamtx.yml可以通过卷挂载的方式用宿主机上的自定义文件覆盖例如docker run --rm -it --networkhost -v $PWD/mediamtx.yml:/mediamtx.yml:ro bluenviron/mediamtx:1注意这里使用了:ro只读挂载宿主机当前目录下的mediamtx.yml会替换镜像内的默认配置。热重载运行中修改无需重启MediaMTX 支持配置热重载hot reloading当服务器正在运行时直接向配置文件写入新的内容服务器会自动检测到文件变化并应用新配置且在不影响现有客户端连接的前提下完成切换凡是可能保持的连接都会被保留。这一能力在源码层面由 internal/confwatcher/confwatcher.go 实现它基于fsnotify库监听配置文件所在目录的文件系统事件并对事件做了去抖处理最小间隔 1 秒、额外等待 10 毫秒见常量minInterval与additionalWait从而避免频繁写入或编辑器保存操作引发的抖动。监听建立后任何对配置文件的写入都会触发配置重载流程。由于配置文件变更不会断开已有会话因此非常适合在生产环境中边改边生效例如临时调整某个路径的录制开关或日志级别。方式二使用环境变量覆盖配置MediaMTX 的每个配置参数都可以通过同名环境变量覆盖命名规则为MTX_PARAMNAME其中PARAMNAME是参数名的大写形式。例如覆盖rtspAddress参数只需MTX_RTSPADDRESS127.0.0.1:8554 ./mediamtx不同值类型的映射规则根据值类型的不同环境变量的写法略有区别完整规则如下表所示参数类型环境变量写法示例标量字符串、数字、布尔MTX_参数名大写MTX_RTSPADDRESS127.0.0.1:8554数组逗号分隔的字符串列表逗号分隔的列表MTX_RTSPTRANSPORTStcp,udp映射map用下划线_分隔层级MTX_PATHS_TEST_SOURCErtsp://myurl列表list元素为结构体用位置下标作为额外的键MTX_AUTHINTERNALUSERS_0_USERusername数组类型可以直接用逗号分隔的字符串整体赋值。例如设置 RTSP 传输协议MTX_RTSPTRANSPORTStcp,udp映射类型通过下划线逐层深入。例如为paths映射中名为test的路径设置source参数MTX_PATHS_TEST_SOURCErtsp://myurl ./mediamtx这等价于在 YAML 中写paths: test: source: rtsp://myurl列表类型与映射类似但需要额外用元素的下标来定位。这一点在使用内部用户认证但希望把凭据放到环境变量中的场景下尤其实用MTX_AUTHINTERNALUSERS_0_USERusername MTX_AUTHINTERNALUSERS_0_PASSpassword这等价于在authInternalUsers列表中定义第一个用户username/password。下标从 0 开始递增MTX_AUTHINTERNALUSERS_0_*、MTX_AUTHINTERNALUSERS_1_*以此类推。环境变量解析的源码原理环境变量的解析逻辑集中在 internal/conf/env/env.go 中。它通过反射reflect递归遍历配置结构体根据字段类型走不同的分支字符串、整数、浮点数、布尔分别调用对应的解析函数布尔值同时接受yes/true与no/false两种写法见env.go中布尔分支结构体字段的 JSON tag 会被转成大写并追加到当前前缀之后形成形如MTX_RTSPADDRESS的键映射类型通过prefix_键名的前缀匹配识别且只接受全大写的键避免与配置文件中的其他内容混淆结构体切片list则按prefix_下标逐项填充这正是MTX_AUTHINTERNALUSERS_0_USER这类写法能够工作的根本原因见env.go中case rt.Elem().Kind() reflect.Struct分支的循环逻辑。项目测试 internal/conf/conf_test.go 中对此有直接验证例如MTX_PATHS_CAM1_SOURCE、MTX_RTSPTRANSPORTS、MTX_AUTHINTERNALUSERS_0_IPS等用例均覆盖了环境变量覆盖配置的路径。Docker 场景下的环境变量环境变量的方式在 Docker 部署时格外方便——不需要维护配置文件直接用-e参数传入即可覆盖任意配置项docker run --rm -it --networkhost -e MTX_PATHS_TEST_SOURCErtsp://myurl bluenviron/mediamtx:1方式三通过 Control API 动态控制第三种方式是通过 Control API 在运行时查询和控制服务器。先在配置中启用 API 服务api: yes然后即可发起 HTTP 请求。例如获取当前所有活动路径的列表curl http://127.0.0.1:9997/v3/paths/listControl API 的默认监听地址是:9997见 mediamtx.yml 中的apiAddress参数完整的接口定义参见 Control API 参考文档 以及仓库中的 OpenAPI 规范文件。需要留意的是默认情况下 Control API 只允许 localhost 访问若要对外暴露或加上认证请参考 认证配置。配置的三种修改方式定位各不相同可按下表理解其适用场景方式适用场景生效时机编辑mediamtx.yml静态、声明式的完整配置可版本化启动时加载运行中写入可热重载MTX_*环境变量容器化部署、临时覆盖、凭据不入文件进程启动时Control API运行时查询状态、动态下发变更即时加密配置文件用MTX_CONFKEY保护敏感参数当配置中包含密码、Token、密钥等敏感信息例如内部用户的pass、转发目标的dest凭据、WebRTC 的 TURN 凭据等时MediaMTX 允许将整个配置文件加密存储防止配置内容以明文形式散落在磁盘上。加密的具体要求如下使用 NaCL 库的crypto_secretbox函数对整个配置文件内容进行加密将加密结果的base64 编码放入配置文件中替换原来的明文 YAML启动服务器时通过环境变量MTX_CONFKEY提供解密密钥MTX_CONFKEYmykey ./mediamtx服务器启动后加载流程会先用MTX_CONFKEY对配置文件内容解密再按 YAML 解析这一逻辑可以在 internal/conf/conf.go 的loadFromFile方法中看到它读取文件字节后检查环境变量MTX_CONFKEY同时兼容历史变量名RTSP_CONFKEY若存在则调用decrypt.Decrypt解密见internal/conf/conf.go的loadFromFile实现以及 internal/conf/decrypt/decrypt.go。测试用例 internal/conf/conf_test.go 中还原了完整的加密-加载链路用secretbox.Seal加密明文、base64.StdEncoding.EncodeToString编码后写入临时文件再加载并断言配置解析成功。这说明加密配置在官方实现中是受完整支持的一等公民功能。需要注意的边界情况配置文件一旦加密就无法再被人工直接阅读和编辑必须先解密再修改、重新加密因此适合凭据由密钥管理系统托管、配置文件整体保密的安全敏感场景。配置加载与校验的底层保障理解配置系统的底层行为有助于规避常见的踩坑点。从 internal/conf/conf.go 的实现可以看出文件查找loadFromFile会在显式指定的路径或默认路径中查找配置文件若未显式指定且默认路径都不存在配置是可选的见loadFromFile中对空路径的处理。参数校验Validate方法会对参数做严格校验并给出明确报错。例如readTimeout、writeTimeout必须大于零writeQueueSize必须是 2 的幂(conf.WriteQueueSize (conf.WriteQueueSize - 1)) ! 0时报错udpMaxPayloadSize必须小于 1472等等。这意味着错误配置会在启动阶段就被拦截而不是带病运行。废弃参数迁移旧的参数名会被自动转换为新参数并打印警告日志例如readBufferCount已由writeQueueSize取代、encryption已由rtspEncryption取代见Validate中相关的deprecated处理保证老配置在升级后仍能平滑工作。总结一套配置三种入口MediaMTX 的配置体系围绕单一事实来源mediamtx.yml构建同时提供环境变量与 Control API 作为运行时补充入口配置文件适合声明式管理和热重载环境变量适合容器化部署与临时覆盖支持数组、映射和带下标的结构体列表Control API 则用于运行时查询与动态控制。对于安全敏感部署还可以用 NaCLcrypto_secretbox配合MTX_CONFKEY对配置整体加密。掌握这几种入口及其映射规则就能在开发、测试和生产环境中灵活、安全地驾驭 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考