mcpField
C
cloudflare-workers-cd-rollback

cloudflare-workers-cd-rollback

github.com/mizchi云与 DevOps41646 次安装1 周前更新
代码仓库

关于 cloudflare-workers-cd-rollback

此技能提供 Cloudflare Workers 的 GitHub Actions 部署工作流模板，面向配置 Cloudflare CI/CD 的项目。它记录既有流量版本，并在冒烟测试失败时尝试恢复部署分配。

主要功能

  1. 01部署至 staging 和 production
  2. 02部署前保存流量版本分配
  3. 03运行 D1 迁移与构建
  4. 04部署后执行冒烟测试
  5. 05失败时恢复先前流量分配

适用场景

  1. 01为 Workers 项目配置 GitHub Actions 发布
  2. 02冒烟测试失败后恢复先前版本
  3. 03在发布前检查构建包与 dry-run

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mizchi/skills --skill cloudflare-workers-cd-rollback

安装后在 Claude Code 中输入/cloudflare-workers-cd-rollback确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
assets/scripts/
deployment-state.test.ts
deployment-state.ts
smoke.ts
assets/workflows/
cd-production.yml
cd-staging.yml
deploy.yml
references/
cd-traps.md

详细介绍

Cloudflare Workers CD 与自动回滚

使用这三个工作流模板，搭配 cf、Node.js 24 和 pnpm。~/ghq/github.com/mizchi/cf-example 中的 cf-example 展示了当前的 Vite/配置/类型生成集成；此技能会添加部署状态捕获和回滚功能。

push main/release → staging/production caller → deploy.yml
  → capture previous traffic versions as JSON
  → cf d1 migrations apply DATABASE_ID --dir db/migrations
  → MoonBit build + FFI preparation
  → cf workers types + cf build --mode <target>
  → bundle check + cf deploy --prebuilt --mode <target> --dry-run
  → cf deploy --prebuilt --mode <target>
  → smoke
  → on failure: cf workers deployments create with the saved traffic array
  → report + fail the workflow when smoke failed

复制和配置

将 assets/workflows/{deploy,cd-staging,cd-production}.yml 复制到 .github/workflows/，并将辅助脚本复制到 scripts/。Bundle 检查器来自 MoonBit 技能；从此技能复制 deployment-state.ts 和 smoke.ts。

CI 运行前，项目必须已有 cloudflare.config.ts。使用 cf migrate 迁移现有的 Wrangler 项目，并在本地解决后续问题，然后提交类型化配置和锁文件。CI 不得依赖自动设置。

请配置：

  • DevDependencies：cf、@cloudflare/vite-plugin@beta、Vite、TypeScript 和 @dotenvx/dotenvx。
  • build:core package 脚本：moon build --target js --release && node scripts/prepare-worker.ts。对于纯 TypeScript 项目，请移除 MoonBit 安装/构建步骤，直接使用 cf build。
  • smoke package 脚本：node scripts/smoke.ts，并根据项目设置路径/状态预期。
  • GitHub 变量 D1_DATABASE_ID_PRODUCTION、D1_DATABASE_ID_STAGING、WORKERS_SUBDOMAIN；可选的 WORKER_NAME_PRODUCTION 和 WORKER_NAME_STAGING 默认分别为 cf-mbt-app 和 cf-mbt-app-staging。使这些名称和 ID 与相应配置模式保持一致。
  • 加密的 .env.cloudflare，其中包含 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID；GitHub 密钥 DOTENV_PRIVATE_KEY_CLOUDFLARE 用于解密该文件。访问冒烟测试所需的凭据也可以来自此文件。

如果项目没有 D1 或有多个数据库，请调整 D1 步骤。cf 需要 ID，默认使用远程模式，--dir 用于选择迁移目录。使用兼容的架构迁移：回滚 Worker 不会撤销数据库变更。

构建和预构建部署必须使用相同的模式。如果启用 bindings.secret()，请为 dry-run 检查提供模拟值，并在发布时通过 --secrets-file 提供相应的已忽略/解密文件；仅有 CLI 凭据不会自动成为 Worker 绑定。

回滚约定

cf API 的输出为 stdout 上的 JSON；进度/错误信息写入 stderr。部署列表会将最新的活动部署放在首位，这与旧版 Wrangler 文本输出的顺序不同。deployment-state.ts 会验证响应，并保存完整的 {version_id, percentage}[] 分配信息，包括渐进式流量拆分。遇到格式错误的数据时会拒绝处理，而不会选择较旧的部署。

成功返回的空列表或特定的 Worker 不存在错误 10007 表示这是首次部署：保存 []，跳过回滚并报告冒烟测试失败。认证、权限、网络和解析失败会在部署前中止。不要将所有列表查询失败都视为首次部署。

冒烟测试失败时，使用 cf workers deployments create --worker <name> --strategy percentage --versions @file 恢复已保存的分配信息。不要自动添加 --force 来绕过因密钥变更而受阻的回滚。首次部署无法恢复到更早版本。请按目标模式串行执行部署；避免其他部署流水线与此工作流同时部署。

消息通过环境变量传入 shell 步骤。切勿将提交正文或任意的 dispatch 输入直接插入 shell 源代码。封装脚本会通过 dotenvx 密钥检查部署条件，并监视 cloudflare.config.ts 和 vite.config.ts 的变更。

验证

部署状态测试涵盖了最新部署优先、渐进式流量、首次部署以及格式错误/API 错误数据。启用复制的工作流前，请验证 YAML 并运行 dry run。来源和限制：cd-traps.md、cf API 指南。

评论

支持 Markdown