企业官网建设流程全解析

2026年10月10日，mediamtx 发布 v1.21.2 最新版本。本次更新以“修复与改进”为主，覆盖通用逻辑、API、Media-Over-QUIC、RTSP、RTMP、HLS、WebRTC 以及依赖库升级等多个方向。

v1.21.2 没有引入新的功能模块，而是集中处理实际运行中可能出现的连接异常、数据包丢失、内存占用、认证阻塞、并发竞争、死锁、播放器兼容性和异常请求导致崩溃等问题。对于使用 UDP、RTSP、RTMP、HLS、WebRTC、JWT 鉴权、API 配置管理的部署场景，这一版本带来了更稳健的行为表现。

版本信息

• 版本：v1.21.2
• 发布时间：2026年10月10日
• 类型：修复与改进版本

通用改进：优化 UDP、JWT、内存与 H264 处理

本次更新首先对连接关闭、鉴权请求、空数据报和视频编码单元处理进行了调整。

修复连接关闭时丢弃 UDP 数据包的问题

此前，在连接关闭过程中，只要出现错误，UDP 数据包就可能被丢弃，而不考虑数据包自身大小。

现在的逻辑变更为：仅当 UDP 数据包为空且同时发生错误时，才会将该数据包丢弃。这样可以避免连接关闭期间因错误状态导致正常 UDP 数据包被错误丢弃。

该修复对应 6278。

修正 YouTube RTMPS 地址文档

文档中此前提供的 YouTube RTMPS 地址存在错误。

v1.21.2 对该地址进行了修正，同时明确指出：当前不再需要配置指纹信息。

该修复对应 6286。

防止旧版凭据配置导致播放服务被无条件访问

当系统使用旧版凭据字段时，包括：

• readUser
• readPass
• publishUser
• publishPass

此前播放服务可能会向所有访问者开放，而不是仅向具备读取凭据的用户开放。

v1.21.2 调整后，播放服务仅允许使用 readUser 与 readPass 的用户获得访问权限，从而避免旧版凭据场景下出现任何人都能访问播放服务的问题。

该修复对应 6311。

JWT 鉴权：未携带令牌时不再请求 JWKS

此前，JWT 鉴权流程会在检查请求是否携带令牌之前，先去获取 JWKS。

这会导致匿名请求也触发向 JWKS 服务端发起外部请求。例如：

• 第一次未认证的 RTSP DESCRIBE 请求；
• 返回 401 之前的 HLS 请求；
• 其他没有携带 JWT 的匿名访问请求。

更严重的是，JWKS 获取过程发生在管理器写锁持有期间。如果 JWKS 服务响应缓慢、不可达或异常，匿名客户端就可能不断触发外部 JWKS 请求，并使所有 JWT 鉴权过程受到阻塞。

v1.21.2 对此进行了优化：

• 如果请求没有携带 JWT，直接返回“JWT 未提供”；
• 在确认请求携带 JWT 之前，不再访问 JWKS；
• 增加 JWKS HTTP 响应状态码检查；
• 非 2xx 的 JWKS 响应将被直接拒绝。

此前，如果 JWKS 服务返回错误页，程序可能会将错误页直接交给 JSON 解码器，最终表现为不清晰的 JSON 解析错误。更极端的情况下，如果错误响应恰好是合法 JSON，该内容还可能被缓存为密钥集合一小时。

现在，非 2xx 响应会按状态码被明确拒绝。对于携带 JWT 且 JWKS 服务正常的请求，原有行为保持不变。

该修复对应 6274。

修复可回退读取器可能造成内存耗尽的问题

空 UDP 数据报可能导致不必要的条目分配，从而增加内存消耗，并可能引发 OOM 问题。

v1.21.2 修复了空数据报导致无意义分配的情况，避免这些空数据包不断创建不必要的内部对象。

该修复来自 mediacommon 383。

H264：撤销对独立 SEI 单元的兼容处理

此前曾针对独立 SEI 单元增加支持，但此类单元现在会在更上游的位置被过滤，因此不再需要在该位置继续兼容。

v1.21.2 撤销了此前对独立 SEI 单元的支持逻辑。如果后续因此产生新的问题，则需要通过问题反馈进行进一步调整。

该变更来自 mediacommon 142 的回退，以及 mediacommon 384。

H264：DTS 提取器支持 SEI 恢复点

v1.21.2 的 DTS 提取器开始支持 H264 中的 SEI recovery point 消息。

SEI recovery point 的负载类型为 6。现在，系统会将其视为随机访问点，其行为类似于 H265 中的 CRA。

这样，DTS 提取器可以从恢复点之后的第一个编码帧重新初始化自身状态。

该改进对应 mediacommon 341。

API 改进：修复 RTSP 会话竞争、密码覆盖与关闭死锁

API 相关更新主要处理并发操作、密码配置回写和 API 重载期间的死锁问题。

修复踢出 RTSP 会话时的竞争条件

当通过 API 踢出 RTSP 会话时，系统此前可能发生竞争条件。

v1.21.2 修复了该问题，涉及 6260 与 6275。

配置补丁不再将空字符串写入密码

部分用户会调用/config/global/get获取配置内容，再将返回结果提交给/config/global/patch。

由于配置读取接口现在会对密码进行脱敏，并将密码字段替换为""，这些空字符串如果被直接用于补丁更新，就可能被当作实际密码写入，导致认证被破坏。

v1.21.2 调整后：

• /config/global/patch会忽略值为""的密码字段；
• 原本已经配置的密码将保持不变；
• 脱敏后的密码字段不会再意外覆盖真实密码。

相关讨论地址为：

https://github.com/bluenviron/mediamtx/issues/6287

该修复涉及 6141 与 6292。

修复 API 重载期间的死锁

此前，当 API 正在关闭时，某个/config接口请求可能正在等待服务端回复。

与此同时，服务端在关闭 API 时又会等待全部 API 接口请求结束，从而形成相互等待：

• /config请求等待服务端响应；
• 服务端等待 API 请求返回；
• API 请求无法结束；
• 服务端关闭流程无法继续。

v1.21.2 通过在 API 关闭时取消 API 接口到服务端的请求，解决了这一死锁问题。

该修复涉及 6280、6279 和 6310。

Media-Over-QUIC 改进：目录轨道名称标准化

Media-Over-QUIC 中的 catalog 轨道名称此前为.catalog。

该名称不符合标准。

v1.21.2 将 catalog 轨道名称调整为：

catalog

该修复对应 6268。

RTSP 改进：读取错误、UDP 缓冲区、SEI 单元与 JPEG RTP 支持

RTSP 部分包含多个稳定性和兼容性改进，涉及读取错误处理、静态源参数生效时机、错误返回码、H264/H265 数据过滤及 RTP/JPEG 实现。

出现读取错误时停止转发

此前，RTSP 数据在出现读取错误后，转发流程可能仍继续进行。

v1.21.2 调整为：一旦发生读取错误，停止继续转发。

该修复对应 6266。

路径级 rtspUDPReadBufferSize 首次连接立即生效

RTSP 静态源此前会先创建客户端，再读取路径级别的rtspUDPReadBufferSize配置。

这会导致该配置无法在第一次连接时生效，而是要等到后续重新连接时才会传递给客户端。

v1.21.2 将该参数的计算时机提前到客户端创建之前，使路径级rtspUDPReadBufferSize在第一次连接时即可生效。

这一行为与 MPEG-TS 源、RTP 源的处理方式保持一致，也恢复了此前某次修改之前的行为。

该修复对应 6291。

调整部分 RTSP 方法的错误返回码

RTSP 服务端部分方法的错误返回码进行了调整。

该改动来自 gortsplib 1091 与 1174。

过滤独立存在的 H264/H265 尾随 SEI 单元

部分摄像机可能生成非标准的 H264/H265 访问单元。这类访问单元仅包含一个 SEI 单元，并且该 SEI 位于其他单元之后。

这类数据会给下游组件带来多个问题，包括：

• DTS 提取器处理异常；
• 录像模块处理异常；
• H264/H265 数据流解析兼容性下降。

此前，H265 DTS 提取器曾被调整以兼容这种数据，但类似问题又在 H265 场景中再次出现。

v1.21.2 选择从源头过滤这类独立存在、且作为尾随单元出现的 H264/H265 SEI 数据，从而避免问题继续传递到后续处理流程。

相关变更涉及 3614、mediacommon 142、6257、mediacommon 382 以及 gortsplib 1184。

所有解码器至少返回 1 字节

RTSP 相关解码器现在保证至少返回 1 字节数据。

该改进来自 gortsplib 1185。

补全 RTP/JPEG 实现

v1.21.2 完善了 RTP/JPEG 的实现，新增对 restart header 的支持。

同时，JPEG 类型支持范围限定为：

• JPEG 类型 0；
• JPEG 类型 1。

该改进来自 gortsplib 1187。

RTMP 改进：连接异常识别、并发写入与消息处理兼容性提升

RTMP 模块本次改进主要面向断开连接识别、写入安全性、发布端消息积压、视频命令帧和空音频消息兼容。

服务端写入时也检测读取错误

此前，系统主要依赖写入错误判断 RTMP 连接是否已经断开。

但是，在服务端持续写入时，连接可能已经发生读取错误，而写入操作未必立刻报错。

v1.21.2 增加了读取错误检查，在服务端写入期间也能够识别断开的 RTMP 连接。

该修复对应 6267。

rawmessage.Write 改为线程安全

rawmessage.Write现在具备线程安全能力，避免并发写入场景下的异常行为。

该改进来自 gortmplib 136。

Writer 主动排空入站消息

有些 RTMP 服务端即使客户端处于推流状态，也会周期性发送消息。

此前，如果这些入站消息没有被读取，它们会填满内部连接缓冲区，最终导致周期性断开连接。

v1.21.2 中，Writer 也会主动读取并排空入站消息，避免这些消息在内部缓冲区不断积压。

该改进涉及 5776 和 gortmplib 132。

支持 FLV 视频命令帧并跳过空音频消息

部分服务端会在第一个视频帧之前发送视频信息或命令帧。

这种视频命令帧通常为 2 字节消息，包含：

• 帧类型 5；
• 一个命令字节，例如开始 seek 或结束 seek。

此前，视频消息反序列化会因为长度不足而拒绝该消息，进而导致整个连接中止。

v1.21.2 对视频消息进行了扩展：

• 增加Video.FrameType字段；
• 帧类型包括关键帧、互帧和命令帧；
• 增加Video.Command字段；
• 原有Video.IsKeyFrame被弃用，建议使用FrameType；
• Reader 会跳过命令帧，因为命令帧不承载媒体数据。

此外，部分服务端还会在第一个音频帧之前发送空音频消息。

此前，空音频消息会因为消息体字节不足而被拒绝，并导致连接中止。

v1.21.2 对空音频消息的处理方式如下：

• 空消息体会被解析为Codec = 0的 Audio 消息；
• 不设置其他字段；
• 再次序列化时仍会恢复为空消息体；
• Reader 会跳过该类消息，因为它们不携带媒体数据；
• 行为与 FFmpeg 的处理方式一致。

该改进来自 gortmplib 128。

Video.Type 更名为 Video.PacketType

为避免与新增的Video.FrameType字段产生混淆，原有的：

message.Video.Type

更名为：

message.Video.PacketType

该改进来自 gortmplib 138。

HLS 改进：Delta 更新保留 EXT-X-MAP

HLS Delta 更新此前生成时没有包含EXT-X-MAP。

但对于没有被跳过的标签，Delta 更新中必须继续保留这些标签。

如果 Delta 更新在跳过分片时缺失EXT-X-MAP，部分客户端会在第一次出现这种 Delta 更新时停止播放，并出现播放错误。

v1.21.2 修复后，Delta 更新会保留EXT-X-MAP。

该改进来自 gohlslib 397。

WebRTC 改进：修复特制 WHEP 请求可能引发的崩溃

此前，某些经过特殊构造的 WHEP 请求可能导致系统发生 panic。

触发条件是：WHEP 请求中的 SDP 不包含媒体描述。

v1.21.2 修复了这一问题，避免无媒体描述的 SDP 请求导致程序异常崩溃。

该修复涉及 6301 与 6309。

依赖更新

v1.21.2 同步升级了多项依赖库。

• Go：从 1.26 升级到 1.27
• code.cloudfoundry.org/bytefmt：从 v0.90.0 升级到 v0.92.0
• github.com/bluenviron/gohlslib/v2：从 v2.4.5 升级到 v2.4.6
• github.com/bluenviron/gortmplib：从 v1.0.3 升级到 v1.0.4
• github.com/bluenviron/gortsplib/v5：从 v5.6.6 升级到 v5.6.7
• github.com/bluenviron/mediacommon/v2：从 v2.9.5 升级到 v2.9.6
• github.com/datarhei/gosrt：从 v0.11.1-0.20260812091715-a77b40bb4b76 升级到 v0.12.0
• github.com/gin-contrib/pprof：从 v1.5.5 升级到 v1.5.6
• github.com/go-git/go-billy/v5：从 v5.9.1 升级到 v5.9.2
• github.com/go-git/go-git/v5：从 v5.19.2 升级到 v5.19.3
• github.com/pion/ice/v4：从 v4.4.2 升级到 v4.4.5
• github.com/pion/interceptor：从 v0.1.48 升级到 v0.1.49
• github.com/pion/rtcp：从 v1.2.17 升级到 v1.2.19
• github.com/pion/transport/v4：已移除
• github.com/pion/webrtc/v4：从 v4.2.20 升级到 v4.2.22
• github.com/quic-go/quic-go：从 v0.62.0 升级到 v0.63.0
• github.com/pion/datachannel：从 v1.6.2 升级到 v1.6.3
• github.com/pion/dtls/v3：从 v3.1.8 升级到 v3.1.9
• github.com/pion/mdns/v2：从 v2.2.0 升级到 v2.2.2
• github.com/pion/sctp：从 v1.11.1 升级到 v1.11.3
• github.com/pion/srtp/v3：从 v3.0.15 升级到 v3.1.3
• github.com/pion/stun/v4：从 v4.0.0 升级到 v4.0.1
• github.com/pion/turn/v5：从 v5.1.0 升级到 v5.1.2
• github.com/pjbgf/sha1cd：从 v0.6.0 升级到 v0.7.0
• github.com/pion/transport/v5：新增 v5.1.1

安全说明：发布流程与二进制校验

mediamtx 的二进制文件由 Release 工作流从源代码编译生成。

该流程完全公开可见，用于防止构建产物在生成过程中被修改或受到外部干扰。

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

lsmediamtx_*|xargs-L1gh attestation verify--repobluenviron/mediamtx

还可以下载checksums.sha256文件，并通过以下命令验证二进制文件校验和：

catchecksums.sha256|grep"$(lsmediamtx_*)"|sha256sum--check

总结

mediamtx v1.21.2 重点解决了 UDP 关闭期间的数据包丢失、匿名请求触发 JWKS 获取、旧版凭据下播放服务访问控制、空 UDP 数据报造成的内存问题、API 重载死锁、RTSP 静态源 UDP 缓冲区首次连接不生效、RTMP 消息积压与兼容性问题、HLS Delta 更新缺失EXT-X-MAP、WHEP 特制请求触发异常等问题。

同时，该版本完成了多项底层依赖升级，并继续提供可验证的发布构建与校验机制。