---
url: /docs/deployment/ci-cd.md
---
# 自动检查与发布

## 工作流分工

| 文件 | 触发与职责 |
| --- | --- |
| `.github/workflows/ci.yml` | 主分支提交、拉取请求、合并队列和手动检查；验证并构建 |
| `.github/workflows/deploy.yml` | 被检查工作流调用；迁移与部署应用 |
| `.github/workflows/infra.yml` | 手动规划与应用基础设施变更 |
| `.github/workflows/pr-title.yml` | 检查拉取请求标题 |

实际条件以工作流源码为准。模板携带这些流程，不代表你的仓库已配置所需变量、环境权限和秘密。

## 检查与构建

检查安装锁定依赖，运行格式、静态检查、基础设施验证、类型检查、Astro 检查、测试、应用和文档构建。基础设施验证用 `init -backend=false -lockfile=readonly`，不读取远程状态，也不创建资源。

应用构建产物供部署任务复用，避免检查一个版本又部署另一个未经检查的产物。产物恢复到 `apps`，邮件包也需要存在，因为接口引用它。

## 启用应用发布

部署默认通过仓库变量 `DEPLOY_ENABLED` 控制，只有明确设为 `true` 才启用。主分支提交可发布预发布；手动运行并选择生产发布时，必须从主分支发起，配置不满足会失败。

在 GitHub 配置 `staging` 和 `production` 环境，各自保存 Cloudflare 发布凭据、数据库管理连接及所需应用秘密，字段以 `deploy.yml` 为准。使用环境级秘密与主分支规则，避免未审查分支接触发布凭据。

## 发布步骤与失败处理

任务先检查构建产物，再迁移目标数据库，然后调用 `scripts/deploy.ts` 依次更新接口、工作台和公开入口。统一脚本本身不执行迁移，手动发布需要先单独完成。

这不是原子事务。中途失败可能出现部分 Worker 已更新，数据库也可能已迁移。修复时先确认各服务实际版本和迁移记录，再补齐发布；不要无条件取消、回滚数据库或重做破坏性迁移。

数据库变更采用分阶段兼容：增加新结构、发布新代码、后续清理旧结构。发布任务不取消正在执行的发布，拉取请求检查可取消过时运行。

## 基础设施工作流

基础设施只手动执行，每个环境串行。规划任务保存计划并写入运行摘要；应用任务应用同一份已保存计划，不重新计算。无变更时跳过应用。

规划与应用使用不同 GitHub 环境：`infra-staging-plan`、`infra-production-plan`、`infra-staging-apply`、`infra-production-apply`。规划使用专用令牌，应用令牌按环境对应的 HCP 工作区隔离。生产审批规则是否可用取决于仓库可配置能力，必须到设置中核实；若不可用，保留规划，在可信机器执行明确审查过的操作。

规划不是对不可信代码的沙箱，远程配置可接触工作区凭据。两个任务都限制主分支，环境分支规则是工作流自身不能绕过的约束。基础设施凭据与应用发布凭据分别管理。

## 复制新站后检查

更新仓库变量、环境名、主分支规则、资源名称、远程状态工作区与秘密。确认实际检查结果及发布目标；一次绿色运行也可能只有检查，没有发布，要查看被跳过的任务与条件。

修改工作流时保留固定提交版本的第三方 Actions、最小权限和不持久保存的检出凭据。不要把密钥或完整环境值写入运行日志和摘要。