CI/CD / 系统课时
把测试版本部署到预发布环境
把测试版本部署到预发布环境
镜像通过测试后,还需要证明它能在接近生产的环境中真正启动并提供服务。本节把已经发布的容器制品部署到预发布环境,通过 GitHub Environment 控制环境级配置,并在部署后执行健康检查,避免“部署命令成功”被误认为“应用可用”。
学习目标
- 将已经构建的镜像作为唯一部署输入传递给预发布作业
- 使用 GitHub Environment 管理预发布环境相关配置
- 在部署完成后执行可失败的健康检查并阻止错误版本继续交付
预发布阶段应该验证什么
预发布部署的重点不是再次构建,而是验证同一个制品在目标运行环境中的表现。构建作业应先确定镜像引用,部署作业只消费这个引用,避免测试完成后又生成一个内容不同的新镜像。
一次最小的预发布链路通常包含三个动作:取得已发布镜像、更新预发布服务、从服务入口执行健康检查。只有第三步通过,才能认为本次部署具备继续向生产提升的条件。

用 Environment 隔离预发布配置
可以在仓库的 staging Environment 中配置 STAGING_HOST、STAGING_USER 等 Secret,并把非敏感的服务入口配置为变量,例如 STAGING_URL。Environment 还可以承载审批或部署保护规则,使环境控制与普通仓库变量分开。
下面的工作流通过手动输入一个已经发布的镜像引用来演示完整部署。生产链路中,这个值通常由前面的制品发布作业传递或由发布记录确定,而不是让部署阶段重新执行 docker build。
name: deploy-staging
on:
workflow_dispatch:
inputs:
image:
description: "Immutable image tag or digest"
required: true
type: string
jobs:
deploy:
runs-on: ubuntu-latest
environment: staging
steps:
- name: Deploy immutable image
uses: appleboy/ssh-action@v1.2.0
env:
IMAGE: ${{ inputs.image }}
with:
host: ${{ secrets.STAGING_HOST }}
username: ${{ secrets.STAGING_USER }}
key: ${{ secrets.STAGING_SSH_KEY }}
envs: IMAGE
script: |
set -e
docker pull "$IMAGE"
docker rm -f app-staging 2>/dev/null || true
docker run -d \
--name app-staging \
--restart unless-stopped \
-p 8080:8080 \
"$IMAGE"
- name: Verify staging health
env:
STAGING_URL: ${{ vars.STAGING_URL }}
run: |
set -e
for attempt in {1..12}; do
if curl --fail --silent --show-error \
"$STAGING_URL/health" > /dev/null; then
echo "staging health check passed"
exit 0
fi
sleep 5
done
echo "staging health check failed" >&2
exit 1预期结果:部署步骤拉取输入指定的镜像并重建 app-staging 容器;健康接口在最多约 60 秒的重试窗口内返回成功状态时,作业通过。
staging health check passed这里的 8080 是示例应用端口,应与实际镜像监听端口一致。STAGING_URL 应配置为 Actions runner 能访问的预发布入口,例如反向代理或负载均衡器暴露的地址。
为什么部署后还要主动验证
docker run -d 返回成功只表示容器进程已经被创建,并不能证明应用完成初始化,更不能证明数据库、缓存或外部依赖可用。健康检查因此必须针对实际服务入口,而不是只检查容器是否处于 running 状态。
示例没有只执行一次 curl,而是短暂重试。这能容纳正常的应用启动时间,同时仍设置明确失败边界。若 12 次检查全部失败,脚本以非零状态退出,GitHub Actions 会把该步骤和作业标记为失败。
失败时按链路定位
如果 SSH 部署步骤失败,先检查 Environment 中的主机、用户和密钥是否正确,再检查目标主机是否能够访问镜像仓库以及 Docker 是否可用。私有镜像还需要目标主机具备对应仓库的拉取凭据。
如果部署步骤成功但健康检查失败,应把重点转向应用本身:确认容器是否仍在运行、端口是否一致、应用是否监听可访问地址,以及数据库等关键依赖是否准备完成。此时不应仅仅延长重试时间掩盖真实启动错误。
在预发布验证通过后,后续生产部署应继续引用这次已经验证的镜像标签或 digest,而不是重新构建。这样预发布真正承担的是“验证候选制品”的职责,生产阶段提升的也是同一个可追踪制品。