部署与运维

GitHub 门禁驱动 Cloudflare Pages，测试与发布使用同一份产物。

默认托管方式

源码保存在 GitHub，公开网页由 Cloudflare Pages 托管。没有自有域名时使用 Pages 提供的域名，不需要添加 DNS 记录。自定义域名属于额外配置，不是运行博客的前提。

站点是静态输出，不需要数据库、常驻 Node 服务或 Cloudflare Workers 运行时函数。

设置 CI

工作流为 .github/workflows/ci.yml。当前发布机制以 GitHub Actions 作为唯一常规入口；避免同时开启 Pages Git 自动构建与直接上传，造成未经同一门禁验证的并发发布。

在仓库设置中添加：

类型	名称	内容
Actions secret	CLOUDFLARE_API_TOKEN	仅指定账户的 Cloudflare Pages 编辑权限
Actions variable	CLOUDFLARE_ACCOUNT_ID	目标账户 ID
Actions variable	DEPLOY_TARGET	cloudflare

上传 job 使用 cloudflare-pages environment。令牌不放入源码、公开手册或聊天；质量、构建、浏览器和普通 PR job 不持有部署密钥。复制项目时同时核对工作流中的 Pages 项目名。

单产物门禁

Node 22.23.3 + frozen install
  ├─ quality：lint / typecheck / unit / security / upstream
  ├─ typst：真实编译 / PDF / 跨来源发布矩阵
  └─ site：完整 build → site-commit artifact
       └─ browsers：下载并验证 artifact → 交互 / 视觉测试
全部通过
  → 下载同一 artifact → 验证摘要与 main HEAD → Cloudflare 上传

部署不重新 build。正式发布只消费 main push 对应的已验收 artifact；受信任分支的手动运行可产生隔离预览，不更新生产。PR 不使用 pull_request_target 执行不受信任 MDX。

地址与子路径

通过站点配置设置 PUBLIC_SITE_URL 和 PUBLIC_BASE_PATH。Cloudflare Pages 默认根路径，GitHub Pages 项目站点通常需要子路径。

GITHUB_PAGES=true inkstack preview

可选 GitHub Pages 目标使用 DEPLOY_TARGET=github-pages，仍在全部主 CI 门禁通过后上传同一份产物。切换平台时重新构建，不复用旧 origin/base 的 artifact。

缓存与验收

_headers 为带摘要的 /_astro/ 文件设置长期 immutable 缓存。博客索引、文档索引和 RSS 使用重验证策略；不要把 Pagefind 的固定文件名配置成一年不更新。

上线后读取真实响应头，再对照 build-report.json 与页面的 inkstack-build-id。只检查部署 job 成功不等于核验了 DNS、自定义域名或所有链接。

失败与回滚

任何门禁失败都会阻止新产物发布，现有站点保留。需要回滚时，在 Pages 中恢复上一份已知可用 deployment，再修复源码走正常 PR。

构建锁防止重叠写入；不要强行删除活动构建的锁或递归清理工作区。摘要不一致时停止上传，重新完整构建并核验，参见故障排查。平台官方说明：Cloudflare CI Direct Upload。