跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

自定义视频房间

最后更新 查看 MarkdownAgent 设置

构建一个浏览器房间:参与者发布摄像头和麦克风轨道,并接收彼此的媒体。该示例展示了 SFU 操作以及把它们连接起来的应用状态。

运行快速入门

打开源码

该示例为实验性内容。它包含后端认证和授权、重连和清理。其生产指南 ↗标出了你的应用需要集成的策略和控制。

工作原理

每个浏览器拥有独立的发布和接收 PeerConnection。每个连接对应一个 SFU 会话。这样两条协商生命周期彼此独立。

可信应用边界
Realtime SFU
浏览器参与者
Worker
Room Durable Object
生产者会话
消费者会话
Access identity + member capability · HTTP owns snapshots, SDP, and mutations
经过身份验证的 HTTP 请求
类型化 RPC
带标签的结果
已授权的 JSON + SDP
Separate producer and consumer PeerConnections · Separate per-session SDP queues
使用服务器凭据调用 SFU API
发布音频 + 视频
使用服务器凭据调用 SFU API
远端音频 + 视频
WebSocket 升级 + 一次性票据
fetch() 仅用于升级
room-changed 修订版本
通知触发经授权的 HTTP 快照

各组件职责如下:

组件 职责
浏览器 采集媒体、应用 SDP、接收轨道,并显示房间与连接状态
Worker 认证请求并路由已授权的应用操作
Durable Object 拥有房间成员、轨道发现、房间权限、重连状态和清理
Realtime SFU 接收已发布的音频/视频,并把每个接收会话所请求的轨道转发出去

休眠 WebSocket 会通知浏览器房间修订已变更。浏览器通过 HTTP 获取权威快照。周期性安全轮询也会检查变更。关闭通知套接字本身不会移除参与者。

发布与发现

发布端通过后端把 SDP offer 发送到 tracks/new。发布成功后,Durable Object 将轨道名称和媒体类型存入房间的发现状态。

其他参与者请求他们想要的发布内容。后端使用发布者会话 ID 和轨道名称,把这些请求转换为远程轨道订阅。该会话上的下一次变更开始前,必须先完成所需的 SFU offer/answer 交换。

共享模型见会话和轨道与协商。

身份与房间权限

已部署房间使用 Cloudflare Access 身份。浏览器还会收到应用成员资格,后续房间操作归该成员所有。房间名称、参与者 ID、轨道名称和 SFU 会话 ID 是定位符,不是凭据。

第一个成功加入的参与者成为房间创建者,可以终止房间。其他参与者只能退出自己的成员资格。该示例把提供方密钥保留在 Worker 上,并在调用 SFU 之前校验操作。

部署房间

完成本地快速入门以准备检出和 .dev.vars 文件。已部署房间使用 Workers、Durable Objects,以及保护 Worker 主机名的 Cloudflare Access 应用。

  1. 为你的 Worker 主机名完成 Access 应用设置。部署时保留 Access 团队域名和应用 audience。

  2. 在 realtime-examples/video-room 中运行部署脚本:

    npm run deploy -- --secrets-file .dev.vars --var "CF_ACCESS_TEAM_DOMAIN:<TEAM_NAME>.cloudflareaccess.com" --var "CF_ACCESS_AUD:<ACCESS_APPLICATION_AUDIENCE>"

    替换两个 Access 占位符。脚本会把 SFU 值上传为 Worker secrets。Worker 会在允许房间操作前校验匹配的 Access 身份。

  3. 在受保护的主机名上打开 /rooms/two-browser-check。登录后,先重复快速入门的两名参与者验证,再分享该部署。

重连与清理

应用定义了这些转换:

操作 行为
加入 创建成员资格以及发布和接收会话
刷新或替换失败连接 保留应用身份,替换 SFU 会话,重新发布并重建订阅
离开 关闭已知资源,并在浏览器清除成员资格前确认清理
终止房间 创建者结束房间,并开始为其参与者清理
被遗弃的标签页 心跳过期后安排清理;资源关闭失败时会重试

缺失心跳可能让被遗弃的参与者最多继续可见 45 秒,之后才符合清理条件。后端错误可能延迟完成。重复的重连设置失败可能需要重新加载页面。

移除部署

结束活动房间,并在移除后端前等待清理确认。在示例目录中删除 Worker:

npx wrangler delete

单独移除关联的 Access 应用。不再需要凭据时删除 .dev.vars。仅在所有使用该专用 SFU 应用的应用都已停止后再删除它。

改造房间

改造示例时,保留认证、资源所有权以及按会话的协商队列。通过浏览器/后端契约替换显示和在线状态行为,而不要信任浏览器提供的 SFU 标识符。

该示例未实现屏幕共享、聊天、录制、simulcast 控制或高级布局。速率限制、房间配额和 Access 策略配置仍由应用负责。

查看实现

追踪示例的信令和状态流 ↗以及 SDP 序列化 ↗。

故障排除

媒体、认证和生命周期症状请使用故障排除指南 ↗。

这篇文档对您有帮助吗?