WebTransport 协议

WebTransport 是基于 QUIC 协议（HTTP/3）的新一代 Web 传输技术。相比 WebSocket，它提供更低的延迟、原生多路复用和无队头阻塞特性，是面向未来的 Web 流媒体传输方案。

基本信息

属性	值
默认端口	4433
传输层	QUIC（HTTP/3）
推流	✅ 支持
拉流	✅ 支持
延迟	< 500ms
Feature Flag	webtransport

配置

Feature 启用

Cargo.toml

[features]
webtransport = ["dep:plugin-webtransport"]

配置文件

webtransport:
  enable: true
  listen_addr: "0.0.0.0:4433"
  cert_file: ""
  key_file: ""
  max_streams: 100
  enable_datagrams: true
  max_datagram_size: 65535
  idle_timeout: 30
  allowed_origins: []

配置项	类型	默认值	说明
enable	bool	true	是否启用插件
listen_addr	string	"0.0.0.0:4433"	监听地址
cert_file	string	""	TLS 证书文件路径
key_file	string	""	TLS 私钥文件路径
max_streams	u32	100	每连接最大并发流数
enable_datagrams	bool	true	启用 Datagram 支持
max_datagram_size	usize	65535	最大 Datagram 大小
idle_timeout	u64	30	空闲超时（秒）
allowed_origins	Vec	[]	允许的跨域来源

TLS 证书

WebTransport 基于 QUIC，要求 TLS 加密传输。

使用自签名证书（开发环境）：

如果不配置 cert_file 和 key_file，插件会自动生成自签名证书。

警告

自签名证书在浏览器中需要特殊处理。Chrome 可以通过启动参数信任自签名证书：

chrome --origin-to-force-quic-on=localhost:4433 \
       --ignore-certificate-errors-spki-list=<证书指纹>

使用正式证书（生产环境）：

webtransport:
  cert_file: "/etc/ssl/certs/server.crt"
  key_file: "/etc/ssl/private/server.key"

支持 Let’s Encrypt 等 CA 签发的证书。

浏览器支持

WebTransport 是较新的 Web API，目前支持情况：

浏览器	支持版本
Chrome	97+
Edge	97+
Firefox	114+
Safari	不支持（截至 2025）
Opera	83+

注意

WebTransport 是实验性技术，浏览器支持在持续改进中。建议在使用前检查 Can I Use 获取最新兼容性信息。

推流

浏览器推流示例

async function publish(streamPath) {
  const url = `https://localhost:4433/publish/${streamPath}`;
  const transport = new WebTransport(url);

  await transport.ready;
  console.log('WebTransport 连接已建立');

  // 获取摄像头
  const stream = await navigator.mediaDevices.getUserMedia({
    video: true,
    audio: true,
  });

  // 通过双向流发送媒体数据
  const bidiStream = await transport.createBidirectionalStream();
  const writer = bidiStream.writable.getWriter();

  // 发送媒体数据...
  // 具体编码和封装逻辑取决于应用层协议

  transport.closed.then(() => {
    console.log('WebTransport 连接已关闭');
  });
}

publish('live/test');

拉流

浏览器拉流示例

async function subscribe(streamPath) {
  const url = `https://localhost:4433/subscribe/${streamPath}`;
  const transport = new WebTransport(url);

  await transport.ready;
  console.log('WebTransport 连接已建立');

  // 读取服务端推送的数据
  const reader = transport.incomingBidirectionalStreams.getReader();

  while (true) {
    const { value: stream, done } = await reader.read();
    if (done) break;

    // 处理接收到的媒体数据
    const streamReader = stream.readable.getReader();
    while (true) {
      const { value, done } = await streamReader.read();
      if (done) break;
      // 解码并渲染...
    }
  }
}

subscribe('live/test');

使用 Datagram 模式

Datagram 模式适合对实时性要求极高、可容忍少量丢包的场景：

const transport = new WebTransport(url);
await transport.ready;

// 发送 Datagram
const writer = transport.datagrams.writable.getWriter();
await writer.write(new Uint8Array([/* 媒体数据 */]));

// 接收 Datagram
const reader = transport.datagrams.readable.getReader();
const { value } = await reader.read();

WebTransport vs WebRTC

特性	WebTransport	WebRTC
底层协议	QUIC (HTTP/3)	ICE/DTLS/SRTP
连接建立	简单（HTTP 升级）	复杂（ICE + SDP 交换）
NAT 穿透	不需要（类 HTTP）	需要 STUN/TURN
多路复用	原生支持	不支持
有序/无序	均支持	部分支持
服务端要求	需要 TLS 证书	需要 STUN/TURN 服务
浏览器支持	较新	成熟

选型建议

• 已有 HTTPS 基础设施：优先选择 WebTransport
• 需要 P2P 通信：选择 WebRTC
• 需要最大浏览器兼容：选择 WebRTC
• 追求架构简洁：选择 WebTransport

跨协议转发

WebTransport 推入的流可以通过其他协议播放：

# 通过 RTMP 拉流
ffplay rtmp://localhost:1935/live/test

# 通过 HTTP-FLV 拉流
ffplay http://localhost:8080/flv/live/test.flv

# 通过 HLS 拉流
ffplay http://localhost:8080/hls/live/test/index.m3u8

注意

WebTransport 使用 Opus 音频编码。转发到 RTMP/FLV/HLS 等协议时，引擎会自动将 Opus 转码为 AAC（需启用 transcode feature）。