发布日期：2026 年 9 月 7 日
最新版本：v1.21.0
mediamtx v1.21.0 正式发布。本次更新覆盖 Media-over-QUIC、API、RTSP、RTMP、HLS、WebRTC、树莓派摄像头支持、配置校验、指标体系、跨域安全、音视频封装与编解码处理等多个方向。
其中，最值得关注的核心变化包括：Media-over-QUIC 支持流转发、API 新增静态源详情查询接口、转发目标与静态源新增类型专属属性、RTSP 支持 SDES SRTP 密钥交换、RTSP 拉流支持 MPEG-TS 解复用、WebRTC 注册入站视频 RTX、默认收紧 API 和指标跨域访问策略，以及针对 H.264、H.265、AV1、MPEG-4 Audio、KLV 等媒体处理链路的大量稳定性修复。
本文根据 v1.21.0 的完整更新内容，对本次版本的功能、改进、修复、依赖升级与二进制安全验证方式进行详细整理。
一、核心亮点：Media-over-QUIC 能力继续完善
Media-over-QUIC 是 v1.21.0 最重要的更新方向之一。本次版本为该能力补充了流转发支持，并围绕连接、客户端、流生命周期和内存限制进行了多项结构性优化。
1. 支持转发流
Media-over-QUIC 新增流转发支持。
这意味着 Media-over-QUIC 不再局限于基础的数据传输能力，进一步具备面向媒体流分发与转发场景的支持。对于需要在不同节点、不同协议链路之间处理媒体流的部署环境，这项能力是本次大版本的重要增强。
2. 布尔头部字段重命名
Media-over-QUIC 中的部分布尔头部字段进行了命名调整：
| 原字段 | 新字段 |
|---|---|
Properties |
HasProperties |
FirstObject |
IsFirstObject |
新的字段名称语义更加明确。HasProperties 用于表达"是否具有属性"，IsFirstObject 用于表达"是否为第一个对象"，能够减少字段含义理解上的歧义。
3. 新增共享 Conn 接口
Media-over-QUIC 新增共享 Conn 接口。
该调整用于统一连接相关能力的抽象，使相关组件可以围绕统一接口进行处理，进一步优化内部连接管理结构。
4. 新增共享客户端
Media-over-QUIC 新增共享客户端。
该能力配合共享连接接口，使客户端侧的处理结构得到进一步整合，有助于统一会话、连接与传输相关逻辑。
5. 不再长期保留无用流
此前，部分双向流和单向流会在整个会话周期内保持打开状态。v1.21.0 改进了这一行为：当服务端流不再使用时，会显式将其关闭。
需要注意的是，在 QUIC 或 WebTransport 中，关闭流并不意味着完整切断通信，而是向对端表达"本端不会再发送数据"。关闭后，入站方向的数据仍然可以继续接收。
这一调整可以避免流在整个会话期间无必要地保持开启状态，使流生命周期管理更加合理。
6. 每个会话的重排序字节总量限制为 100MB
Media-over-QUIC 针对重排序数据引入了新的限制策略：每个会话最多允许 100MB 的重排序字节数据。
此前，限制是按单个轨道分别计算的。现在调整为按会话统一计算，可以降低在多轨道场景下发生内存耗尽问题的概率。
这一变化对于复杂媒体会话尤为重要。多个媒体轨道同时出现乱序数据时，统一的会话级限制能够更好地控制资源使用范围。
二、API 更新：静态源查询、转发目标信息与接口命名优化
v1.21.0 对 API 进行了多项扩展和整理，包括新增静态源查询接口、补充转发目标与静态源的类型专属属性、优化接口命名结构，以及对部分旧字段和旧接口保留兼容。
1. 新增静态源详情查询接口
新增接口：
text
/paths/static-sources/get该接口用于获取静态源的详细信息。
通过该接口，使用者可以查询静态源的相关状态和详情，为管理静态拉流来源、查看路径源配置以及进行自动化运维提供了更直接的 API 入口。
2. 转发目标增加类型专属属性
转发目标新增类型专属属性。
不同类型的转发目标可能具备不同配置和运行特征。通过新增类型专属属性，API 可以返回更符合实际类型的信息，便于调用方根据不同转发目标进行识别和处理。
3. 静态源增加类型专属属性
静态源同样新增类型专属属性。
静态源可能涉及不同传输协议与来源形式，类型专属属性可以让 API 响应更准确地反映源的具体情况，提升管理端对不同静态源的识别能力。
4. 转发目标新增 type 字段，protocol 字段进入弃用状态
转发目标新增 type 字段，同时原有的 protocol 字段被标记为弃用。
type 与服务其他区域所使用的术语保持一致，能更清晰地描述转发目标类型。
需要注意的是，protocol 字段并未立即移除，仍会保留以兼容既有调用方。但在后续 API 对接和新功能开发中，应优先使用 type 字段。
5. 转发目标 conf 字段进入弃用状态
转发目标中的 conf 字段被标记为弃用。
相关配置已经可以通过路径的 confName 属性获取，因此不再建议依赖转发目标中的 conf 字段。该调整减少了重复配置字段，并使配置定位方式更加统一。
6. API 端点重新分类与命名规范化
API 端点进行了结构性整理，主要包括：
- 按类别对端点进行分组；
- HLS 相关资源采用如
/hls/muxers、/hls/sessions的组织方式； - 原
/forward/*路径调整为/forward-dests/*； - 接口命名采用 kebab-case 风格。
虽然端点命名进行了重构，但旧端点仍然会继续提供服务，以保持向后兼容。已有系统无需因本次升级立即修改全部调用路径，但新项目和后续维护建议逐步迁移到新的接口命名方式。
三、配置与通用能力改进
v1.21.0 在配置校验、版本来源、日志、外部命令、YAML、macOS 缓冲区设置等方面均有改进。
1. 新增配置校验参数
新增命令行参数：
text
--validate-conf该参数用于校验配置文件。
通过独立的配置验证能力，可以在服务正式启动前检查配置内容是否有效，适合部署流程、自动化脚本与配置变更后的预检查场景。
2. 使用统一版本来源
服务版本信息现在统一从以下内部文件获取：
text
internal/core/VERSION这使版本号的来源更加集中，避免不同位置维护版本信息时可能出现的不一致问题。
3. HTTP 响应包装器正确传递 Flush
HTTP 相关响应包装器现在支持正确传递 Flush() 调用，同时支持 Unwrap()。
此前，日志处理器使用的响应记录器与写超时处理器使用的响应写入器都包装了 http.ResponseWriter，但没有实现 http.Flusher 或 Unwrap()。
这一问题会导致中途刷新的响应无法及时发送给客户端：即使处理器已经写入并执行刷新，客户端仍可能要等到处理器彻底返回后才能收到内容。
这会影响分块输出和服务端事件推送等场景。写超时写入器的目标本身是允许长响应按块写入，同时避免超时；但如果刷新操作没有真正传递，响应内容仍然会被缓冲到处理结束时才送达。
本次修复后，Flush() 能够穿透响应包装器，http.ResponseController 也可以借助 Unwrap() 继续访问底层能力。相关测试通过真实监听器验证：在处理器仍处于阻塞状态时读取响应内容，确保中途刷新确实能够到达客户端。
4. macOS 支持设置读取缓冲区大小
macOS 平台现在支持设置读取缓冲区大小。
该能力覆盖通用层与 RTSP 相关实现，使运行在 macOS 系统上的部署能够配置读取缓冲区参数。
5. Debian Bullseye 支持终止
v1.21.0 移除了对 Debian Bullseye 的支持。
Bullseye 已于 2026 年 8 月 31 日结束生命周期，因此本次版本同步停止对该系统版本的支持。树莓派摄像头相关组件也同步移除了 Debian Bullseye 支持。
6. 服务关闭时输出 closed 日志
当服务关闭时，系统现在会输出 closed 日志消息。
这一改进让服务停止事件在日志中更加明确，方便运维人员确认实例是否完成关闭。
7. 修复非 Windows 平台外部命令退出码上报
修复了非 Windows 平台上外部命令退出码报告不正确的问题。
如果服务通过外部命令机制执行相关操作，现在能够更准确地反映外部命令的退出状态。
8. 配置支持 YAML 版本指令
配置解析现在支持 YAML 版本指令。
这一改进提升了 YAML 配置兼容能力，使包含版本指令的 YAML 内容能够被正确处理。
四、指标体系更新：字段优化、弃用提示与跨域默认收紧
本次版本对 metrics 指标接口进行了多项调整，重点围绕转发目标字段、远端地址字段以及跨域安全策略展开。
1. forward_dests 新增 pos 属性
metrics 中的 forward_dests 新增 pos 属性。
该字段用于补充转发目标相关信息，使指标数据能够呈现更多与转发目标位置有关的内容。
2. remoteAddr 属性进入弃用状态
metrics 中的 remoteAddr 属性被标记为弃用。
指标系统的定位是提供聚合统计数据，而不是用于暴露单个对端的属性信息。单个对端的详细数据可以通过 API 获取。
为保证兼容性，remoteAddr 当前仍然会继续提供，但后续使用中不建议将其作为长期依赖字段。
3. forward_dests 新增 type，protocol 进入弃用状态
与 API 调整一致，metrics 中的转发目标增加 type 字段，原 protocol 字段被标记为弃用。
type 的命名与服务其他模块保持统一，更适合用于表达转发目标类型。
4. metrics 和 pprof 默认 Allow-Origins 调整为空列表
metrics 与 pprof 的默认 Allow-Origins 现在设置为空列表。
这一调整可以阻止默认配置下的跨站请求访问 API，从而降低跨站攻击风险。对于需要跨域访问 metrics 或 pprof 的部署，需要显式配置允许来源，而不再依赖默认放行行为。
五、跨域访问安全修复：Allowed Origins 规则更严格
v1.21.0 对 HTTP 允许来源规则进行了多项修复，主要解决通配符、点号匹配、缓存和返回头策略的问题。
1. 修复允许来源通配符错误匹配不同协议的问题
此前，包含通配符的允许来源规则可能让服务接受不同协议的来源。
本次修复后，允许来源规则会正确区分协议，避免来源协议不一致时被错误接受。
2. 修复允许来源中的点号被当作任意字符的问题
此前，HTTP 允许来源中的点号可能被解释为任意字符匹配。
修复后，允许来源规则中的点号必须与请求来源中的实际点号对应，避免域名匹配范围被意外扩大。
3. Access-Control-Allow-Origin 同时返回 Vary: Origin
当返回 Access-Control-Allow-Origin 时，服务会同时返回：
text
Vary: Origin这一行为可以避免 CDN 在缓存响应时，不区分请求来源而错误复用 Access-Control-Allow-Origin 头部。
4. 不再直接返回通配符作为 Access-Control-Allow-Origin
当域名被允许时，服务会返回对应的具体域名；当域名不被允许时，不返回该头部。
不再使用通配符直接作为 Access-Control-Allow-Origin 返回值，使跨域返回策略更加精确。
六、路径、录制与认证行为调整
1. always-available 路径支持离线时禁用录制
新增 alwaysAvailableRecorded 参数。
该参数控制 always-available 路径在源离线期间是否进行录制：
| 参数值 | 行为 |
|---|---|
true |
源离线期间仍按 always-available 行为进行录制 |
false |
只有真实源已连接时才开始录制 |
当 alwaysAvailableRecorded 设置为 false 时，录制不会在离线期间启动，只有真实媒体源接入后才会开始。
2. 支持用户名带空密码的源与转发目标
现在允许源地址和转发目标地址使用显式空密码。
例如，带用户名且密码为空的 URL 现在可以被接受。这符合 RFC 3986 的语义，也适用于一些无法设置密码的旧式摄像头。
该行为适用于 validateURL() 处理的所有协议，包括 RTSP 源和转发目标。
需要区分以下情况：
| URL 认证形式 | 是否允许 |
|---|---|
| 有用户名，密码显式为空 | 允许 |
| 有用户名，没有密码部分 | 不允许 |
| 有密码，没有用户名 | 不允许 |
对于不允许的认证格式，系统会给出更明确的错误信息，提示正确的 URL 语法。
七、媒体封装与编解码处理优化
v1.21.0 对 pmp4、fmp4、H.264、H.265、AV1 等处理路径进行了多项改进。
1. pmp4 与 fmp4 不再验证入站 H.264 和 H.265 SPS
pmp4 与 fmp4 处理流程不再验证入站 H.264、H.265 的 SPS。
验证 SPS 会增加延迟，并且通常属于冗余操作。因此，本次调整能够减少不必要的处理环节。
2. pmp4 与 fmp4 不接受空的 H.264 和 H.265 参数
虽然不再执行 SPS 验证，但空的 H.264 和 H.265 参数仍然不被接受。
这项调整避免空参数进入后续媒体处理流程，降低异常流引发问题的可能性。
3. 修复 H.265 时间戳提取对时间子层流的支持
修复 H.265 DTS 提取器对带时间子层流的处理问题。
此前，H.265 DTS 提取逻辑仅处理部分图像类型，包括 TRAIL、RASL 等类型。当访问单元中的切片属于 TSA 或 STSA 类型时，处理流程可能落入"访问单元不包含 IDR 或非 IDR NALU"的错误分支，导致流无法被录制。
TSA 与 STSA 图像使用的切片分段头语法与 TRAIL 图像一致，因此现在会按照与 TRAIL 相同的方式处理。
这一修复使包含时间子层的 H.265 流能够正常提取 DTS 并进入录制流程。
八、RTSP 更新：安全、认证、MPEG-TS、SRTP 与 RTP 处理全面增强
RTSP 是本次版本更新最集中的模块之一，涉及日志脱敏、MPEG-TS 解复用、SDES SRTP、Digest 认证、MPEG-4 Audio 分片、AV1 RTP、KLV 缓冲区与 HTTP 隧道等内容。
1. RTSP 日志隐藏认证凭据
RTSP 日志现在会对认证凭据进行脱敏处理。
当 RTSP URL 中包含用户名、密码或其他认证信息时，日志不再直接暴露这些敏感内容，从而减少凭据泄露到日志系统中的风险。
2. 静态 RTSP 拉流支持 MPEG-TS 解复用
当启用 rtspDemuxMpegts 时，如果拉取到的 RTSP 静态源只包含单个 MP2T 轨道，服务会将该 MPEG-TS 轨道解复用为基础码流。
解复用后的效果与 RTSP 发布端提供的基础流保持一致，因此 HLS 可以附加到这些媒体轨道上。
这项能力改善了 RTSP 静态源中使用 MPEG-TS 封装的场景，使后续 HLS 输出能够正常衔接。
3. 支持 RTSP 与 RTSPS 源的 SDES SRTP 密钥交换
RTSP 和 RTSPS 源现在支持使用 SDES 方式进行 SRTP 密钥交换。
该能力遵循 RFC 4568，扩展了服务与采用 SDES SRTP 安全传输方式的 RTSP 源之间的兼容性。
4. SETUP 响应中忽略无效源 IP
RTSP 客户端现在会忽略 SETUP 响应中的无效源 IP 地址。
这一修复增强了客户端面对异常或不规范响应内容时的兼容性。
5. 修复分片 MPEG-4 Audio 数据包的编码与解码
修复了分片 MPEG-4 Audio 数据包的编码和解码问题。
此前，在后续分片中，AU-size 字段的设置不正确。该问题现已修复，使 MPEG-4 Audio 分片数据包能够按照正确方式处理。
6. RTSP 不再验证入站 H.264 与 H.265 SPS
RTSP 处理链路同样不再验证入站 H.264 和 H.265 SPS。
该调整与 pmp4、fmp4 的改进保持一致，避免增加额外延迟和冗余处理。
7. KLV 解码结果不再复用内部缓冲区
RTSP KLV 处理不再复用返回 KLV 单元的内部缓冲区。
此前，解码器返回的切片指向内部缓冲区；下一次解码时，同一块数组可能被覆盖。若调用方仍在录制或另一个协程中转发前一个 KLV 单元，就可能读取到后一个单元的数据，或得到不同大小数据交错后的错误内容。
修复后，缓冲区会被清空而不是仅截断，从而确保每个 KLV 单元拥有独立的数据数组。
H.264、H.265、AV1、VP8 和 MPEG-1 Video 解码器此前已经采用类似方式，代价是每个单元需要一次额外分配。
8. Digest 客户端认证支持 qop=auth
RTSP Digest 客户端认证新增 qop=auth 支持。
此前，客户端不会读取 Digest 挑战中的 qop 指令，而是始终使用旧式 RFC 2069 响应计算方式。因此，当服务端要求 qop="auth" 时，客户端请求会被拒绝并返回 401。
现在，当服务端提供 auth 时，客户端会发送以下字段：
text
qop
cnonce
nc并按照 RFC 7616 的方式计算认证响应：
text
H(HA1:nonce:nc:cnonce:qop:HA2)其中，nonce 计数会在每次请求时递增。
对于不包含 qop 的挑战，客户端仍保持此前行为。auth-int 暂未实现。
此外，挑战中的 opaque 值现在会被复制到 Authorization 请求头中，并保持原样返回。
9. HTTP 隧道 GET 请求移除 Content-Length
RTSP 客户端的 HTTP 隧道 GET 请求不再包含 Content-Length。
该调整改善了 HTTP 隧道请求格式的兼容性。
10. 修复 AV1 RTP 打包时错误设置 Y 与 Z 标志位的问题
RTSP AV1 RTP 打包逻辑得到修复。
此前，当数据包剩余空间不足以容纳下一个 OBU 的任何字节时，编码器虽然未写入该 OBU 内容，但仍会将当前包标记为 Y=1、后续包标记为 Z=1。
根据 AV1 RTP 负载格式规范，只有当 OBU 元素实际跨越两个数据包时，Y 和 Z 才能被设置为 1。若没有实际分片，两个标志位必须为 0。
错误标志可能让接收端把两个完整 OBU 错误拼接为一个 OBU。该问题可能影响重打包媒体流，例如由非 RTSP 源读取后再通过 RTSP 输出的场景。
修复后，只有真正写入 OBU 分片数据时才会设置相关标志位。
九、RTMP 更新：空配置处理、参数校验与认证信息清理
1. RTMP 读取端支持空 H.264 配置
RTMP 读取端现在支持空的 H.264 配置。
这一调整提高了对部分特殊 RTMP 流的兼容能力。
2. 修复无效 H.264 和 H.265 参数引发崩溃的问题
RTMP 写入端修复了在 H.264 或 H.265 参数无效时可能发生崩溃的问题。
现在遇到无效参数时，系统能够避免异常崩溃。
3. RTMP 读取端不接受空 H.264 和 H.265 参数
RTMP 读取端不接受空的 H.264 和 H.265 参数。
需要注意的是，"支持空 H.264 配置"与"不接受空 H.264/H.265 参数"属于不同处理环节的调整：前者针对读取端的 H.264 配置兼容能力，后者用于防止空媒体参数进入后续处理。
4. RTMP 服务端始终从 URL 中移除认证参数
RTMP 服务端现在始终会从 URL 中移除认证参数。
这一调整有助于避免认证相关参数在后续 URL 处理中继续保留。
十、HLS 更新：按变体校验分段数量
HLS 现在会根据 HLS 变体正确校验 hlsSegmentCount。
不同 HLS 变体对分段数量可能存在不同要求。本次调整让 hlsSegmentCount 的校验逻辑与实际 HLS 变体保持一致。
十一、WebRTC 更新：RTX 与 IPv6 ICE 解析修复
1. 为入站视频轨道注册 RTX
WebRTC 现在为入站视频轨道注册 RTX。
RTX 用于 RTP 重传相关处理。该改进增强了入站视频轨道对 RTX 的支持。
2. 修复已弃用 WebRTC ICE Servers 解析器的 IPv6 主机解析问题
修复了已弃用 WebRTC ICE Servers 解析器处理 IPv6 主机时的问题。
使用 IPv6 主机地址的相关配置现在可以被更正确地解析。
十二、树莓派摄像头模块更新
树莓派摄像头相关模块同步移除了 Debian Bullseye 支持。
由于 Debian Bullseye 已于 2026 年 8 月 31 日结束生命周期，v1.21.0 不再继续支持该系统版本。
十三、依赖组件升级清单
v1.21.0 更新了多个依赖组件，具体如下：
| 依赖 | 旧版本 | 新版本 |
|---|---|---|
code.cloudfoundry.org/bytefmt |
v0.85.0 | v0.88.0 |
github.com/bluenviron/gohlslib/v2 |
v2.4.3 | v2.4.4 |
github.com/bluenviron/gortmplib |
v1.0.1 | v1.0.2 |
github.com/bluenviron/gortsplib/v5 |
v5.6.4 | v5.6.5 |
github.com/bluenviron/mediacommon/v2 |
v2.9.3 | v2.9.4 |
github.com/matthewhartstonge/argon2 |
v1.5.6 | v1.5.7 |
github.com/pion/webrtc/v4 |
v4.2.18 | v4.2.19 |
github.com/quic-go/quic-go |
v0.61.0 | v0.62.0 |
github.com/quic-go/webtransport-go |
v0.12.0 | v0.13.0 |
github.com/stretchr/testify |
v1.12.0 | v1.12.1 |
github.com/dunglas/httpsfv |
v1.1.0 | v1.1.1 |
github.com/pion/stun/v3 |
v3.1.6 | v3.1.7 |
github.com/pion/turn/v5 |
v5.0.12 | v5.0.13 |
github.com/bluenviron/mediamtx-rpicamera |
v2.8.0 | v2.9.0 |
hls.js |
v1.7.0 | v1.7.2 |
此外，YAML 相关依赖发生了调整：
| 变更类型 | 依赖 |
|---|---|
| 移除 | gopkg.in/yaml.v3 |
| 新增 | go.yaml.in/yaml/v3 v3.0.5 |
十四、二进制安全与校验方式
v1.21.0 的二进制文件由 Release 工作流从源代码编译生成。
该工作流是完全可见的流程，用于防止生成产物在构建过程中被修改或遭受外部干预。
同时，二进制文件校验和会通过 GitHub Attestations 发布到公共区块链中。可以使用以下命令验证二进制文件的证明信息：
bash
ls mediamtx_* | xargs -L1 gh attestation verify --repo bluenviron/mediamtx也可以下载 checksums.sha256 后，通过以下方式验证二进制文件校验和：
bash
cat checksums.sha256 | grep "$(ls mediamtx_*)" | sha256sum --check十五、版本总结
代码地址：github.com/bluenviron/mediamtx
mediamtx v1.21.0 是一次覆盖范围广泛的重要更新。
在传输协议层面，Media-over-QUIC 增加流转发能力，并优化连接抽象、客户端复用、流关闭机制和会话级内存限制；在 API 层面，新增静态源查询接口，补充静态源与转发目标类型信息，并完成端点分类与命名优化；在安全层面，默认收紧 metrics、pprof 和 API 的跨域访问策略，修复允许来源匹配问题，并强化 RTSP 凭据日志脱敏。
媒体处理方面，本次版本改善了 H.264、H.265、AV1、MPEG-4 Audio、MPEG-TS、KLV 等多种格式与封装链路的处理能力；RTSP 增加 SDES SRTP、Digest qop=auth、MPEG-TS 解复用等支持；RTMP、HLS、WebRTC 与树莓派摄像头模块也获得对应更新。
对于正在使用 mediamtx 的流媒体平台、视频监控系统、协议网关、媒体转发服务与自动化运维环境而言，v1.21.0 在功能完整性、协议兼容性、资源控制、跨域安全与媒体处理稳定性方面带来了大量值得关注的变化。