Cloudflare Stream 配置完全指南：从环境变量、Wrangler 到签名密钥与 Webhook-酒店常州论坛

Cloudflare Stream 配置完全指南：从环境变量、Wrangler 到签名密钥与 Webhook

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本文是 Cloudflare Stream（无服务器点播与直播视频平台）的配置实战指南，聚焦于在 Cloudflare Deploy 技能栈中从零搭建 Stream 项目的安装、环境变量、wrangler 配置、签名密钥、Webhook 以及上传/直播/水印参数配置。读完本文，你将掌握如何为基于 Cloudflare Workers/Pages 的视频应用完成 SDK 安装、密钥体系设计与安全配置，并能结合仓库中的 Stream 参考文档快速落地一个生产可用的视频上传与播放服务。

概述：Stream 配置在整个项目中的位置

Cloudflare Stream 提供视频上传、编码、存储与全球分发的一体化能力，无需自建转码与 CDN 基础设施。在cloudflare-deploy技能体系中，Stream 属于"媒体与内容"产品线（参见 SKILL.md 决策树中的 Media/Content 分支）。官方建议的阅读顺序是：先读 configuration.md 完成项目初始化，再按需深入 api.md（点播 API）、api-live.md（直播 API）、patterns.md（全栈流程）与 gotchas.md（排错）。

本文对应文档中的第一环——配置。所有配置项都以 Workers 运行时 + wrangler 部署为默认前提，因为 Stream 的官方 SDK 与签名密钥、Webhook 机制天然服务于边缘函数场景。

安装：三组核心依赖

配置的第一步是安装官方 SDK 与辅助库：

# 官方 Cloudflare SDK（Node.js、Workers、Pages） npm install cloudflare # React 组件库（内置 Stream Player 封装） npm install @cloudflare/stream-react # TUS 断点续传（大文件上传） npm install tus-js-client

三者的职责边界：

cloudflare：服务端 SDK，用于创建直传 URL、管理视频、操作 live inputs。仓库中所有后端示例（如 api.md 的 Direct Creator Upload）均通过new Cloudflare({ apiToken: env.CF_API_TOKEN })初始化。
@cloudflare/stream-react：前端 React 播放器组件。在 patterns.md 中它的最小用法是<Stream controls src={videoId} responsive />，配合签名 token 时传入${videoId}?token=${token}。
tus-js-client：面向超过 500MB 的大文件。TUS 协议支持分块（默认示例chunkSize: 50MB）与断点重试（retryDelays: [0, 3000, 5000, 10000, 20000]），详见 patterns.md 的 TUS Resumable Upload。

前提说明：使用 SDK 需要 Node.js 环境或 Workers 运行时支持（Workers 原生支持 Web 标准 API，SDK 可直接在 Worker 内运行，参见 workers 参考）。

环境变量：必填与可选清单

# Required CF_ACCOUNT_ID=your-account-id CF_API_TOKEN=your-api-token # For signed URLs (high volume) STREAM_KEY_ID=your-key-id STREAM_JWK=base64-encoded-jwk # For webhooks WEBHOOK_SECRET=your-webhook-secret # Customer subdomain (from dashboard) STREAM_CUSTOMER_CODE=your-customer-code

变量语义与使用场景：

变量	必填性	用途	关联 API/功能
`CF_ACCOUNT_ID`	必需	API 路径前缀`accounts/{account_id}`，以及 SDK 调用中的`account_id`参数	所有上传/直播/管理 API
`CF_API_TOKEN`	必需	Bearer 鉴权令牌，初始化 SDK 与所有`curl`调用	全局
`STREAM_KEY_ID`	高流量时	自签名 JWT 的`kid`（Header 声明），对应签名密钥的`id`	签名 URL，见 patterns.md 的 Self-Sign JWT
`STREAM_JWK`	高流量时	base64 编码的 JWK 私钥，用于 RS256 签名	同上
`WEBHOOK_SECRET`	使用 Webhook 时	校验`Webhook-Signature`的 HMAC-SHA256 密钥	Webhook 通知，见 patterns.md 的 Webhook Handler
`STREAM_CUSTOMER_CODE`	播放时	拼接`customer-<CODE>.cloudflarestream.com`子域名，用于 iframe 与 HLS/DASH 播放地址	播放器，见 api.md 的 Playback APIs

从源码结构看，签名密钥（STREAM_KEY_ID/STREAM_JWK）只在日签发 token 超过约 1,000 个时才有必要：低流量可直接调用POST /stream/{video_id}/token换取签名 URL（见 api.md 的 Signed URLs），高流量则改为本地 RS256 自签名，避免每次请求打 API。

Wrangler 配置：将变量接入 Worker

{ "name": "stream-worker", "main": "src/index.ts", "compatibility_date": "2025-01-01", // 新项目请使用当前日期 "vars": { "CF_ACCOUNT_ID": "your-account-id" } // 敏感值请用 secret 存储： // wrangler secret put CF_API_TOKEN // wrangler secret put STREAM_KEY_ID // wrangler secret put STREAM_JWK // wrangler secret put WEBHOOK_SECRET }

要点说明：

vars放非敏感配置：CF_ACCOUNT_ID这类非密钥值可直接写入vars，Worker 中通过env.CF_ACCOUNT_ID读取。
wrangler secret put放敏感值：CF_API_TOKEN、签名密钥与 Webhook 密钥必须走 secrets。仓库的 wrangler 配置参考强调：vars与各类 bindings 属于不可继承字段，每个环境需单独定义；而name、main、compatibility_date等可被环境继承。若需多环境，可在env下按环境覆盖vars并用wrangler deploy --env production部署。
compatibility_date用当前日期：文档明确建议新项目使用当前日期，以启用最新兼容性行为。
本地开发：配置完成后用npx wrangler dev本地调试，用npx wrangler deploy发布（命令清单见 workers 参考）。

签名密钥：为高流量自签名令牌而生

当日均签发 token 达到数千级别时，继续走POST /stream/{video_id}/tokenAPI 会产生不必要的开销与配额压力。此时应一次性创建签名密钥，在服务端本地用 RS256 自签名 JWT。

创建密钥（只需执行一次）：

curl -X POST \ "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/keys" \ -H "Authorization: Bearer <API_TOKEN>" # 保存响应中的 id 和 jwk（base64 编码）

存入 secrets：

wrangler secret put STREAM_KEY_ID wrangler secret put STREAM_JWK

配合使用：从代码结构可以确认，STREAM_KEY_ID会作为 JWT Header 的kid声明，STREAM_JWK经 base64 解码后由crypto.subtle.importKey('jwk', ..., { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign'])导入用于签名（完整实现见 patterns.md 的 Self-Sign JWT）。该流程可与访问规则结合，在 JWT payload 中嵌入accessRules实现地理/IP 限制。

Webhooks：从轮询到事件推送

视频处理完成、状态变更等事件可通过 Webhook 推送到你的 Worker，替代低效的轮询（patterns.md 的最佳实践明确建议 "Use webhooks over polling"）。

设置 Webhook URL：

curl -X PUT \ "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/webhook" \ -H "Authorization: Bearer <API_TOKEN>" \ -H "Content-Type: application/json" \ -d '{"notificationUrl": "https://your-worker.workers.dev/webhook"}' # 保存响应返回的 secret，用于签名校验

存储 secret：

wrangler secret put WEBHOOK_SECRET

校验流程（见 patterns.md 的 Webhook Handler）：请求头携带Webhook-Signature，格式为time=<ts>,sig1=<hmac>；服务端用WEBHOOK_SECRET对${timestamp}.${body}计算 HMAC-SHA256 并比对sig1，同时允许5 分钟的时间戳漂移。校验失败返回 401。需要留意的是，按 gotchas.md 的说明，Cloudflare 对 Webhook 有最多 5 次指数退避重试、单次超时 30 秒的限制。

上传 / 直播 / 水印配置参数

// 直传（Direct upload）配置 const uploadConfig = { maxDurationSeconds: 3600, // 视频最大时长（秒），防止滥用 expiry: new Date(Date.now() + 3600000).toISOString(), // 上传 URL 过期时间 requireSignedURLs: true, // 私有内容：要求签名 token 才能播放 allowedOrigins: ['https://yourdomain.com'], // 防盗链白名单 meta: { creator: 'user-123' } // 自定义元数据 }; // 直播输入（Live input）配置 const liveConfig = { recording: { mode: 'automatic', timeoutSeconds: 30 }, // 自动录制，断流 30s 后停止 deleteRecordingAfterDays: 30 // 录制产物 30 天后自动删除 }; // 水印（Watermark）配置 const watermark = { name: 'Logo', // 水印名称 opacity: 0.7, // 不透明度 0~1 padding: 20, // 边距（像素） position: 'lowerRight', // 位置：如 lowerRight scale: 0.15 // 相对视频尺寸的缩放比例 };

参数说明与源码印证：

maxDurationSeconds：直传/直播录制时的时长上限。超出会触发ERR_DURATION_EXCEED_CONSTRAINT错误（见 gotchas.md），生产环境建议显式设置以控制成本与滥用。
recording.mode取值automatic（录制全部直播）或off（不录制）；timeoutSeconds表示流结束后多少秒停止录制。requireSignedURLs与allowedOrigins同样适用于录制转点播（VOD）的播放（见 api-live.md 的 Recording Settings）。
allowedOrigins：限定可嵌入播放器的域名，若遗漏会导致播放器无限加载（CORS 问题，见 gotchas.md）。
meta：随视频携带的自定义键值对，可用于记录创作者、业务标签，配合 api.md 的视频管理中的search检索使用。

访问规则与播放器配置

// 访问规则：放行 US/CA，拒绝 CN/RU，或使用 IP 白名单 const geoRestrict = [ { type: 'ip.geoip.country', action: 'allow', country: ['US', 'CA'] }, { type: 'any', action: 'block' } ]; // iframe 播放器参数 const playerParams = new URLSearchParams({ autoplay: 'true', muted: 'true', preload: 'auto', defaultTextTrack: 'en' });

访问规则（Access Rules）嵌入在签名 token 的 payload 中，按规则顺序先匹配先生效。上例先放行美加地区，其余（any）一律拒绝，实现地理限制；action同样支持block直接封禁特定国家（如 CN/RU）。规则类型与签名 token 的完整组装方式见 patterns.md 的自签名 JWT 示例——payload 中直接包含accessRules数组。

播放器参数通过URLSearchParams拼接到 iframe 的src上：

<iframe src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/iframe?autoplay=true&muted=true&preload=auto&defaultTextTrack=en" style="border: none;" height="720" width="1280" allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;" allowfullscreen="true" ></iframe>

其中<CODE>即STREAM_CUSTOMER_CODE。若需 HLS/DASH 原生流或缩略图地址，直接拼接customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/manifest/video.m3u8（HLS）或/manifest/video.mpd（DASH），见 api.md 的 Playback APIs。

完整配置串联：一个可落地的初始化顺序

综合本文内容，生产项目的推荐配置顺序如下：

npm install cloudflare @cloudflare/stream-react tus-js-client；
在 dashboard 获取CF_ACCOUNT_ID与 API Token，写入.dev.vars或 wranglervars/secrets；
按需curl创建签名密钥（高流量）并wrangler secret put STREAM_KEY_ID/STREAM_JWK；
curl设置 Webhook URL 并保存WEBHOOK_SECRET；
在wrangler.jsonc中配置name、main、compatibility_date、vars；
编写 Worker：初始化 SDK → 创建直传 URL → 前端上传 → 配置播放器与访问规则。

配置完成后，可继续阅读 api.md 实现点播上传与播放，或 patterns.md 获取直传、TUS、Webhook 校验与自签名 JWT 的完整代码，配合 wrangler 配置参考理解环境与 bindings 的高级用法。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析