# 为拉取请求（Pull Requests）启用预览部署

Source: https://support.kapsulehost.com/zh-cn/site-preview

预览部署会为每个拉取请求提供一个独立的实时 URL，根据该分支的代码构建，让审阅者可以直接点开实际的更改，而不必阅读差异后再自行猜测。每次推送新提交时，预览都会随之更新，并在拉取请求关闭时自动清理。

## 预览部署在哪里

打开**网站**，点击相应站点，在站点左侧菜单中打开**环境**分组，选择**预览**。该页面标题为**预览部署**。

预览与预发布不同。预发布是您有意推送内容到的一个长期存在的站点副本；而预览是为每个拉取请求创建的短期环境，之后会被丢弃。许多团队会同时使用这两者。另一半内容请参见[预发布环境](https://support.kapsulehost.com/zh-cn/staging-environments)。

![KPanel 中某站点的预览部署页面](https://support.kapsulehost.com/help/screenshots/site-preview.0fb977c9.webp)

## 先设置 Git 部署

预览并非一项独立功能。它们会重用生产站点的部署密钥和构建命令，因此在启用预览之前，站点需要先有一个可用的 Git 部署配置。

如果尚未配置 Git 部署，页面会显示**先设置 Git 部署**，并提供一个**前往 Git 部署**按钮，而不是启用表单。请先完成[从 Git 部署站点](https://support.kapsulehost.com/zh-cn/site-git-deploy)中的步骤，然后再回到这里。

> **Note:** 如果 Git 部署已连接但没有构建命令，预览页面会显示一条警告。预览将假定存储库已经构建完成，静态文件位于根目录。这对于纯 HTML 站点是正确的，但对于任何需要编译的项目则是错误的，因此如果您的项目需要构建命令，请在 Git 部署页面中进行设置。

## 启用预览

1. 在**启用预览部署**卡片中，以 `owner/repo` 的形式输入存储库。不是 URL，也不是 SSH 地址，只需填写两个部分，例如 `acme/marketing-site`。
2. 点击**启用**。

任何不符合 `owner/name` 格式的内容都会被拒绝，并提示**存储库必须采用 owner/name 格式**。

启用后，KPanel 会立即在一张标题为**立即复制您的webhook密钥**的卡片中显示 webhook 签名密钥，并提示您之后将无法再次查看该密钥。

> **Important:** 请在离开该页面之前复制好密钥。它只会生成一次，之后无法再次获取。如果您遗失了该密钥，解决方法是重新生成，但这会使旧密钥失效，并意味着您还需要更新存储库的 webhook 设置。

## 将 Webhook 添加到您的存储库

配置完成后的卡片会显示一个 **Webhook URL**，供您粘贴到存储库设置中的 Webhooks 部分。请按以下方式配置：

- **载荷 URL**：页面上显示的 webhook URL。
- **Secret（密钥）**：您刚刚复制的值。
- **内容类型**：JSON。
- **事件**：拉取请求相关事件，以及推送事件，这样打开的拉取请求上出现新提交时就会重新构建预览。

完成以上配置后，打开拉取请求会在几分钟内构建出预览。后台任务每分钟都会检查是否有新的预览工作，因此您无需在 KPanel 中执行任何额外操作。

## 预览 URL

每个预览都会获得形如 `pr-<pull-request-number>-<site-id>.kapsulecloud.app` 的独立主机名，并由通配符证书覆盖，因此会通过 HTTPS 提供服务，您无需自行处理证书相关步骤。

打开预览最可靠的方式是点击**最近预览**中该预览所在行的“打开”按钮，它会带有为该构建分配的确切 URL。请将该链接粘贴到拉取请求中，让审阅者完全不必去寻找 KPanel。

## 查看最近预览列表

**最近预览**部分会按时间倒序列出最近的预览记录。每一行会显示拉取请求编号和标题、分支、提交，以及状态：

| 状态 | 含义 |
|---|---|
| BUILDING（构建中） | 正在克隆并构建 |
| LIVE（已上线） | 正通过其预览 URL 提供服务 |
| FAILED（失败） | 构建出错；展开日志查看原因 |
| DESTROYED（已销毁） | 已清理，通常是因为拉取请求已关闭 |

点击某一行的**切换构建日志**可在行内展开其构建输出。当预览失败时，这是首先应该查看的内容，它与您本地构建产生的输出是一致的。

如果列表为空，页面会给出提示：在该存储库上打开一个拉取请求，几分钟内就会构建出一个预览。

## 轮换 Webhook 密钥

点击配置卡片中的**重新生成密钥**。KPanel 会要求您确认，并明确说明当前密钥将立即失效，之后您需要在存储库的 webhook 设置中进行相应更新。

新密钥只会显示一次，仍然是在与之前相同的一次性卡片中显示。请复制它，然后更新存储库中的 webhook。在这两个步骤之间，传入的 webhook 请求会被拒绝，因此请连续完成这两个步骤，不要中断。

当拥有存储库管理员权限的人员离职时，或者该密钥曾被粘贴到不应出现的地方（例如共享聊天频道或工单）时，请重新生成密钥。

## 关闭预览

点击**禁用**。配置随即关闭，存储的密钥也会被清除。现有的预览将不再被重新构建。

同时也请清理存储库中的 webhook。它不会造成任何有害的影响，只是会开始失败，但一个始终返回错误的 webhook 会给您存储库的投递日志带来干扰。

## 费用与日常维护

预览会构建并提供真实代码，因此会占用与站点上其他任何部署相同的资源。以下两个习惯有助于控制这一点：

- 关闭您不再处理的拉取请求。拉取请求关闭后，其对应的预览会自动清理。
- 不要让预览使用生产环境的凭据。请通过[机密信息](https://support.kapsulehost.com/zh-cn/site-secrets)标签页中的 **preview** 环境为预览提供测试密钥，该环境正是为了避免预览配置与生产配置混淆而设立的。

> **Warning:** 预览 URL 并非私密内容。它是一个真实的、可公开访问的主机名，拥有有效证书，任何拥有该链接的人都可以打开它。请勿使用预览来审查任何包含真实客户数据的内容，也不要用生产数据库的转储来初始化预览环境。

## 故障排查

**打开拉取请求时没有构建任何内容。** 请检查存储库中 webhook 的最近投递记录。出现 401 或 403 表示密钥不匹配，请重新生成密钥并同时更新两端。完全没有投递记录则表示该 webhook 没有订阅拉取请求事件。

**预览已构建但显示目录列表或 404。** Git 部署页面上的输出目录与您的构建实际写入的位置不一致。预览会继承生产环境的该设置。

**构建仅在预览环境中失败。** 最常见的原因是某个依赖项或环境变量存在于生产环境中，但从未添加到预览环境中。请检查机密信息页面上的 **preview** 标签页。

**预览 URL 不再工作。** 请查看该行的状态。**DESTROYED（已销毁）**表示拉取请求已关闭，环境已被回收，这是预期的行为。

## 接下来可以阅读

- [从 Git 部署站点](https://support.kapsulehost.com/zh-cn/site-git-deploy)，前置配置要求。
- [为站点存储应用机密信息](https://support.kapsulehost.com/zh-cn/site-secrets)，用于按环境管理凭据。
- [预发布环境](https://support.kapsulehost.com/zh-cn/staging-environments)，用于持久化的预生产副本。