mediamtx v1.21.3发布：HTTP2、转发热重载、录制稳定性、MoQ 与 HLS 全面增强

发布日期：2026年11月1日

mediamtx v1.21.3 是一次覆盖范围较广的维护与功能增强版本。本次更新重点改善了 HTTP2、转发目标热重载、日志重建、录制时间戳、H264 随机访问点识别、JWT 会话过期处理、内部用户管理接口、MoQ 协议兼容性、RTMP 地址拼接、HLS MPEG-TS 兼容性、WebRTC 配置校验、UDP 组播以及树莓派摄像头文字叠加等能力。

同时，多个与音视频录制、AAC 多声道、MPEG-TS 大帧解析、证书加载协程、监听错误处理相关的问题得到修复。对于长期运行、频繁热重载、存在多协议转发和录制需求的部署环境，本版本带来了更好的稳定性与可维护性。

一、通用能力更新与稳定性修复

HTTP2 请求支持恢复

本版本恢复了 HTTP2 请求支持。

此前，服务端在 TLS ALPN 协商中不再声明 HTTP2 协议，导致 HTTP2 请求无法正常使用。现在该问题已经修复，服务端将重新在 TLS ALPN 中正确声明 HTTP2。

关联编号：6320。

转发目标热重载更加精准

转发配置在热重载时，对目标列表的比较方式得到改进。

此前，ReloadConf 按照目标在配置列表中的位置比较旧列表和新列表。如果从列表中间删除一个目标，后续所有目标的位置都会向前移动，因此会被错误识别为发生变化，进而被重启。重启会导致已有连接被断开，并重新建立连接。

现在，系统会按照目标配置内容匹配转发目标，而非仅依赖目标在列表中的位置。因此：

• 新增目标时，仅启动新增的目标；

• 删除目标时，仅停止被删除的目标；

• 调整目标顺序时，不会导致未修改目标重启；

• 未变化的目标可以持续运行并保持连接；

• 被保留目标在 API 和日志中展示的位置会同步更新。

这一改动能够明显减少配置重载时不必要的转发中断。

关联编号：6299。

避免转发目标在切换时重叠发布

当配置发生变化且转发目标被修改时，系统将先关闭已有的转发目标，再创建新的转发目标。

此前，新旧转发目标可能在短时间内同时存在，造成重复发布。新版本通过调整创建和关闭顺序，避免转发目标重叠发布。

关联编号：6324。

HTTP 出站请求日志增强

HTTP 出站请求现在会以 debug 日志级别记录。

此前，HTTP 入站请求已经能够进行日志记录，但出站请求缺少同样的可观测性。升级后，用户可以通过 debug 级别日志同时查看 HTTP 请求的进入与发出情况，便于定位代理、认证、回调及网络通信问题。

关联编号：6325。

动态重建日志时修复竞态条件

日志配置支持动态更新，例如修改 logLevel 时，日志组件可能需要重建。

此前，在日志重建过程中，部分始终依赖日志组件的模块可能发生问题，尤其是 hooks。hooks 不会在普通日志配置变更时停止，只有整个服务关闭时才会停止，因此日志对象销毁并重建的方式可能产生竞态条件。

本版本改为安全地重新加载日志配置，而不是直接销毁日志对象，从而避免日志动态重建期间出现竞态问题。

关联编号：6206、6326。

补充链路本地 IPv6 Zone 编码说明

文档现在补充了关于链路本地 IPv6 地址 Zone 编码的说明。

关联编号：6327。

建议在可写目录中运行

文档新增了运行目录建议，以确保相关文件可正常写入。

推荐方式如下：

• 在 Docker 中运行时，使用/etc/mediamtx；

• 在主机 Linux 环境中运行时，使用/usr/local/etc/mediamtx。

关联编号：6369。

致命监听错误将直接退出

如果发生致命的监听错误，服务现在会直接退出。

这一调整避免服务在无法正常监听端口的状态下继续运行。

关联编号：6415。

证书加载器协程泄漏修复

CertLoader 的关闭逻辑得到修复。

此前，证书加载器的监听协程可能无法在关闭后被正确等待，存在协程泄漏风险。现在，CertLoader.Close 会等待 CertLoader.watch 完成。

关联编号：6261、6417。

二、录制功能与时间戳处理增强

录制分段名称统一使用本地时区

录制分段名称中的时间戳处理得到修复。

视频帧的绝对时间戳可能携带不同的时区。尤其是来自 HLS 源的时间戳，会保留其原始时区。当没有可用的绝对时间戳时，相关组件会使用本地时区的当前时间。

此前，这些时间戳在用于生成录制分段名称时，没有被统一规范到本地时区。于是，同一路流可能因为时间戳来源不同，产生带有不同时区的分段名称。当录制路径中没有使用%z占位符时，容易造成混乱和错误。

现在，所有传入日期在用于生成分段名称前，都会统一转换为本地时区。

关联编号：5451、6333。

默认录制路径加入时区，并对缺失时区发出警告

默认 recordPath 现在包含时区信息。

如果 recordPath 没有%z，在夏令时切换期间可能出现以下问题：

• 录制分段被覆盖；

• 分段被保存到错误的时间位置；

• 同一个本地时间对应多个实际时刻时产生冲突。

因此，新版本为默认录制路径加入时区，并在录制路径没有时区信息时给出警告。

关联编号：6334。

H264 Recovery Point SEI 被视为随机访问点

对于没有 IDR 帧的 H264 流，I 帧配合 Recovery Point SEI 可以作为随机访问点。

此前，RTMP 读取端输出以及 fMP4 录制器只接受 IDR 帧作为随机访问点，单元重封装器也只会在 IDR 帧前添加 SPS 和 PPS。这样一来，DTS 提取器可能始终无法接收到 SPS。

新版本使用 H264 随机访问点判断逻辑，将 Recovery Point SEI 纳入随机访问点处理范围。MPEG-TS 输出此前已经具备对应行为。

关联编号：6349。

不再静默跳过异常 H264 单元

MPEG-TS 和 RTMP 的 H264 处理逻辑得到改进。

此前，缺少 IDR 且缺少非 IDR 图像的 H264 单元可能被静默跳过。现在不再进行静默跳过。

关联编号：6354。

修复 VP9 fMP4 录制高度错误

VP9 轨道写入 fMP4 录制文件时，视频高度识别错误的问题已修复。

此前，fMP4 录制器错误地从关键帧头部的宽度字段读取 VP9 高度，因此初始化分段会错误声明为正方形尺寸。例如，原本应为 1920×804 的视频，可能被声明为 1920×1920。

现在，系统会正确读取 VP9 的高度字段。

关联编号：6359。

修复 MPEG-1 和 MPEG-2 Audio 的 fMP4 时间戳

MPEG-1 Audio 与 MPEG-2 Audio 写入 fMP4 录制文件时，时间戳计算问题得到修复。

此前，每个样本的 DTS 被错误计算为单元 PTS 加上单元 PTS，导致：

• 录制中的样本时长变成真实时长的两倍；

• 一个单元中包含多帧时，这些帧会拥有相同时间戳。

现在，系统会按照每一帧的时长逐步推进 PTS，并以相同偏移量推进每帧的 NTP 时间，行为与 Opus、MPEG-4 Audio、AC-3 的处理方式一致。

关联编号：6361。

避免流时间断点导致 fMP4 分段时长异常膨胀

当 RTP 时间戳发生不连续时，例如大量丢包之后，两个连续样本的时间间隔可能变得非常大。

在 fMP4 录制中，前一个样本的时长由下一个样本 DTS 减去当前样本 DTS 得出。如果两个时间戳之间存在巨大间隔，该间隔会被写入前一个样本的时长，并进一步推动分段结束 DTS。最终，文件头中的总时长以及 runOnRecordSegmentComplete 上报的时长都会被严重放大。

例如，实际约一分钟的片段，可能被上报为数小时。

此前，NTP 与流时间漂移检测会在下一个样本到来后才触发。此时，被放大的分段可能已经被刷新和上报。

新版本将断点检测提前一个样本：当下一个样本的流时间与绝对时间的漂移超过容差时，会将当前样本的时长置零，从而避免当前分段被异常拉长。之后，原有的漂移检测机制仍会在后续样本上重置录制状态。

MPEG-TS 不受这一问题影响，因为其会在修改分段之前基于当前样本检查漂移。

这一修复与此前针对负时间差和时间漂移重置的处理形成补充。

关联编号：5984。

频繁重载时录制分段无法删除的问题修复

如果配置频繁重载，旧版本中可能出现录制分段永远无法删除的问题。

本版本已修复该问题，确保录制分段清理机制在频繁配置重载场景下能够正常工作。

关联编号：6256。

fMP4 录制分段 API 增加时长字段

API 现在会暴露 fMP4 录制分段的 duration 信息。

关联编号：6412。

三、认证、会话与内部用户管理更新

JWT 到期后自动关闭会话

会话现在会在 JWT 到期时关闭。

这项改进使认证会话的有效期能够与 JWT 的过期时间保持一致。

关联编号：4300、5813、6389。

HTTP 认证支持设置会话过期时间

HTTP 认证现在能够设置会话过期日期。

关联编号：6391。

新增内部用户管理 API

本版本新增用于管理内部用户的专用接口，不再需要通过config/global/patch并携带完整用户列表来修改单个用户。

新增接口包括：

•/v3/config/internal-users/list

•/v3/config/internal-users/get/{id}

•/v3/config/internal-users/add

•/v3/config/internal-users/patch/{id}

•/v3/config/internal-users/replace/{id}

•/v3/config/internal-users/delete/{id}

这些接口可用于列出、读取、添加、局部更新、替换和删除指定内部用户。

关联编号：6293。

不允许使用旧凭据访问内部用户列表接口

internal-users/list不再允许使用已废弃的凭据方式访问。

关联编号：6368。

修复 global/patch 与旧配置字段的兼容问题

global/patch 在使用旧字段时的问题已修复。

此前，如果设置了旧的webrtcICEServers参数，系统会自动填充webrtcICEServers2。而后者存在时，会阻止前者通过 global/patch 进行设置。

类似问题也存在于以下已废弃字段：

•readUser

•readPass

•publishUser

•publishPass

•authInternalUsers

本版本修复了这些旧字段通过 global/patch 设置时的兼容性问题。

关联编号：6362、6365。

API 暴露 MoQ 会话用户信息

API 现在能够暴露 MoQ 会话所使用的用户信息。

关联编号：6390。

四、音频轨道与多声道 AAC 修复

修复常驻 8 声道 AAC 轨道拒绝 7.1 发布者的问题

当始终可用轨道配置为 8 声道 MPEG-4 Audio 时，旧版本可能拒绝 7.1 AAC 发布者，并报出 MPEG-4 Audio 配置不匹配。

问题原因是：轨道使用了通道配置值 8，但该值是保留值；而发布者使用的是配置值 7。配置值 7 实际代表 8 个声道。

现在，8 声道轨道使用通道配置值 7，其他声道数量保持不变。

关联编号：6414。

修复 API 中 7.1 AAC 声道数显示错误

当路径携带通道配置值为 7 的 MPEG-4 Audio 轨道时，例如 7.1 AAC，路径 API 的tracks2中 codecProps 字段此前可能错误显示：

"channelCount": 7

但该轨道实际拥有 8 个声道。

新版本会将通道配置值 7 正确报告为 8 声道。1 至 6 声道的显示行为不变。

关联编号：6405。

五、MPEG-TS 解析与媒体处理优化

支持包含大视频帧的 MPEG-TS 轨道读取

MPEG-TS 流中的大视频帧可能延迟音频包到达，而音频包是轨道解析所需要的数据。

本版本提高了最大缓冲区大小，以适应大视频帧场景，改善 MPEG-TS 轨道读取能力。

关联编号：4791。

停止验证 AC-3 与 EAC-3 帧

MPEG-TS 解析时，不再验证 AC-3 与 EAC-3 帧。

此类帧验证并不是 MPEG-TS 解析正常工作所必需的，同时会降低性能。因此新版本移除了这部分验证。

关联编号：395。

六、Media-Over-QUIC 更新

客户端不再等待服务端 SETUP 后才发送 SETUP

MoQ 客户端现在可以在不等待服务端 SETUP 的情况下发送客户端 SETUP。

关联编号：6396。

记录所有入站与出站 MoQ 消息

MoQ 现在会记录每一条入站和出站消息。

关联编号：6404。

修复 MoQ 中 7.1 AAC 声道数与配置映射

MoQ 客户端读取 7.1 AAC 路径时，旧版本中的 catalog 可能将声道数报告为 7，而实际应为 8。

同时，MoQ 源或发布者发送"channels": 8时，旧版本可能写入保留的通道配置值 8。正确的方式是使用通道配置值 7 来表示 8 个声道。

新版本调整后：

• 通道配置值 7 会被报告为 8 声道；

• 8 声道输入会使用配置值 7；

• 7.1 轨道在转发时会继续保留配置值 7；

• 其他声道数量的处理方式保持不变。

关联编号：6406。

支持多个 MoQ 草案版本

MoQ 新增支持以下草案版本：

• draft-22

• draft-21

• draft-20

关联编号：6403。

七、RTMP 功能更新

保留 tcURL 查询参数

RTMP 在拼接 tcURL 与流密钥时，现在会正确保留 tcURL 中已有的查询参数。

新逻辑会分别解析 tcURL 和流密钥，再拼接二者的路径，从而实现以下效果：

• tcURL 原有查询参数得以保留；

• 流密钥中的查询参数会进行合并；

• 已转义路径能够被保留；

• 不需要自定义转义时，不会不必要地填充 RawPath。

关联编号：133。

支持以问号开头的流密钥

RTMP 现在支持以问号开头的流密钥。

关联编号：141。

暴露 ErrReaderUnpublish 用于优雅关闭

RTMP 库现在暴露 ErrReaderUnpublish，以便 mediamtx 在读取端取消发布时进行优雅关闭处理。

同时补充了 ErrReaderUnpublished 的补丁覆盖。

关联编号：139。

八、HLS 更新

修复 MPEG-TS HLS 变体无法处理 Opus 轨道的问题

当 HLS 变体设置为 MPEG-TS 时，如果流中包含 Opus 音频，例如通过 WebRTC 发布的 H264 与 Opus 流，旧版本可能无法通过 HLS 播放。

此前，复用器会因 MPEG-TS HLS 仅支持 MPEG-4 Audio 而启动失败，播放列表请求返回 500 错误，导致视频也无法访问。

现在，当 HLS 变体为 MPEG-TS 时，系统会跳过不是 MPEG-4 Audio 的音频轨道，行为与此前对 KLV 轨道的处理一致。

如果流中仅有这种不受支持的音频轨道，则会返回 ErrNoSupportedCodecs，而不是在复用器启动时失败。

关联编号：6387。

修复 MPEG-TS HLS 变体无法处理多个 AAC 轨道的问题

当 HLS 变体设置为 MPEG-TS，且流中含有多个 MPEG-4 Audio 轨道时，例如通过 SRT 接收的 H264 加两个 AAC 轨道，旧版本可能启动失败。

原因是 MPEG-TS HLS 只支持单个音频轨道。此前复用器会报错，播放列表请求可能返回 500，视频同样无法读取。

现在，系统会保留第一个 MPEG-4 Audio 轨道，并跳过后续 MPEG-4 Audio 轨道，处理方式与跳过其他不支持音频编码的策略一致。

关联编号：6394。

HLS 复用器支持 H264 Recovery Point

HLS 复用器现在支持 H264 Recovery Point。

关联编号：403。

HLS 不再静默跳过异常 H264 单元

HLS 处理 H264 时，不再静默跳过缺少 IDR 和非 IDR 图像的单元。

关联编号：405。

增加 AI 警告

HLS 相关组件增加 AI 警告。

关联编号：406。

九、WebRTC 与 UDP 更新

禁止同时使用两个 WebRTC ICE Servers 配置字段

现在不允许同时使用webrtcICEServers与webrtcICEServers2。

关联编号：6367。

UDP 组播源支持 interface=all

UDP 组播源重新支持在所有具备组播能力的网络接口上监听数据包。

配置 UDP 组播 URL 时，可以在地址末尾增加：

interface=all

关联编号：6253。

十、树莓派摄像头更新

文字叠加支持换行

树莓派摄像头的文字叠加功能现在支持换行符。

关联编号：5763。

十一、依赖更新

本版本同步升级了多个依赖组件：

•bytefmt：从 v0.92.0 升级至 v0.95.0；

•gohlslib/v2：从 v2.4.6 升级至 v2.4.7；

•gortmplib：从 v1.0.4 升级至 v1.0.5；

•mediacommon/v2：从 v2.9.6 升级至 v2.9.7；

•gookit/color：从 v1.6.1 升级至 v1.6.3；

•argon2：从 v1.6.3 升级至 v1.6.4；

•ice/v4：从 v4.4.5 升级至 v4.4.8；

•webrtc/v4：从 v4.2.22 升级至 v4.2.24；

•go-proxyproto：从 v0.15.0 升级至 v0.16.0；

•quic-go：从 v0.63.0 升级至 v0.64.1；

•x/crypto：从 v0.57.0 升级至 v0.58.0；

•x/sync：从 v0.23.0 升级至 v0.24.0；

•x/sys：从 v0.48.0 升级至 v0.49.0；

•x/term：从 v0.46.0 升级至 v0.47.0；

•dtls/v3：从 v3.1.9 升级至 v3.1.13；

•sctp：从 v1.11.3 升级至 v1.12.0；

•x/net：从 v0.59.0 升级至 v0.61.0；

•x/text：从 v0.42.0 升级至 v0.43.0；

•mediamtx-rpicamera：从 v2.9.0 升级至 v2.9.1。

十二、安全性与二进制校验

发布二进制文件由发布工作流基于源代码编译生成。该流程完全可见，可防止生成产物在构建过程中被修改或受到外部干扰。

二进制文件的校验和也会通过 GitHub Attestations 发布到公开区块链中，可使用以下命令进行验证：

ls mediamtx_* | xargs -L1 gh attestation verify --repo bluenviron/mediamtx

也可以下载checksums.sha256文件，再通过以下命令校验二进制文件：

cat checksums.sha256 | grep "$(ls mediamtx_*)" | sha256sum --check

总结

代码地址：github.com/bluenviron/mediamtx

mediamtx v1.21.3 的更新核心集中在稳定性、协议兼容性、录制准确性和运维可观测性。

HTTP2 支持恢复、转发热重载优化、日志动态重建修复、致命监听错误退出以及证书加载器协程回收，提升了服务端运行稳定性。录制部分针对时区、夏令时、H264 随机访问点、VP9 尺寸、MPEG 音频时间戳和 RTP 时间断点进行了集中修复，使 fMP4 录制的文件信息和分段时长更加可靠。

在协议兼容性方面，MoQ 支持多个草案版本，RTMP 改善 tcURL 与流密钥拼接，HLS MPEG-TS 变体能够更合理地跳过不支持的音频轨道，UDP 组播支持全部可用接口监听。再加上内部用户管理 API、JWT 会话到期关闭、AAC 7.1 声道映射修复以及多项依赖升级，v1.21.3 为多协议流媒体服务的部署、维护和扩展提供了更完善的基础。

我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”，发消息可获得面试资料，让AI助力您的未来发展。