文档/ 部署/ 预览环境

预览环境

每个 Pull Request 都获得自己的实时部署和唯一 URL。在合并前在真实环境中审阅更改，PR 关闭时自动清理。

什么是预览环境

预览环境是为每个 Pull Request 自动创建的临时、功能完整的部署。它们允许你在与生产环境类似的隔离环境中测试更改，而不影响你的线上应用。

当团队成员打开 PR 时，sh0 会构建分支、将其部署到唯一 URL，并在 PR 上发表评论附带预览链接。当 PR 被合并或关闭时，预览环境自动销毁。

GitHub pull request with an sh0 bot comment showing the preview URL and deploy status

启用预览

预览环境按应用启用。导航到 应用设置 → Git → 预览环境 并开启该功能。你需要一个已连接的 Git 提供商（GitHub、GitLab 或 Bitbucket）并具有 webhook 访问权限。

Preview environment toggle in app settings

启用后，sh0 会监听来自 Git 提供商的 Pull Request 事件：

  • PR 打开：构建和部署分支
  • PR 更新（新推送）：重新构建和重新部署
  • PR 合并或关闭：销毁预览环境
Note
预览环境需要通过 OAuth 连接你的 Git 提供商，以便 sh0 可以接收 PR 事件并发布状态更新。手动 webhook 设置不支持预览环境。

自动 PR 部署

当 Pull Request 被打开时，sh0 自动执行以下操作：

  1. 克隆 PR 分支
  2. 使用与生产相同的构建流水线构建 Docker 镜像
  3. 使用 PR 代码启动新容器
  4. 分配唯一的预览 URL
  5. 在 PR 上发表评论，附带预览链接和构建状态
  6. 更新 PR 状态检查（绿色对勾或红色叉号）
Deployment in progress for a pull request with real-time build log

当新提交被推送到 PR 分支时，sh0 自动重新构建和重新部署预览。URL 保持不变，因此审阅者始终看到最新版本。

Tip
你可以配置 sh0 仅为针对特定分支（例如仅针对 main）的 PR 构建预览。这可以避免功能分支之间 PR 的不必要构建。

预览 URL

每个预览环境根据分支名称和应用名称获得唯一 URL：

Preview URL format
https://{branch-name}.{app-name}.your-domain.com

例如，如果你的应用名为 my-api，PR 分支为 feature/new-auth，预览 URL 将是：

Example preview URL
https://feature-new-auth.my-api.sh0.app

分支名称会被处理以适合 URL：斜杠替换为连字符，特殊字符被移除。每个预览 URL 的 SSL 证书通过 Caddy 自动配置。

Note
如果你为域名使用通配符 DNS 记录（例如 *.my-api.your-domain.com），预览 URL 会立即生效。否则，sh0 会为每个预览单独配置 DNS 记录。

预览环境设置

你可以自定义预览环境的行为：

  • 基础分支过滤：仅为针对特定分支的 PR 构建预览
  • 环境变量覆盖：设置预览专用变量（例如 NODE_ENV=staging）
  • 资源限制：限制预览容器的 CPU 和内存以节省资源
  • TTL（存活时间）：在指定时间后自动销毁预览，即使 PR 仍然打开
  • 最大并发预览数：限制活跃预览环境的数量以控制资源使用
Preview environment settings panel with filters, resource limits, and TTL configuration

自动清理

当 Pull Request 被合并或关闭时，sh0 自动清理预览环境：

  1. 预览容器被停止和移除
  2. Docker 镜像被删除以释放磁盘空间
  3. Caddy 路由被移除
  4. SSL 证书被清理
  5. 所有预览专用卷被删除（除非配置为保留）

你也可以在不关闭 PR 的情况下从控制台手动销毁预览环境。这在预览消耗资源且不再需要审阅时非常有用。

Warning
预览环境的数据（数据库、文件上传）默认是临时的。如果预览环境需要种子数据，请使用部署前钩子在每次部署时填充数据库。

数据库隔离

预览环境可以配置为使用隔离数据库。sh0 支持两种策略：

  • 共享数据库：预览环境连接到与预发布或生产相同的数据库（建议只读）。通过环境变量覆盖进行设置。
  • 隔离数据库：sh0 为每个预览启动专用数据库容器。数据库从快照或迁移脚本中填充，并随预览一起销毁。
Preview environment with isolated database
preview:
  enabled: true
  database_isolation: true
  seed_command: "pg_restore --dbname=$DATABASE_URL /seeds/staging.dump"
  max_concurrent: 5
  ttl: 72h
Tip
为获得最佳审阅体验，建议将预览环境与隔离数据库和来自预发布环境的种子数据相结合。这让审阅者可以真实地预览更改在生产中的表现。
Previous
Deploy Hooks
Next
Blue-Green & Rollbacks