预览部署会为每个拉取请求提供一个独立的实时 URL，根据该分支的代码构建，让审阅者可以直接点开实际的更改，而不必阅读差异后再自行猜测。每次推送新提交时，预览都会随之更新，并在拉取请求关闭时自动清理。
预览部署在哪里
打开网站，点击相应站点，在站点左侧菜单中打开环境分组，选择预览。该页面标题为预览部署。
预览与预发布不同。预发布是您有意推送内容到的一个长期存在的站点副本；而预览是为每个拉取请求创建的短期环境，之后会被丢弃。许多团队会同时使用这两者。另一半内容请参见预发布环境。
先设置 Git 部署
预览并非一项独立功能。它们会重用生产站点的部署密钥和构建命令，因此在启用预览之前，站点需要先有一个可用的 Git 部署配置。
如果尚未配置 Git 部署，页面会显示先设置 Git 部署，并提供一个前往 Git 部署按钮，而不是启用表单。请先完成从 Git 部署站点中的步骤，然后再回到这里。
如果 Git 部署已连接但没有构建命令，预览页面会显示一条警告。预览将假定存储库已经构建完成，静态文件位于根目录。这对于纯 HTML 站点是正确的，但对于任何需要编译的项目则是错误的，因此如果您的项目需要构建命令，请在 Git 部署页面中进行设置。
启用预览
- 在启用预览部署卡片中，以
owner/repo的形式输入存储库。不是 URL，也不是 SSH 地址，只需填写两个部分，例如acme/marketing-site。 - 点击启用。
任何不符合 owner/name 格式的内容都会被拒绝，并提示存储库必须采用 owner/name 格式。
启用后，KPanel 会立即在一张标题为立即复制您的webhook密钥的卡片中显示 webhook 签名密钥，并提示您之后将无法再次查看该密钥。
请在离开该页面之前复制好密钥。它只会生成一次，之后无法再次获取。如果您遗失了该密钥，解决方法是重新生成，但这会使旧密钥失效，并意味着您还需要更新存储库的 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 会给您存储库的投递日志带来干扰。
费用与日常维护
预览会构建并提供真实代码，因此会占用与站点上其他任何部署相同的资源。以下两个习惯有助于控制这一点：
- 关闭您不再处理的拉取请求。拉取请求关闭后，其对应的预览会自动清理。
- 不要让预览使用生产环境的凭据。请通过机密信息标签页中的 preview 环境为预览提供测试密钥，该环境正是为了避免预览配置与生产配置混淆而设立的。
预览 URL 并非私密内容。它是一个真实的、可公开访问的主机名，拥有有效证书，任何拥有该链接的人都可以打开它。请勿使用预览来审查任何包含真实客户数据的内容，也不要用生产数据库的转储来初始化预览环境。
故障排查
打开拉取请求时没有构建任何内容。 请检查存储库中 webhook 的最近投递记录。出现 401 或 403 表示密钥不匹配，请重新生成密钥并同时更新两端。完全没有投递记录则表示该 webhook 没有订阅拉取请求事件。
预览已构建但显示目录列表或 404。 Git 部署页面上的输出目录与您的构建实际写入的位置不一致。预览会继承生产环境的该设置。
构建仅在预览环境中失败。 最常见的原因是某个依赖项或环境变量存在于生产环境中，但从未添加到预览环境中。请检查机密信息页面上的 preview 标签页。
预览 URL 不再工作。 请查看该行的状态。DESTROYED（已销毁）表示拉取请求已关闭，环境已被回收，这是预期的行为。
接下来可以阅读
- 从 Git 部署站点，前置配置要求。
- 为站点存储应用机密信息，用于按环境管理凭据。
- 预发布环境，用于持久化的预生产副本。