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 仓库。示例先取得当前提交的短哈希,再组合构建号生成标签。
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}}"'
}
}
}
}预期输出
IMAGE=registry.example.com/demo/app:<ID>-<ID>
[registry.example.com/demo/app:<ID>-<ID>]两个 <ID> 分别代表实际构建号和 Git 短提交哈希,具体值随构建变化。docker build 还会输出与 Docker 版本和构建后端相关的过程日志,因此这里仅列出用于验证版本标识的稳定结果。
为什么在构建开始时确定版本
IMAGE_TAG 应在同一次 Pipeline 中只生成一次,后续测试、推送和部署阶段都复用它。如果每个阶段分别读取分支、时间或其他动态信息,同一流水线可能得到不同标签,导致测试过的镜像与最终部署的镜像不一致。

这种关系也意味着后续推送镜像时不应重新计算标签,而应直接使用 $IMAGE_REPO:$IMAGE_TAG。部署清单、发布记录和回滚记录同样应保存这个确定值。
选择稳定且可追踪的标签
构建号适合在单个 Jenkins Job 内递增,但不同 Job 可能产生相同编号;Git 短哈希能补充源码身份,但短哈希并不等同于全局唯一版本。组合二者通常足以满足内部流水线追踪,跨多个仓库或 Job 时还可以在仓库路径或版本规则中加入项目维度。
不要把分支名未经处理直接拼进 Docker 标签。Git 分支可能包含 / 等不适合作为 Docker 标签组成部分的字符。若确实需要把分支加入版本规则,应先定义统一、可测试的规范化策略。
完成构建后,应以 docker image inspect 或后续仓库查询确认目标标签确实存在,并把同一个 IMAGE_TAG 传递给推送与部署阶段。这样一次生产部署就能沿着“部署版本 → 镜像标签 → Jenkins 构建 → Git 提交”的链路反查来源,为后续发布审计和回滚提供稳定依据。