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 SDKNode.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 标准 APISDK 可直接在 Worker 内运行参见 workers 参考。环境变量必填与可选清单# Required CF_ACCOUNT_IDyour-account-id CF_API_TOKENyour-api-token # For signed URLs (high volume) STREAM_KEY_IDyour-key-id STREAM_JWKbase64-encoded-jwk # For webhooks WEBHOOK_SECRETyour-webhook-secret # Customer subdomain (from dashboard) STREAM_CUSTOMER_CODEyour-customer-code变量语义与使用场景变量必填性用途关联 API/功能CF_ACCOUNT_ID必需API 路径前缀accounts/{account_id}以及 SDK 调用中的account_id参数所有上传/直播/管理 APICF_API_TOKEN必需Bearer 鉴权令牌初始化 SDK 与所有curl调用全局STREAM_KEY_ID高流量时自签名 JWT 的kidHeader 声明对应签名密钥的id签名 URL见 patterns.md 的 Self-Sign JWTSTREAM_JWK高流量时base64 编码的 JWK 私钥用于 RS256 签名同上WEBHOOK_SECRET使用 Webhook 时校验Webhook-Signature的 HMAC-SHA256 密钥Webhook 通知见 patterns.md 的 Webhook HandlerSTREAM_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这类非密钥值可直接写入varsWorker 中通过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 和 jwkbase64 编码存入 secretswrangler 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 URLcurl -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用于签名校验存储 secretwrangler secret put WEBHOOK_SECRET校验流程见 patterns.md 的 Webhook Handler请求头携带Webhook-Signature格式为timets,sig1hmac服务端用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 srchttps://customer-CODE.cloudflarestream.com/VIDEO_ID/iframe?autoplaytruemutedtruepreloadautodefaultTextTracken styleborder: none; height720 width1280 allowaccelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture; allowfullscreentrue /iframe其中CODE即STREAM_CUSTOMER_CODE。若需 HLS/DASH 原生流或缩略图地址直接拼接customer-CODE.cloudflarestream.com/VIDEO_ID/manifest/video.m3u8HLS或/manifest/video.mpdDASH见 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_JWKcurl设置 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），仅供参考