CI/CD / 系统课时

构建带版本标识的 Docker 镜像

构建带版本标识的 Docker 镜像

持续交付中的镜像标签必须能回答“它来自哪次构建、对应哪个提交”。本篇使用 Jenkins 构建号与 Git 提交短哈希生成可追踪的 Docker 标签,并完成构建与检查,避免把无法定位来源的 latest 当作唯一发布标识。

学习目标

  • 用 Jenkins 构建信息和 Git 提交生成镜像标签
  • 在 Pipeline 中构建带可追踪版本的 Docker 镜像
  • 验证镜像标签并理解标签设计的边界

版本标识要解决什么问题

只构建 registry.example.com/demo/app:latest 时,标签会被后续构建重复覆盖。看到运行中的 latest,无法仅凭标签判断它对应哪个 Git 提交,也不利于指定旧版本回滚。

一个实用方案是组合 Jenkins 的 BUILD_NUMBER 与 Git 提交短哈希,例如 128-a1b2c3d。构建号方便从 Jenkins 反查任务,提交哈希方便从镜像反查源码,两者承担不同的追踪职责。

在 Pipeline 中生成标签并构建

下面的 Jenkinsfile 假设 Agent 已安装 Git 和 Docker,并且 Jenkins 工作区来自 Git 仓库。示例先取得当前提交的短哈希,再组合构建号生成标签。

groovy
pipeline {
    agent { label 'linux-docker' }

    environment {
        IMAGE_REPO = 'registry.example.com/demo/app'
    }

    stages {
        stage('Prepare Version') {
            steps {
                script {
                    def gitSha = sh(
                        script: 'git rev-parse --short=8 HEAD',
                        returnStdout: true
                    ).trim()
                    env.IMAGE_TAG = "${env.BUILD_NUMBER}-${gitSha}"
                    echo "IMAGE=${env.IMAGE_REPO}:${env.IMAGE_TAG}"
                }
            }
        }

        stage('Build Image') {
            steps {
                sh 'docker build --tag "$IMAGE_REPO:$IMAGE_TAG" .'
            }
        }

        stage('Verify Image') {
            steps {
                sh 'docker image inspect "$IMAGE_REPO:$IMAGE_TAG" --format "{{.RepoTags}}"'
            }
        }
    }
}

预期输出

text
IMAGE=registry.example.com/demo/app:<ID>-<ID>
[registry.example.com/demo/app:<ID>-<ID>]

两个 <ID> 分别代表实际构建号和 Git 短提交哈希,具体值随构建变化。docker build 还会输出与 Docker 版本和构建后端相关的过程日志,因此这里仅列出用于验证版本标识的稳定结果。

为什么在构建开始时确定版本

IMAGE_TAG 应在同一次 Pipeline 中只生成一次,后续测试、推送和部署阶段都复用它。如果每个阶段分别读取分支、时间或其他动态信息,同一流水线可能得到不同标签,导致测试过的镜像与最终部署的镜像不一致。

Jenkins 构建信息到镜像版本的追踪关系

这种关系也意味着后续推送镜像时不应重新计算标签,而应直接使用 $IMAGE_REPO:$IMAGE_TAG。部署清单、发布记录和回滚记录同样应保存这个确定值。

选择稳定且可追踪的标签

构建号适合在单个 Jenkins Job 内递增,但不同 Job 可能产生相同编号;Git 短哈希能补充源码身份,但短哈希并不等同于全局唯一版本。组合二者通常足以满足内部流水线追踪,跨多个仓库或 Job 时还可以在仓库路径或版本规则中加入项目维度。

不要把分支名未经处理直接拼进 Docker 标签。Git 分支可能包含 / 等不适合作为 Docker 标签组成部分的字符。若确实需要把分支加入版本规则,应先定义统一、可测试的规范化策略。

完成构建后,应以 docker image inspect 或后续仓库查询确认目标标签确实存在,并把同一个 IMAGE_TAG 传递给推送与部署阶段。这样一次生产部署就能沿着“部署版本 → 镜像标签 → Jenkins 构建 → Git 提交”的链路反查来源,为后续发布审计和回滚提供稳定依据。

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

目录与阅读设置

阅读设置

17

记录一个想法

构建带版本标识的 Docker 镜像

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

登录哪都通