MediaMTX 1.21.3 配置参数详解

目标：把 MediaMTX v1.21.3 的 121 个全局配置参数与 92 个路径默认参数（pathDefaults）按功能域讲透——所有默认值取自运行实例 REST API 的实测回显（/v3/config/global/get），关键参数逐项配实测验证，并给出可落地的生产配置模板。

一、环境信息

本文参数与回显在以下真实环境实测采集（实测日期 2026-10-29）：

操作系统：Ubuntu 22.04（x86_64）
MediaMTX：v1.21.3（官方 linux/amd64 静态二进制，一键化部署方案见《MediaMTX 1.21.3 Docker Compose 部署指南》）
参数采集方式：REST API GET /v3/config/global/get（实测返回 121 个键）与 GET /v3/config/pathdefaults/get（实测返回 92 个键），另对照官方发布包内全量注释配置文件（38940 字节）
实测验证工具：FFmpeg 6.1.1（推拉流）、curl（HTTP/API）

二、前置条件

一台能运行 MediaMTX 的 Linux 服务器（解压即可用，见介绍篇快速开始）；
开启 REST API（api: yes）以便用 API 查看与热改参数——本文大量命令依赖它；
配置文件路径约定：下文以 /opt/mediamtx/mediamtx.yml 为例（MediaMTX 启动时依次在工作目录、/usr/local/etc/mediamtx.yml、/etc/mediamtx/mediamtx.yml 等位置查找，实测启动日志会打印 configuration loaded from <路径>）。

三、参数查看与修改方式

3.1 三种查看方式

① 官方全量注释配置（改参数前的最佳参考）：发布包 tar 里自带 mediamtx.yml，121 个参数全部带英文注释与默认值；② REST API 实时生效值（最权威，所见即所得）：

# 查看 121 个全局参数的当前生效值（需 API 权限账号）
curl -s -u admin:q1w2e3r4 http://127.0.0.1:9997/v3/config/global/get | python3 -m json.tool | head -20

实测回显（节选）：

{
    "api": true,
    "apiAddress": ":9997",
    "apiAllowOrigins": [
        "*"
    ],
    "authHTTPAddress": "",
    ...

（输出节选（实测首尾）：完整响应为 121 键的 JSON，此处截取开头数键） ③ 启动日志：非法参数名会直接在启动日志报警（实测把旧参数 apiAllowOrigin 写进配置，启动即输出 WAR parameter 'apiAllowOrigin' is deprecated and has been replaced with 'apiAllowOrigins'——v1.21 改名后的排障实录）。

3.2 三种修改方式与生效时机

方式	操作	生效时机	实测结论
改配置文件 + 重启进程	编辑 yml 后重启 MediaMTX	重启后	最可靠，全参数可改
环境变量覆盖	键名大写加 `MTX_` 前缀（如 `MTX_LOGLEVEL=debug`）	启动时	实测 DEB 级日志出现即生效；优先级高于 yml
REST API 热更新	`PATCH /v3/config/global/patch`	立即	实测把 logLevel 从 info 改 debug，不重启即时生效

API 热更新实测回显：

curl -s -u admin:q1w2e3r4 -X PATCH http://127.0.0.1:9997/v3/config/global/patch \
  -H 'Content-Type: application/json' -d '{"logLevel":"debug"}'
curl -s -u admin:q1w2e3r4 http://127.0.0.1:9997/v3/config/global/get | grep -o '"logLevel":"[a-z]*"'

{"status":"ok"}
"logLevel":"debug"

💡 说明：布尔参数用 yes/no（yml 中）或 true/false（API JSON 中），时长参数带单位（10s、200ms），与回显一致。

四、参数总览

121 个全局参数按功能域分布（键名与默认值均为 API 实测采集）：

功能域	代表参数	数量级
日志	logLevel、logDestinations、logFile	少量
HTTP 管理面	api、metrics、pprof、playback	~20
认证	authMethod、authInternalUsers、authHTTPAddress、authJWT*	~10
RTSP	rtsp*（地址/传输/加密/握手超时）	~10
RTMP	rtmp*	~4
SRT	srt*	~2
HLS	hls*（变体/分片/加密/源站）	~15
WebRTC	webrtc*（信令/ICE/加密）	~15
MoQ（v1.21 新增）	moq*	少量
协议通用	readTimeout、writeTimeout、writeQueueSize、udpReadBufferSize 等	~10
路径与录制	pathDefaults（92 键）、record*、paths	pathDefaults 独立 92 键

关键差异：全局参数管「服务器行为」，pathDefaults 管「每条路径的默认属性」，paths 段按路径名覆盖 pathDefaults——三层结构，具体路径 > pathDefaults > 内置默认。

五、核心参数分类详解

5.1 日志参数

logLevel: info
logDestinations: [stdout]
logFile: mediamtx.log

logLevel：error/warn/info/debug。生产用 info，排障切 debug（实测 API patch 即时生效，debug 级会输出 DEB path manager created 等内部行为）；
logDestinations：stdout/file/syslog 组合；logFile 为 file 目标的落盘路径。

5.2 HTTP 管理面参数（api/metrics/pprof/playback）

四个独立 HTTP 服务，默认全部关闭（实测 GET /v3/config/global/get：api: true 因实验配置显式开启，metrics、pprof、playback 默认 no）：

api: yes                 # REST 控制 API
apiAddress: :9997        # 实测默认 :9997
apiAllowOrigins: ['*']   # CORS 白名单；⚠️ v1.21 由 apiAllowOrigin 改名为复数，实测旧名触发弃用警告
metrics: yes             # Prometheus 指标
metricsAddress: :9998    # 实测 /metrics 输出 paths{name="cam",state="ready"} 1 等指标
pprof: no                # Go 性能剖析，:9999
playback: no             # 录制回放服务，:9996

实测启用 metrics 后的指标片段（curl -u admin:q1w2e3r4 http://127.0.0.1:9998/metrics，节选）：

# Paths
paths{name="cam",state="ready"} 1
paths_readers{name="cam",readerType="",state="ready"} 0
paths_inbound_bytes{name="cam",state="ready"} 5773613
paths_outbound_bytes{name="cam",state="ready"} 3039552

管理面四端口建议只对内网开放，认证见 5.3。

5.3 认证参数（authMethod / authInternalUsers）

authMethod 默认 internal（实测值），可选 http（外部认证回调 authHTTPAddress）与 jwt（authJWTJWKS 指 JWKS 端点）。内置用户表示例（即本文实测配置，逐项注释）：

authInternalUsers:
  - user: admin          # 管理账号
    pass: q1w2e3r4
    ips: []              # 空 = 不限来源 IP
    permissions:
      - action: publish  # 推流
      - action: read     # 拉流（RTSP/RTMP/SRT/HLS/WebRTC）
      - action: playback # 回放
      - action: api      # REST API
      - action: metrics  # Prometheus
      - action: pprof    # 剖析
  - user: any            # any = 匹配任意用户名的匿名用户
    pass: ''
    ips: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16']
    permissions:
      - action: publish
      - action: read

实测行为：未匹配任何用户时 API 返回 {"status":"error","error":"authentication error"}（实测回显）；带 curl -u admin:q1w2e3r4 即通过。高危坑：默认 any 用户仅放行 localhost，跨机/经端口映射访问一律 401——必须按实际来源网段重配 ips。

💡 技术拓展：流媒体鉴权不止内置用户表一种。常见方案对比——

方案原理适用
internal 内置用户表配置文件内 user/pass/ips/permissions 小规模、无外部用户系统
http 外部回调每个 publish/read 请求回调你的 HTTP 服务决定放行需对接业务系统/动态令牌
jwt JWKS 用公钥集验签 JWT 已有统一认证中心
IP 白名单 internal 方案的 ips 字段设备/内网固定来源

本文采用 internal（内置 admin + 内网段 any），因为实测环境无外部用户系统且需要 API 管理权限。

方案	原理	适用
internal 内置用户表	配置文件内 user/pass/ips/permissions	小规模、无外部用户系统
http 外部回调	每个 publish/read 请求回调你的 HTTP 服务决定放行	需对接业务系统/动态令牌
jwt JWKS	用公钥集验签 JWT	已有统一认证中心
IP 白名单	internal 方案的 ips 字段	设备/内网固定来源

5.4 RTSP 参数

rtsp: yes
rtspAddress: :8554          # 实测默认
rtspTransports: [multicast, tcp, udp]   # 实测默认顺序，客户端协商优先
rtspEncryption: no          # 可 no/yes/strict（strict 拒绝明文）
rtspHandshakeTimeout: 10s

实测佐证：FFmpeg 以 -rtsp_transport tcp 推拉成功（服务端启动日志实测 INF [RTSP] started with listeners on :8554 (TCP/RTSP), :8000 (UDP/RTP), :8001 (UDP/RTCP)，即另有 :8000 UDP/RTP、:8001 UDP/RTCP 两个固定监听）；推流时出现 INF [path cam] RTP packets are too big (1460 > 1440), remuxing them into smaller ones——MediaMTX 按 MTU 自动重切 RTP 包，属正常自愈行为。摄像机接入建议保留三种 transport 协商（不同设备支持不一）。

5.5 RTMP / SRT 参数

rtmp: yes
rtmpAddress: :1935          # 实测默认；RTMP 无加密变体（RTMPS 走反代/TLS 终结）
srt: yes
srtAddress: :8890           # 实测默认（UDP）

SRT 的认证与选路藏在 streamid 里，格式 动作:路径[:用户:密码]。实测：

# 推流（publish + 路径 + 凭据）
ffmpeg -re -f lavfi -i testsrc=size=640x360:rate=25 \
  -c:v libx264 -preset veryfast -tune zerolatency -pix_fmt yuv420p -g 50 \
  -f mpegts 'srt://127.0.0.1:8890?streamid=publish:cam_srt:admin:q1w2e3r4'
# 拉流（内网段 any 用户匿名）
ffprobe -v error 'srt://127.0.0.1:8890?streamid=read:cam_srt'

实测回显（服务端日志与拉流结果）：INF [path cam_srt] stream is available and online, 1 track (H264)；ffprobe 拉回 codec_name="h264"。

5.6 HLS 参数

hls: yes
hlsAddress: :8888
hlsVariant: lowLatency      # 可 lowLatency/classic
hlsSegmentCount: 7
hlsSegmentDuration: 1s
hlsPartDuration: 200ms
hlsEncryption: no

默认 lowLatency 的实测证据：媒体清单出现 EXT-X-PART-INF:PART-TARGET=0.20000（200ms part，LL-HLS 特征）与 EXT-X-SERVER-CONTROL:CAN-BLOCK-RELOAD=YES,PART-HOLD-BACK=0.50000；分片实测为 fMP4（EXT-X-MAP:URI="2505ec18-5c46-45a9-b504-4a83d8bcbf4c_video1_init.mp4"、HTTP 200 bytes=3684 type=video/mp4）。hlsSegmentCount×hlsSegmentDuration 决定播放窗口（默认 7 秒）。另实测：首次请求 302 到 ?cookieCheck=1 属官方防循环机制，播放器自动跟随。

5.7 WebRTC 参数

webrtc: yes
webrtcAddress: :8889        # 信令（WHEP/WHIP）HTTP 监听
webrtcEncryption: no        # 信令 HTTPS（与 rtspEncryption 类似三态）
webrtcLocalUDPAddress: :8189   # ICE 媒体 UDP（实测日志：started with listeners on :8889 (TCP/HTTP), :8189 (UDP/ICE)）
webrtcAdditionalHosts: []   # 服务器对外可达 IP/域名列表（NAT 场景必配）
webrtcICEServers: []        # 外部 STUN/TURN

实测佐证：POST /cam/whep 提交 SDP offer 返回 HTTP/1.1 201 Created + SDP answer（含 a=fingerprint:sha-256 行与 a=setup:active），响应头 Location: /cam/whep/<会话ID> 指向会话资源。跨机部署黑屏排障见部署篇 Q6。

5.8 路径参数（pathDefaults 与 paths）

pathDefaults 实测共 92 键，最核心的几个（默认值均实测）：

pathDefaults:
  source: publisher            # 流来源：publisher（等外部推）/ rtsp://（拉流代理）/ staticMedia（文件）
  sourceOnDemand: false        # 拉流代理按需拉（无人看不拉）
  sourceOnDemandStartTimeout: 10s
  sourceOnDemandCloseAfter: 10s
  maxReaders: 0                # 0=不限拉流端数量
  recordPath: ./recordings/%path/%Y-%m-%d_%H-%M-%S-%f_%z
  srtReadPassphrase: ''        # SRT 读取加密短语
  runOnDemand: ''              # 有人看时触发的自定义命令

paths 段按路径名覆盖，两段实测语义必须记住：

定义了 cam: 后，未列出的路径默认拒绝——实测 RTMP 推 cam_rtmp 报 closed: path 'cam_rtmp' is not configured；
all_others: 显式放行其余全部路径；
完全不写 paths 段（零配置）= 全拒。实测零配置直推报 400 Bad Request，服务端日志 closed: path 'cam' is not configured。

路径也可用 REST API 运行时增删（POST /v3/config/paths/add/cam_rtmp 实测返回 {"status":"ok"}，随后 RTMP 立即推入成功），适合路径动态多变的场景。

5.9 协议通用与缓冲参数

readTimeout: 10s        # 实测默认；连接读超时
writeTimeout: 10s       # 实测默认；连接写超时
writeQueueSize: 512     # 实测默认；每读者发送队列包数，高码率高延迟场景可加大
udpReadBufferSize: 0    # 实测默认 0=系统默认；弱网大流量可调

writeQueueSize 是拉流卡顿的第一调整项：读者网络差于推流速率时队列溢出会踢读者，日志可见对应告警；一般 512→1024/2048 按场景递增，内存代价线性。

5.10 录制参数（record*）

record: no                          # 总开关
recordPath: ./recordings/%path/%Y-%m-%d_%H-%M-%S-%f_%z   # 实测默认（来自 pathDefaults）
recordFormat: fmp4                  # 分段 fMP4
recordSegmentDuration: 1h           # 单文件时长

格式占位符：%path 路径名、%Y-%m-%d_%H-%M-%S-%f 起始时间、%z 时区。录制与回放（9996 端口 playback 服务）配套使用。

六、生产配置模板

适用场景：8GB 内存、SSD、单机 50 路以内 1080p 摄像机接入 + 浏览器实时查看 + 录制备份（监控/园区典型形态）。逐项都有解说：

logLevel: info
logDestinations: [stdout, file]     # 双落点：控制台 + 文件
logFile: /var/log/mediamtx.log

api: yes                            # 运维自动化依赖 API
apiAddress: :9997
apiAllowOrigins: ['https://ops.example.com']   # 收紧 CORS 到运维站点
metrics: yes                        # Prometheus 抓取
metricsAddress: :9998

authMethod: internal
authInternalUsers:
  - user: admin                     # 管理账号（API/metrics 全权限）
    pass: q1w2e3r4
    ips: ['10.0.0.0/8']
    permissions:
      - action: publish
      - action: read
      - action: playback
      - action: api
      - action: metrics
  - user: any                       # 内网设备/观众匿名读写
    pass: ''
    ips: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16']
    permissions:
      - action: publish
      - action: read

rtsp: yes
rtspTransports: [tcp, udp]          # 服务器侧不监听 multicast（未用组播则去掉）
hlsVariant: lowLatency              # 浏览器 2~5s 延迟观看
hlsSegmentDuration: 1s
hlsPartDuration: 200ms

webrtc: yes
webrtcAdditionalHosts: ['media.example.com']   # 对外域名/IP，跨网观看必配
srt: yes                            # 异地中心拉流走 SRT

writeQueueSize: 1024                # 弱网观众缓冲加倍
readTimeout: 20s

record: yes                         # 录制备份
recordPath: /data/recordings/%path/%Y-%m-%d_%H-%M-%S-%f_%z
recordSegmentDuration: 30m          # 30 分钟一个文件，便于回传与清理

paths:
  all_others:                       # 路径放开由认证约束

模板要点：对外只暴露 8554/8888/8889/8890 与 9997/9998（防火墙层面）；9997/9998 不对公网；录制盘与系统盘分离；writeQueueSize/readTimeout 是两个最常用的稳定性旋钮。若需公网加密分发，前置 Nginx/Caddy 终结 TLS 反代 8888/8889 即可。

七、常见问题

Q1：改了参数不生效？

三种改法三种生效时机（见 3.2）：改 yml 必须重启进程；环境变量只在启动时读；运行中热改走 PATCH /v3/config/global/patch。用 GET /v3/config/global/get 看当前生效值最直接（实测该方法返回 121 键实时值）。

Q2：启动警告 parameter 'apiAllowOrigin' is deprecated and has been replaced with 'apiAllowOrigins'？

v1.21 改名：apiAllowOrigin → apiAllowOrigins（复数、数组值）。实测改名后警告消失（排障实录）。

Q3：推流全部报 path 'cam_rtmp' is not configured？

paths 段语义问题（见 5.8）：定义过具体路径后其余默认拒绝，加 all_others:；零配置启动同样全拒。首次部署 90% 的推流失败源于此。

Q4：API 报 authentication error？

默认内置用户只放行 localhost；跨机访问需在 authInternalUsers 加用户与来源网段（见 5.3），或用 -u 用户:密码 携带具 api action 权限的账号。

Q5：SRT 拉流要密码吗？

由 path 的 srtReadPassphrase 与 authInternalUsers 共同决定：streamid 里带 :用户:密码 段即走认证（实测 publish:cam_srt:admin:q1w2e3r4 通过），内网段 any 用户可匿名 read（实测 read:cam_srt 通过）。

八、参考链接

官方默认全量配置（v1.21.3 发布包内 mediamtx.yml，全部参数注释）
官方 wiki 配置文档：https://github.com/bluenviron/mediamtx/tree/main/wiki
本系列：《MediaMTX 1.21.3 介绍与选型指南》、《MediaMTX 1.21.3 Docker Compose 部署指南》、《MediaMTX 1.21.3 API 使用详解》