CI/CD / 系统课时

发布可追踪的容器镜像

发布可追踪的容器镜像

生产部署不能只得到一个 latest 镜像。真正可用的制品需要能回答“由哪个提交构建、属于哪个版本、如何精确回滚”。本节用 GitHub Actions 构建并推送带提交与版本标签的镜像,让部署记录能够反查到源码。

学习目标

  • 为同一个镜像生成版本标签和不可变的提交标签
  • 在镜像元数据中记录源码仓库与提交信息
  • 验证镜像已推送,并理解部署与回滚应使用哪种标签

为什么镜像必须可追踪

如果生产环境始终部署 latest,标签指向的内容可以变化。事故发生后,即使知道部署命令用了 latest,也无法仅凭这个标签确定当时运行的是哪个提交。

更稳妥的做法是让一次构建产生多个指向同一镜像内容的标签。例如发布 v1.8.0 时,同时保留提交 SHA 标签。版本标签便于人阅读,SHA 标签则把制品直接关联到源码提交。

从源码提交到可追踪镜像再到部署与回滚的关系

构建并推送镜像

下面的工作流在推送形如 v1.8.0 的 Git 标签时运行。示例使用 GitHub Container Registry,并通过 docker/metadata-action 同时生成版本标签、提交标签和 OCI 元数据。

yaml
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 与镜像摘要会随构建变化。

text
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> 替换为实际值。

bash
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;实际值取决于发布时的提交。

text
<ID>

如果标签存在但 revision 与预期提交不一致,应停止部署并检查触发工作流的 Git 标签指向、checkout 的提交以及镜像标签生成规则,而不是继续用 latest 覆盖问题。

用同一个制品完成回滚

发布后不要在预发布和生产阶段重新构建源码,否则即使代码提交相同,构建环境变化也可能让两个环境拿到不同制品。更可靠的链路是 build once, deploy many:构建阶段只生成一次镜像,后续环境提升都引用已经发布的 SHA 标签或 digest。

发生故障时,回滚也不需要重新执行旧代码的构建。部署系统只需把镜像引用切回上一条已验证的 SHA 标签或 digest。这样,提交、容器制品、部署记录和回滚目标形成一条可以审计的链路。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

发布可追踪的容器镜像

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通