自动部署

自动部署的工作原理

每当 GitHub 为应用所跟踪的分支发送 push 事件时，自动部署就会重新部署该 GitHub 应用。Server Compass 会在您的服务器上安装一个始终在线的网关和私有部署 worker，创建仓库 webhook，验证 GitHub 已签名的测试投递，并将该确切的 commit 排入部署队列。

设置完成后，Server Compass 桌面应用无需保持打开。服务器端运行时会随 Docker 一起重启，并持续接收 webhook、构建应用并记录部署历史。您的 SSH 端口可以保持私有；只有 webhook 主机名必须能被 GitHub 通过 HTTPS 访问到。

前提条件

开始之前，请确认您已具备：

• 一个已从 GitHub 仓库部署的 Docker 应用
• 已选择 Build on VPS 作为构建位置；webhook 自动部署 v1 不支持 GitHub Actions 构建
• 应用的 Server Compass 目录内有一个受管的 Git 检出
• 一个已关联、并有权限创建仓库 webhook 的 GitHub 账户
• 服务器上安装了 Docker Engine 和 Docker Compose
• 一个专用的公开 HTTPS 主机名，例如 deploy.example.com
• 从该主机名到 webhook 网关的路由

自动部署会跟随已部署应用上保存的分支。每次推送到该确切分支都会将 GitHub 事件中包含的 commit 排入队列；对其他分支的推送会被忽略。

设置应用

1. 在 Server Compass 中，将仓库部署为 GitHub 应用。
2. 部署时选择 Build on VPS。
3. 打开已部署的应用，前往 Deployments。
4. 找到 自动部署 卡片，点击 Set up Auto Deploy。
5. 输入一个公开的 webhook 主机名。仅使用主机名或 HTTPS origin，例如 deploy.example.com 或 https://deploy.example.com。请勿添加路径、查询字符串或自定义端口。

该主机名是 GitHub 的公开入口。仅有一个域名还不够：DNS、TLS、防火墙或 NAT 规则，以及您的代理或隧道，必须共同构成一条通往服务器上网关的完整路由。

选择 GitHub 访问服务器的方式

这三种路由选项都使用相同的已签名 webhook 和私有部署 worker。只有公开路由不同。

Server Compass 托管的 Traefik

当 Server Compass 托管的 Traefik 已经是服务器上的公开反向代理时，使用此选项。将主机名的 DNS 记录指向服务器，并确保入站端口 80 和 443 可以到达它。Server Compass 会将 webhook 网关接入现有的 traefik-public Docker 网络，并配置 HTTPS 主机路由。

对于公开的 VPS，这通常是最简单的选项。当路由器将端口 80 和 443 转发到某台 LAN 服务器，且主机名解析到路由器的公网 IP 时，它也可用于该 LAN 服务器。

现有的反向代理

当 Nginx、Caddy、Traefik、HAProxy 或其他代理已经处理该主机名时，使用此选项。点击 Check server 获取生成的 loopback 目标，然后将 webhook 主机名路由到显示的地址，例如 http://127.0.0.1:42315。

代理必须保留原始请求正文和 GitHub webhook 请求头，以便网关能够验证 HMAC 签名。请勿在此路由前放置登录中间件、Cloudflare Access 或其他交互式身份验证页面。

如果代理运行在 Docker 中，请记住代理容器内的 127.0.0.1 指的是该容器本身。请改用 host 网络、host-gateway 地址或合适的共享 Docker 网络。

稳定隧道

对于 LAN 服务器、私有 VPS、CGNAT 连接，或任何您不想开放入站端口的服务器，使用此选项。创建一个持久的具名 Cloudflare Tunnel 或等效隧道，在服务器上运行其连接器，并将公开主机名映射到 Check server 显示的 loopback 目标，例如 http://127.0.0.1:42315。

隧道必须稳定，并在重启后自动启动。临时的 Quick Tunnel 或重启后会变化的 ngrok URL 不适用，因为 GitHub 会存储该 webhook URL。如果连接器运行在 Docker 中，请为其提供 host 网络或另一条确实能到达主机上网关的路由。

检查服务器并激活

1. 点击 Check server。
2. 确认 Docker Engine、Docker Compose 和建议的网关端口通过就绪检查。
3. 如果您选择了托管的 Traefik，请确认 traefik-public 网络也通过检查。
4. 如果您选择了现有代理或稳定隧道，请将外部路由指向结果中显示的确切 loopback 端口以完成配置。
5. 点击 Activate Auto Deploy。

Server Compass 会安装网关和 worker，创建一个私有 webhook URL，将签名密钥存储在服务器上，在 GitHub 中创建 webhook，发送一次 GitHub ping，并等待一次成功的已签名投递。状态会依次经过 Installed、Routed、Hooked、Verified 和 Active。

如果设置停留在 Awaiting route，说明运行时已安装，但 GitHub 尚无法访问它。请完成或修正 DNS、TLS、防火墙/NAT、代理或隧道路由，然后点击 Continue setup。您无需重新安装该应用。

验证自动部署

首先确认公开的健康检查端点能到达 Server Compass 网关：

curl -fsS https://deploy.example.com/healthz

然后验证完整的部署流程：

1. 在 GitHub 中打开仓库，前往 Settings > Webhooks。
2. 打开 Server Compass 创建的 webhook，确认其最近一次投递返回了 2xx 响应。
3. 向跟踪的分支推送一个小的 commit。
4. 在 Server Compass 中打开应用的部署历史，确认该 webhook 任务使用了所推送的 commit。
5. 确认已部署的应用包含该更改。

作为最后的测试，请完全退出 Server Compass，向跟踪的分支再推送一个 commit，然后再次验证应用。由于网关、队列和 worker 都运行在服务器上，部署应当仍能完成。

管理已激活的 webhook

自动部署卡片提供以下操作：

• Test webhook 会发送另一次 GitHub 测试投递并刷新其状态。
• Rotate secret 会同时替换服务器和 GitHub webhook 上的签名密钥。
• Pause 会保留目标和历史，但停止自动部署；Resume 会再次启用。
• Remove 会删除 GitHub webhook 及其远程目标策略，同时保留部署历史。

若要更改所跟踪的仓库或分支，请先移除自动部署，用新的仓库或分支更新并重新部署应用，然后再次设置自动部署。

故障排查与安全

• 健康检查端点失败或返回 502/404： 请验证 DNS 和 TLS，确认代理或隧道指向当前的 loopback 端口，并确保网关容器正在运行。
• GitHub 投递不是 2xx： 请检查该 webhook 最近的投递，确认没有身份验证层拦截 GitHub，并确保代理没有更改原始正文或移除 GitHub 请求头。
• 推送不触发部署： 请确认自动部署处于 Active 而非 Paused 状态，且推送发生在确切的跟踪分支上。
• 隧道在重启前一直正常： 请将具名隧道连接器配置为系统服务或可重启的容器。请勿使用临时 URL。
• 桌面应用已关闭且部署失败： 请检查服务器是否在线，以及 Server Compass 网关和 worker 容器是否正在运行。

webhook URL 包含一个私有路由令牌，不应公开。GitHub 投递通过一个 HMAC 签名密钥进行认证，该密钥在服务器上生成并存储，且从不在 UI 中显示。您无需将 SSH、Docker socket 或私有 worker 暴露到互联网。