CI/CD / 系统课时
发布可追踪的容器镜像
发布可追踪的容器镜像
生产部署不能只得到一个 latest 镜像。真正可用的制品需要能回答“由哪个提交构建、属于哪个版本、如何精确回滚”。本节用 GitHub Actions 构建并推送带提交与版本标签的镜像,让部署记录能够反查到源码。
学习目标
- 为同一个镜像生成版本标签和不可变的提交标签
- 在镜像元数据中记录源码仓库与提交信息
- 验证镜像已推送,并理解部署与回滚应使用哪种标签
为什么镜像必须可追踪
如果生产环境始终部署 latest,标签指向的内容可以变化。事故发生后,即使知道部署命令用了 latest,也无法仅凭这个标签确定当时运行的是哪个提交。
更稳妥的做法是让一次构建产生多个指向同一镜像内容的标签。例如发布 v1.8.0 时,同时保留提交 SHA 标签。版本标签便于人阅读,SHA 标签则把制品直接关联到源码提交。

构建并推送镜像
下面的工作流在推送形如 v1.8.0 的 Git 标签时运行。示例使用 GitHub Container Registry,并通过 docker/metadata-action 同时生成版本标签、提交标签和 OCI 元数据。
name: publish-image
on:
push:
tags:
- "v*"
permissions:
contents: read
packages: write
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Generate image metadata
id: meta
uses: docker/metadata-action@v5
with:
images: ghcr.io/${{ github.repository }}
tags: |
type=ref,event=tag
type=sha,prefix=sha-
labels: |
org.opencontainers.image.revision=${{ github.sha }}
org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
- name: Build and push
uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}预期结果:假设发布标签为 v1.8.0,工作流会构建一次镜像并向 GHCR 推送版本标签和 sha- 前缀的提交标签。实际 SHA 与镜像摘要会随构建变化。
ghcr.io/<OWNER>/<REPOSITORY>:v1.8.0
ghcr.io/<OWNER>/<REPOSITORY>:sha-<ID>GITHUB_TOKEN 由工作流获得,packages: write 允许作业发布包。若仓库或组织对包权限另有策略,还需要确保该工作流实际拥有对应写权限。
把版本信息写进制品
标签解决“如何引用镜像”,OCI Label 则解决“镜像自己携带什么来源信息”。示例中的 org.opencontainers.image.revision 保存完整提交 SHA,org.opencontainers.image.source 保存源码仓库地址,因此即使只拿到镜像,也能反查构建来源。
提交标签尤其适合部署记录。版本标签可能因发布流程错误而被重新指向,提交 SHA 本身对应明确源码;要求更严格时,还可以在部署清单中直接记录镜像 digest,因为 digest 标识的是具体镜像内容。
验证发布结果
推送完成后,可以拉取提交标签并检查 OCI Label。下面以已经登录 GHCR 的终端为例,<OWNER>、<REPOSITORY> 和 <ID> 替换为实际值。
docker pull ghcr.io/<OWNER>/<REPOSITORY>:sha-<ID>
docker image inspect ghcr.io/<OWNER>/<REPOSITORY>:sha-<ID> \
--format '{{ index .Config.Labels "org.opencontainers.image.revision" }}'预期输出为构建该镜像的完整提交 SHA;实际值取决于发布时的提交。
<ID>如果标签存在但 revision 与预期提交不一致,应停止部署并检查触发工作流的 Git 标签指向、checkout 的提交以及镜像标签生成规则,而不是继续用 latest 覆盖问题。
用同一个制品完成回滚
发布后不要在预发布和生产阶段重新构建源码,否则即使代码提交相同,构建环境变化也可能让两个环境拿到不同制品。更可靠的链路是 build once, deploy many:构建阶段只生成一次镜像,后续环境提升都引用已经发布的 SHA 标签或 digest。
发生故障时,回滚也不需要重新执行旧代码的构建。部署系统只需把镜像引用切回上一条已验证的 SHA 标签或 digest。这样,提交、容器制品、部署记录和回滚目标形成一条可以审计的链路。