只发布文档前端：Cloudflare 构建、路由与验收

Cloudflare 官方 Workers Static Assets 可在没有应用 Worker 脚本的情况下发布静态目录。这里选它承载 VitePress；Cloudflare Pages 也可以使用相同 dist 做静态托管，但下面只需执行一条 Workers 路径。后端集群、GPU、权限工具、模型 API 密钥都不属于静态站。

npm ci
npm run docs:build
npm run docs:preview
npx wrangler deploy --dry-run
# 获得账号授权后，在自己的终端登录或给 CI 配置最小权限 token
npx wrangler login
npx wrangler deploy

Wrangler 配置里的 assets.directory 是唯一发布目录，不要上传仓库根目录。构建会生成独立章节 HTML、搜索索引和 404.html，直接访问 /runtime 由静态 HTML 匹配；不存在的路径返回 404，而非兜底首页的 SPA 200。哈希资源按 _headers 设置 immutable 缓存；HTML 不应永久缓存。上线时用 curl -I 分别核验首页、章节、随机不存在的路径以及带 hash 的资源，再在手机上直接打开深链接。

当前工作区上级仓库与本书无关。将本目录作为独立仓库根目录后 GitHub Actions 才能发现 .github/workflows/handbook.yml。CI 的环境名 production，Secrets 为 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID；只在已授权的仓库手动 dispatch 或打开 CLOUDFLARE_AUTODEPLOY 才发布，PR 只做构建和预检。页面的源码链接指向同一版本的静态源码副本。不要替换现有上级仓库的 origin。

自定义域名需要可管理的 zone；在 Worker 的 Settings → Domains & Routes 添加 Custom Domain，让 Cloudflare 建 DNS 与证书，等 HTTPS 生效后验证重定向和证书链。仓库没有预填域名或秘密。线上域名、证书、缓存和 Access 策略只能在授权后检验。

每次发布至少验证两种内容

配置 wrangler.jsonc 将 assets.directory 指向 handbook/.vitepress/dist。npm run docs:build 的 prebuild 打包白名单源码，与页面引用使用相同文件。构建失败或本地链接失败则不上传。云端健康不能只检查首页 HTTP 200：检查一篇深层路由的章节文字，并逐字节比较下载包。

npm ci
npm run docs:build
python3 scripts/check-static.py
npx --no-install wrangler deploy --dry-run --config wrangler.jsonc
# 已登录并选择正确账户后：
npx --no-install wrangler deploy --config wrangler.jsonc
SITE=https://cloudlab-engineering-handbook.ggb55812.workers.dev
curl -fsSL "$SITE/kube/kubebuilder" | grep -q '从空目录开发'
curl -fsSL "$SITE/labs/cloudlab-mac.zip" -o /tmp/cloudlab-published.zip
cmp /tmp/cloudlab-published.zip handbook/public/labs/cloudlab-mac.zip
rm /tmp/cloudlab-published.zip

生产域名与 TLS 由账号中对应 zone 管理；本站继续使用既有 workers.dev 域，没有替用户新增 DNS。私有 API、数据库、集群凭证均不属于静态站；后端部署在 Linux/K8s，需要独立认证与可观测性。