企业官网建设流程全解析

• 后端
• 音视频

导读

rust/types/CHANGELOG.md记录了 mediasoup Rust 生态中独立类型库mediasoup-types（crate 名mediasoup-types，当前版本 0.5.0）从 0.2.1 到 0.4.0 的版本演进脉络，涵盖 SCTP 内建协议栈切换、RTP 头部扩展 URI 枚举扩充、RTP 参数新增msid字段等关键变更。本文以该 CHANGELOG 为主线，结合仓库内 类型库源码 与 mediasoup-types README，逐条还原每次变更背后的类型设计与 WebRTC 协议语义，帮助 Rust 开发者理解该类型库的定位、核心数据结构的字段含义，以及在升级依赖时的破坏性变更注意事项。

一、类型库定位：为什么 mediasoup 需要独立的 Rust 类型 crate

在深入 CHANGELOG 之前，先明确mediasoup-types在整个项目中的角色。根据 rust/types/README.md 的说明，它提供 mediasoup 各 Rust crate 之间共享的核心类型、枚举与数据结构，既被主mediasoupcrate 使用，也被任何需要与 mediasoup 交互的 Rust 库、工具和应用使用。入口模块在 rust/types/src/lib.rs 中清晰列出：

• data_structures：ICE/DTLS/SCTP 状态、传输元组、指纹等通用数据结构；
• rtp_parameters：RTP 编解码器、头部扩展、编码层等 RTP 参数体系；
• scalability_modes：可伸缩性模式（SVC）枚举；
• sctp_parameters：SCTP 关联与流参数；
• srtp_parameters：SRTP 加解密参数。

依赖关系上，rust/types/Cargo.toml 显示该 crate 基于serde（含derive特性）做序列化、serde_json做 JSON 解析、thiserror做错误定义、once_cell与regex用于可伸缩性模式字符串解析，整体保持轻量、无 mediasoup 运行时依赖，便于作为独立类型契约被上下游复用。

注意：仓库根目录的 Cargo.toml 与 rust-scripts.mjs 用于构建、测试整个 Rust workspace，而mediasoup-types自身位于 rust/types 目录，其 API 文档对应docs.rs/mediasoup-types。

二、版本 0.2.1：作为独立 crate 的首次发布

CHANGELOG 记录的最早版本是 0.2.1，标注为：

Initial release as a standalone crate extracted frommediasoup（PR #1572）

从源码结构看，这一变更的本质是将原本内嵌在mediasoupcrate 中的类型定义抽离为独立 crate。其直接收益是：

• 类型契约解耦：应用代码、中间件库可以仅依赖mediasoup-types引入RtpParameters、RtpCapabilities、MediaKind等类型，而不必引入完整的 mediasoup 运行时；
• 语义边界清晰：类型定义与 worker 进程通信逻辑分离，后续的协议演进（如新增头部扩展）只需改动类型 crate，再同步主 crate。

README 中的最小使用方式（即 rust/types/README.md 的 Usage 章节）如下：

[dependencies] mediasoup-types = "X.Y.Z"

use mediasoup_types::{RtpCodecParameters, RtpCapabilities, MediaKind};

2.1 从源码看类型的序列化设计

独立发布的同时，类型库确立了贯穿至今的 serde 序列化约定，这在此后所有版本变更中反复出现：

• 枚举序列化为字符串：如MediaKind以#[serde(rename_all = "lowercase")]序列化为"audio"/"video"（见 rtp_parameters.rs 中的定义）；
• 结构体字段采用 camelCase：RtpCapabilities、RtpParameters等均标注#[serde(rename_all = "camelCase")]，与 mediasoup 的 JS API 及 worker 通道协议保持一致；
• 可选字段跳过序列化：大量字段使用#[serde(skip_serializing_if = "Option::is_none")]，避免输出冗余null。

这意味着所有版本新增的类型字段都能直接用于 JSON 通道通信与用户侧参数构造，是理解后续 CHANGELOG 变更的底层背景。

三、版本 0.3.0：RTP 头部扩展与 msid 支持

0.3.0 的变更集中在 RTP 参数体系，包含两项 PR：

3.1 RtpHeaderExtensionUri 新增 7 个变体（PR #1631）

CHANGELOG 原文：

RtpHeaderExtensionUri: AddSsrcAudioLevel,AbsSendTime,TransportWideCcDraft01,DependencyDescriptor,AbsCaptureTime,PlayoutDelayandMediasoupPacketIdvariants. RenameAudioLeveltoSsrcAudioLevel.

从 rtp_parameters.rs 中可看到完整的RtpHeaderExtensionUri枚举，它用 serde 将每个变体映射为对应的标准 URI 字符串：

两点值得注意：

1. 重命名语义对齐：AudioLevel更名为SsrcAudioLevel，与其真实 URIurn:ietf:params:rtp-hdrext:ssrc-audio-level对齐，避免与 RFC 6465 的 in-band 音频电平混淆；
2. 兜底变体：Unsupported使用#[serde(other)]捕获未知 URI 字符串，保证反序列化远端能力集时不会因未知扩展而整体失败，这与 mediasoup 对未知扩展“跳过但容忍”的处理策略一致。

3.2 RtpParameters 新增可选 msid 字段（PR #1634）

CHANGELOG 原文：

RtpParameters: Add optionalmsidfield (WebRTC MediaStream Identification, RFC 8830).

在 rtp_parameters.rs 的RtpParameters结构体中，msid位于rtcp之后、以Option<String>承载，并标注#[serde(skip_serializing_if = "Option::is_none")]：

pub struct RtpParameters { pub mid: Option<String>, // BUNDLE MID pub codecs: Vec<RtpCodecParameters>, pub header_extensions: Vec<RtpHeaderExtensionParameters>, pub encodings: Vec<RtpEncodingParameters>, pub rtcp: RtcpParameters, pub msid: Option<String>, // RFC 8830 MediaStream Identification }

msid让 mediasoup 在信令层面感知 WebRTC 的 MediaStream 标识（形如<stream-id> <track-id>），从而在转码/转发场景中保留媒体流归属信息。它是纯可选项：不设置时不影响既有调用。

3.3 相关测试印证

类型库为每个模块提供了配套单元测试，例如 rtp_parameters 测试 与 scalability_modes 测试，覆盖 MIME 类型解析、可伸缩性模式字符串解析等路径；主 crate 的集成测试（如 rust/tests/integration/webrtc_transport.rs）则验证了这些类型在实际传输流程中的可用性。

四、版本 0.4.0：内建 SCTP 协议栈与 SctpNegotiatedCapabilities

0.4.0 是 CHANGELOG 中影响面最大的破坏性变更，对应 PR #1806：

New built-in SCTP stack:

• RemoveNumSctpStreamstype.
• AddSctpNegotiatedCapabilitiestype.

4.1 移除 NumSctpStreams

在旧设计中，SCTP 关联需要显式指定发送/接收流数量（numSctpStreams，即 OS/MIS 字段）。新内建 SCTP 协议栈不再需要调用方预先声明流数量，因此NumSctpStreams类型被删除。这一变化与 worker 侧内建 SCTP 实现（见 worker/include/RTC/SCTP 与 worker/src/RTC/SCTP 目录下的 association/rx/tx 等实现）直接对应：内建协议栈在关联建立阶段自动协商流数量。

4.2 新增 SctpNegotiatedCapabilities

替代方案是新增SctpNegotiatedCapabilities，仅在 SCTP 关联成功连接后可用。源码见 rust/types/src/sctp_parameters.rs：

#[serde(rename_all = "camelCase")] pub struct SctpNegotiatedCapabilities { pub negotiated_max_outbound_streams: u16, pub negotiated_max_inbound_streams: u16, }

两个字段分别表示协商后的最大出站/入站流数量，均由内建协议栈在握手过程中实际协商得出，而非调用方预先指定——这正是“移除 NumSctpStreams、改为协商结果”的设计意图。

4.3 兼容性遗留字段

为保持向后兼容，SctpParameters 中仍保留三个旧字段（源码注释明确标注“For backwards compatibility. Remove them in the future”）：

• os: u16（JSON 键名为"OS"）：出站流数量；
• mis: u16（JSON 键名为"MIS"）：入站流数量；
• max_message_size: u32：旧的最大消息尺寸字段。

同时新增了内建栈下的字段：max_send_message_size、max_receive_message_size、send_buffer_size、per_stream_send_queue_limit、max_receiver_window_buffer_size、is_data_channel。升级到 0.4.0 后，若代码中直接构造SctpParameters，应优先采用新字段，并为未来移除遗留字段做好准备。

4.4 源码中的实际使用

从仓库搜索可见，SctpNegotiatedCapabilities已被 pipe_transport.rs、plain_transport.rs、webrtc_transport.rs 等路由模块引用，并出现在 webrtc_transport 集成测试 与 plain_transport 集成测试 中，作为关联连接后查询协商结果的标准途径。

五、NEXT：当前未发布变更与升级路线

CHANGELOG 顶部保留### NEXT占位，用于记录尚未发布的下一个版本变更。当前仓库中mediasoup-types的版本号已推进到0.5.0（见 rust/types/Cargo.toml），因此可以推断：自 0.4.0 之后存在一批已提交但尚未写入 CHANGELOG 的变更。在实际升级时，建议开发者：

1. 以仓库内 CHANGELOG.md 顶部NEXT区块为准，核对目标版本对应的破坏性变更；
2. 关注NumSctpStreams相关代码的清理进度，避免继续使用遗留的os/mis字段；
3. 结合 types 目录测试 与 集成测试 验证类型行为。

六、版本演进之外：类型库核心数据结构速查

为便于读者在阅读 CHANGELOG 时定位对应类型，下表汇总了本次演进的直接载体及其文件位置：

值得展开的两个类型：

• ScalabilityMode：完整覆盖 W3C webrtc-svc 定义的 L/S 系列模式（L1T2、L2T2_KEY、S3T3h 等），并支持通过正则^LST([1-9][0-9]?)(_KEY)?解析自定义模式字符串（见 scalability_modes.rs），spatial_layers()/temporal_layers()/ksvc()提供层数查询；
• SctpStreamParameters：可靠性语义清晰——ordered=true时max_packet_life_time与max_retransmits必须为None；ordered=false时二者最多只能设置一个，并提供了new_ordered、new_unordered_with_life_time、new_unordered_with_retransmits三个构造器保证组合合法。

七、总结与升级建议

mediasoup-types的 CHANGELOG 虽然简短，却精准勾勒了类型契约的两条演进主线：

1. 协议覆盖面扩张（0.3.0）：RTP 头部扩展从基础 MID/RID 扩展到拥塞控制（transport-cc）、AV1 依赖描述符、自定义 packet-id 等，RTP 参数补全 RFC 8830msid，使 Rust 侧类型与 mediasoup v3 的完整能力对齐；
2. 传输栈重构（0.4.0）：内建 SCTP 协议栈取代依赖外部栈的方案，将流数量从“调用方预声明”改为“关联后协商”，以SctpNegotiatedCapabilities暴露结果，并保留遗留字段以兼容旧代码。

对使用方而言，升级时需重点检查：是否还在构造NumSctpStreams（0.4.0 已删除）、是否依赖RtpHeaderExtensionUri::AudioLevel（0.3.0 已更名为SsrcAudioLevel）、以及是否主动使用了新增的msid字段。结合本仓库的 类型源码、mediasoup-types README 与 worker SCTP 实现，即可在升级前后完整验证类型行为与协议语义的一致性。

• 后端
• 音视频