预览与清理

目标

为一个 Pull Request、分支或临时来源创建独立的预览部署，并在不再需要时安全清理，不影响生产部署。

适用场景

团队希望每个 Pull Request 都能有一个可访问的预览地址供评审。
需要在合并前验证一次变更的真实运行效果。

前置条件

已经完成一次第一次部署，Resource 的 Source/Runtime/Network Profile 已经可用。
已经完成 GitHub 与集成中的仓库授权（如果预览来自 GitHub Pull Request）。

输入与默认值

输入	说明
`--preview`	预览类型，例如 `pull-request`
`--preview-id`	预览的稳定标识，例如 `pr-123`，同一个 PR 应该始终使用同一个 id
`--preview-domain-template`	可选，预览访问域名模板
`--require-preview-url`	可选，要求 Appaloft 必须能给出可访问的预览地址，否则让命令失败

CLI 操作步骤

在 GitHub Actions workflow（或任何 CI）中，针对 Pull Request 事件触发预览部署：

appaloft deploy . \
  --config appaloft.preview.yml \
  --preview pull-request \
  --preview-id "pr-${PR_NUMBER}" \
  --preview-domain-template "pr-${PR_NUMBER}.preview.example.com" \
  --require-preview-url

Pull Request 关闭时运行清理（推荐配一个单独的 pull_request.closed workflow）：

appaloft preview cleanup . \
  --config appaloft.preview.yml \
  --preview pull-request \
  --preview-id "pr-${PR_NUMBER}"

Web 操作步骤

Resource 详情页的 Preview 区域会列出该资源当前的 Pull Request 预览、过期时间和清理状态；可以在这里手动触发清理，不需要等待 CI workflow。

预期输出与状态

预览地址可以来自自动生成的访问地址，也可以来自自定义预览域名模板（需要通配符 DNS 已经指向目标服务器）。使用 --require-preview-url 时，如果 Appaloft 暂时无法给出可公开访问的预览路由，命令会直接失败，而不是”看起来成功但打不开”。

验证

打开命令或 Web 界面返回的预览地址，确认应用可访问。
确认预览环境使用了独立的域名/路由，没有覆盖生产环境的配置。

回滚 / 恢复

清理是幂等的：重复运行清理命令不会报错，也不会影响生产部署和普通部署历史。清理会停止预览专属的运行时、删除预览路由、解除预览来源绑定；不会触碰同一资源下的生产部署。

故障排查链接

没有预览地址：确认生成访问地址是否就绪，或者预览域名的通配符 DNS 是否已生效，再决定是否应该用 --require-preview-url 直接暴露失败。
清理没有效果：确认清理命令使用了和创建预览时完全相同的 --preview 类型和 --preview-id。
来自 Fork 的 Pull Request 被跳过：这是刻意的默认安全行为——不应该把部署凭据暴露给不可信的 Fork Pull Request，除非你已经设计了降权凭据策略。