@hyperframes / gcp-cloud-run
谷歌云运行+云工作流适配器的超帧分布
呈现。OSS呈现原语(plan → renderChunk × n→
assemble)是本地文件路径上的纯函数；这个包裹是
在谷歌Cloud上运行它们的部署、编排和存储胶水
的GCP对应 @hyperframes/aws-lambda.
两面一包：
- 服务器端处理程序 （
./server)——一个云运行的HTTP服务 分派plan/renderChunk/assemble在请求主体的Action字段，桥接GCS↔每个OSS周围的容器的文件系统 原始的。这是捆绑的Dockerfile运行。 - 客户端SDK （
./sdk) - - -renderToCloudRun，getRenderProgress，deploySite，validateDistributedRenderConfig,computeRenderCost. 从Node进程（CI、CLI、应用程序后端）调用它们来驱动已部署的 堆栈不写GCS /工作流样板。
包裹是 不 的依赖 @hyperframes/producer;安装它
分开。
体系结构
GCS bucket ←→ Cloud Run service (plan / renderChunk / assemble)
▲
│ OIDC-authenticated http.post, one per step
│
Cloud Workflows (Plan → parallel RenderChunk → Assemble)
- 计划 下载项目压缩包并发布遗留版本v1 planDir tarball或v2清单加上内容寻址的工件。
- RenderChunk 并行运行
for循环在工作流程中，呈扇形展开 直到计划的块计数。每次调用呈现一个块并上传 它。 - 组装 下载每个块和音频，缝合最终 可交付，并上传。
每一步都是 POST 到同一个Cloud Run URL使用不同的 Action.
工作流累积每个步骤的小结果体并返回
{ Plan, Chunks, Assemble } 所以 getRenderProgress 可以读取帧总数和
每一步成功的持续时间。
规划运输选择
Plan v2是新渲染的默认版本。当 planProtocol 省略了,
renderToCloudRun 发送显式的 PlanProtocol: "v2" 所以SDK和
部署的工作流同意：
await renderToCloudRun({
// ...project, bucket, workflow, service, and config...
});
V2始终使用单独的清单和内容寻址的工件定位器 工作流。未知协议和完整性失败失败关闭；呈现 永远不要混合v1和v2工件。
作为已弃用的兼容性，单片v1传输仍然可用
通过 planProtocol: "v1" 明确。
更新订单
从相同的new中重新部署Cloud Run映像和Cloud工作流定义
在升级调用
renderToCloudRun。暂停新的渲染并消耗活动的工作流执行
在基础设施更新期间。较旧的工作流可以将省略默认为v1
或者缺少v2分支，而新的SDK发送显式的v2。如果基础设施
不能先重新部署，保留以前的SDK版本或通过
planProtocol: "v1" 直到Terraform/工作流重新部署完成
完成了。
Chrome运行时
不像Lambda适配器，它与250mb的ZIP上限作斗争
解压缩 @sparticuz/chromium 成 /tmp 在运行时-云运行运行一个
容器的形象。这个 Dockerfile 安装相同的固定
chrome-headless-shell 生成渲染器使用的构建和字体设置
固定路径，并导出 HYPERFRAMES_CHROME_PATH。CDP-level BeginFrame
支持的是二进制/运行时功能，因此映像构建启动它
需要启用+预热+ png返回
HeadlessExperimental.beginFrame 探测器通过。端到端烟雾
要求每个块报告有效 CaptureMode: "beginframe",这
从构建时打包中单独捕获运行时回退。没有
运行时解压步骤，没有封装上限。
部署
这个 terraform/ 模块提供一切：GCS渲染桶，
云运行服务，云工作流定义，两个最小权限
服务帐户（服务读取/写入桶；工作流调用）
服务)，以及一个逃跑请求警报。
# 1. Build + push the image (Cloud Build or local docker).
gcloud builds submit . \
--tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
# 2. Apply the module.
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform init
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
-var project_id=PROJECT \
-var region=us-central1 \
-var image=REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
起程拓殖输出 render_bucket_name， service_url， workflow_name,
region -将它们直接传递到SDK中。
使用SDK
import { renderToCloudRun, getRenderProgress } from "@hyperframes/gcp-cloud-run/sdk";
const handle = await renderToCloudRun({
projectDir: "./my-composition",
config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
bucketName: "hyperframes-render-my-project", // from terraform output
projectId: "my-project",
location: "us-central1",
workflowId: "hyperframes-render",
serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
});
// Poll until done.
let progress = await getRenderProgress({ executionName: handle.executionName });
while (progress.status === "running") {
await new Promise((r) => setTimeout(r, 5000));
progress = await getRenderProgress({ executionName: handle.executionName });
}
console.log(progress.status, progress.outputFile, progress.costs.displayCost);
deploySite 在传递时隐式调用 projectDir;叫它
预先上传一次，然后重复使用 siteHandle 在许多渲染中
（例如，个性化的模板批次）。
运行测试
bun test # unit tests over an in-memory GCS double — no network
bun run typecheck
现场端到端烟雾（构建图像→地形应用→渲染灯具）
通过工作流→psnr→比较→破坏)生命
examples/gcp-cloud-run/scripts/smoke.sh 并且需要一个GCP项目
计费启用。
前方还有什么
- 飞行中的每块进度。
getRenderProgress报告粗running进展和成功的确切数字。阅读云 工作流的步进API将在渲染时给出每个块的进度 在飞行中；作为后续跟踪。 - 云运行作业/ Firebase函数变体。 第一个版本 目标是云运行服务+工作流（最接近Lambda +的模拟） 步骤功能)。相同的处理程序在云运行作业下不变地运行； 只有业务流程触发器不同。