管理发布版本并回滚更改

简介

某个支持可用性接口一直运行正常，直到新版本开始返回 503。在本实验中，你将发布一次性 Worker 的两个版本，识别当前活动版本，并恢复已知正常的版本。你将把实际 HTTP 行为与 Cloudflare 的部署元数据进行对比，而不是仅凭上传成功消息判断部署是否正常。

你应该已经了解本地 Wrangler 开发、账户授权和部署。请使用自己的学习账户，在这台全新的 VM 中开始实验；不会复用之前的 VM 或 Worker。初始化过程会安装 Node.js 22.22.0 和项目本地的 Wrangler 4.131.1，并提供两个很小的模拟处理程序样例。实验不需要域名、存储服务或密钥。所有部署和清理操作都由你亲自完成。

版本是不可变的代码和配置快照。部署决定哪个版本接收流量。回滚会为现有版本创建新的部署；它不会改写本地源代码，也不会恢复绑定资源中的数据。请参阅官方版本概览。

准备已知正常的发布版本

在本步骤中，准备一个已知正常的入口文件，并在本地确认其行为。提供的样例文件可以让你专注于发布操作。正常处理程序返回 available=true；有故障的处理程序仍能通过健康检查，但会为业务路由返回 503。

cd /home/labex/project/release-recovery

cat versions/good.js

diff -u versions/good.js versions/faulty.js

由于两个文件内容不同，diff 会以状态码 1 退出，这是预期结果。只有可用性值及其 HTTP 状态码发生变化。复制正常样例文件后，配置指定的源文件就会采用该内容。

cp versions/good.js src/index.js

使用 Node 的标准 crypto API 生成唯一名称。下面未加引号的 EOF 分隔符会将 Shell 变量展开到 JSON 中；该文件不包含注释，因此标准 JSON 读取工具也可以检查它。

WORKER_NAME="labex-release-$(node -p "require('node:crypto').randomBytes(6).toString('hex')")"

cat > wrangler.jsonc <<EOF
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-07-30",
  "workers_dev": true,
  "preview_urls": false,
  "version_metadata": {"binding": "RELEASE"}
}
EOF

版本元数据绑定会提供运行时版本 ID 和标签。本地开发使用本地元数据；只有已部署的元数据才能标识云端版本。此处介绍了该绑定。

使用 & 在后台启动本地服务器，并将输出重定向到 dev.log。看到 Ready 后，再发送请求。

npx wrangler dev --ip 0.0.0.0 --port 8080 > dev.log 2>&1 &

cat dev.log

curl -i http://127.0.0.1:8080/health

curl -i http://127.0.0.1:8080/api/availability

两个路由都应返回 200；可用性值应为 true。本地版本和标签值可能是开发占位符。下一步停止开发任务之前，先完成验证。

部署并记录正常版本

在本步骤中，将已知正常的源代码部署到你的学习账户，并记录实际版本。停止本地任务；如果任务编号不同，请替换为当前编号。

jobs

kill %1

npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read

在浏览器中打开命令输出的设备链接，输入验证码，并授权目标学习账户。在登录流程中保管好凭据。读取标准账户输出；即使只列出一个账户，也要确认账户名称。

npx wrangler whoami --json

将下面的 YOUR_ACCOUNT_ID 替换为该账户的实际 ID。这个标准 Node 命令会更新项目的显式配置；账户不是通过临时环境变量选择的。

node -e 'const fs=require("node:fs");const p="wrangler.jsonc";const c=JSON.parse(fs.readFileSync(p));c.account_id="YOUR_ACCOUNT_ID";fs.writeFileSync(p,JSON.stringify(c,null,2)+"\n");'

cat wrangler.jsonc

标签是便于阅读的名称；版本 UUID 才是精确的身份标识。部署会上传一个版本，并将流量指向该版本。消息用于说明此版本的用途。

npx wrangler deploy --tag good --message "Known-good availability"

将输出中的 workers.dev URL 和 Current Version ID 复制到下面的命令中。这些只是示例占位符，不是固定的共享资源。如果此账户没有 workers.dev 子域名，请先按照「部署你的第一个 Cloudflare Worker」中的初始设置操作，然后重新部署。

APP_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"

printf '%s\n' "YOUR_GOOD_VERSION_ID" > good-version.txt

curl -i "$APP_URL/api/availability"

npx wrangler deployments status

npx wrangler versions list

预期结果为：响应状态码是 200，available=true，标签为 good，并且响应中包含已记录的版本 UUID。当前活动部署必须将 100% 的流量分配给该版本。在 Dashboard 中打开这个准确的 Worker，检查 Deployments，将 CLI 中的版本和活动部署与可见资源对应起来。如果部署后响应立即仍显示之前的状态，请等待 5 秒后重新读取，最长重试 1 分钟；不要通过修改代码来掩盖传播延迟。确认观察结果一致后，再运行验证。

观察有故障的发布版本

在本步骤中，在这个一次性 Worker 中重现一次受控的发布回归。健康检查通过并不代表业务路由正常。将入口文件替换为有故障的样例，并发布一个带有不同标签的版本。

cp versions/faulty.js src/index.js

npx wrangler deploy --tag faulty --message "Demonstrate availability regression"

保存本次部署新的 Current Version ID，不要保存正常版本的 ID。检查两个路由以及当前部署。

printf '%s\n' "YOUR_FAULTY_VERSION_ID" > faulty-version.txt

curl -i "$APP_URL/health"

curl -i "$APP_URL/api/availability"

npx wrangler deployments status

npx wrangler versions list

健康检查仍返回 200。可用性接口现在返回 503，available=false，标签为 faulty。响应中的运行时 UUID 必须与新的当前活动版本一致，并且该版本接收 100% 的流量。本步骤中的 503 是预期的故障，不是跳过验证的理由。如果传播仍在进行，请使用相同的有时间上限的响应重试方式。独立检查要求先观察到该故障，再进行恢复。

在 Compute → Workers & Pages 中打开你的准确 Worker，然后选择 Deployments。将 Active deployment 下的 ID 与 Version History 中标签为 faulty 的行进行对比。截图使用了缩短的示例 UUID；在命令中使用你完整保存的 UUID。即使有故障的版本处于活动状态，正常版本仍会保留在历史记录中。使用上面的 wrangler deployments status 确认已配置 100% 的流量分配；这张安静状态截图中的活动数值为零，不能证明业务路由正常。

回滚并同步本地源代码

在本步骤中，恢复准确的已知正常版本。在更改流量之前，读取已保存的 ID，并检查选定的正常版本。Shell 命令替换会从文件中读取 UUID；它不会上传新版本。

cat good-version.txt faulty-version.txt

npx wrangler versions view "$(cat good-version.txt)"

确认正常标签、目标 Worker 和账户，以及 UUID 都正确。回滚会将这个一次性 Worker 的 100% 流量指向该版本。消息用于记录恢复原因。确认目标无误后，再执行命令。

npx wrangler rollback "$(cat good-version.txt)" --message "Restore known-good availability"

Wrangler 询问可选消息时，按 Enter 接受 Restore known-good availability。读取显示的正常 UUID 和 100% 流量目标；出现匹配的确认提示时，只按一次 y。等待成功回滚消息出现后再继续。

npx wrangler deployments status

curl -i "$APP_URL/api/availability"

新的部署应使用原正常版本的 UUID，但不必使用原来的部署 ID。可用性接口应再次返回 200 和 true。刷新 Dashboard 的 Deployments 标签页，并对比活动 UUID。如有需要，使用相同的最长 1 分钟响应重试方式。

在本示例中，Active deployment 已恢复到 7afe5d31，它与最初 good 版本的缩短 ID 相同。Version History 中的活动标记已移动到该行，有故障的版本仍在列表中。使用你自己的 ID 对照这些关系；不要复制示例值。此页面用于识别选定的版本，而可用性响应则用于确认行为已经修复。

回滚不会改变本地源代码。请在本地恢复正常样例，这样之后进行普通部署时就不会意外重新引入已知故障。试运行会使用本地源代码生成部署包，但不会上传。

cp versions/good.js src/index.js

npx wrangler deploy --dry-run

运行验证：它会将实际运行时 UUID 和标签与当前 100% 的部署进行对比，并检查之前的有故障部署是否仍保留在历史记录中。仅在本地写入成功文件是不够的。

回滚不会撤销对数据库、队列或外部 API 的写入；绑定资源的变化也可能导致旧版本不兼容。本实验没有这些资源。在真实事故中，请先评估这些边界，再进行恢复。回滚文档介绍了相关限制以及版本保留窗口。

删除发布测试 Worker

在本步骤中，在授权仍然有效时删除一次性 Worker。删除前确认其准确名称和所属账户。

cat wrangler.jsonc

npx wrangler delete

出现匹配的名称提示时，只按一次 y。固定版本的 Wrangler 在删除 Worker 后，可能会报告旧版 KV 清理身份验证错误。不要授予更宽泛的权限范围，也不要认为出现任何错误就能证明删除成功。刷新 Dashboard 并运行验证：成功通过身份验证的资源清单中不应再出现此 Worker。保留学习账户、子域名和无关资源。

断开 VM

在确认删除成功后，本步骤会断开这台 VM。仅退出登录并不会删除已部署的 Worker。

npx wrangler logout

npx wrangler whoami --json

预期结果为 loggedIn=false；由于当前已未通过身份验证，这个结构化命令可能会以非零状态码退出。运行最终验证。浏览器登录状态和学习账户仍可用于今后的独立实验。

总结

你比较了 Worker 版本与活动部署，观察到业务路由发生回归但健康检查仍然正常，并恢复了选定的正常版本。运行时元数据将实际响应与 100% 的部署关联起来。你还恢复了本地源代码、验证了云端清理结果，并断开了 VM。