CI/CD / 系统课时
设计版本号规则
设计版本号规则
这一课解决“同一个制品到底来自哪次构建”的问题。最终要建立一套同时兼顾人类可读、机器唯一和可追溯性的版本规则,让发布版本、提交哈希与流水线编号各司其职,而不是把所有信息混成一个随意字符串。
学习目标
- 说明语义化版本、提交哈希和流水线编号分别解决什么问题。
- 设计既能表达发布语义、又能唯一定位构建的版本标识。
- 在脚本中稳定生成版本,并验证同一输入会得到同一结果。
先分清三种标识的职责
语义化版本回答“这是哪个对外发布版本”,例如 1.4.0;提交哈希回答“代码来自哪个 Git 状态”,例如 a1b2c3d4;流水线编号回答“这是第几次 CI 构建”,例如 812。三者关注点不同,缺一项都可能留下追踪盲区。
只使用 1.4.0,无法区分同一版本号下的多次重建;只使用提交哈希,读者看不出发布语义;只使用流水线编号,迁移 CI 系统后又难以对应源代码。因此更稳妥的做法是保留一个发布版本,再生成一个不可混淆的构建标识。
组合出可追踪的版本
对于正式发布,可以保留标准语义化版本作为主版本,并把构建信息放进 SemVer 的 build metadata,例如 1.4.0+ci.812.a1b2c3d4。它表达“发布语义仍是 1.4.0,但这份二进制来自流水线 812 和该提交”。
如果目标系统的制品名或镜像标签不接受 +,不要悄悄删除追踪信息,而是另外生成传输安全的标识,例如 1.4.0-ci.812-a1b2c3d4。这两个字符串用途不同:前者保持 SemVer 语义,后者服务于仓库路径、文件名或标签约束。
| 字段 | 作用 | 示例 |
|---|---|---|
| 发布版本 | 表达兼容性和发布语义 | 1.4.0 |
| 流水线编号 | 区分重复构建 | 812 |
| 短提交哈希 | 回到唯一源码状态 | a1b2c3d4 |
| 制品标识 | 组合后用于归档与部署 | 1.4.0-ci.812-a1b2c3d4 |
用脚本生成版本
下面的脚本把三项输入集中到一个地方生成,避免不同 Job 各自拼接导致格式漂移。真实流水线中应把 RELEASE_VERSION、CI_PIPELINE_IID 和 GIT_COMMIT 替换为平台提供的环境变量或前一步输出。
#!/usr/bin/env bash
set -euo pipefail
RELEASE_VERSION="1.4.0"
CI_PIPELINE_IID="812"
GIT_COMMIT="a1b2c3d4e5f67890"
SHORT_SHA="${GIT_COMMIT:0:8}"
SEMVER="${RELEASE_VERSION}+ci.${CI_PIPELINE_IID}.${SHORT_SHA}"
ARTIFACT_ID="${RELEASE_VERSION}-ci.${CI_PIPELINE_IID}-${SHORT_SHA}"
printf 'SEMVER=%s\n' "$SEMVER"
printf 'ARTIFACT_ID=%s\n' "$ARTIFACT_ID"预期输出
SEMVER=1.4.0+ci.812.a1b2c3d4
ARTIFACT_ID=1.4.0-ci.812-a1b2c3d4同一组输入必须得到同一标识;只要提交或流水线编号变化,制品标识就应变化。这样发布记录、部署日志和制品仓库可以通过同一个字符串互相对照。
处理分支构建和重建
不是每次 CI 都应伪装成正式语义化版本。分支或 Pull Request 构建可以使用 dev-<流水线编号>-<短哈希> 这类内部标识,把正式 1.4.0 留给真正的发布事件。这样能避免测试包被误认为稳定发布包。
还要提前定义“同一提交重新构建”是否允许生成新制品。如果依赖、基础镜像或构建环境可能变化,就应保留新的流水线编号;如果要求完全可复现,则应进一步固定依赖并记录构建环境摘要,而不是只相信 Git 哈希。
检查规则是否真的可用
一套版本规则至少要通过三个检查:看到标识能定位源码;同一发布下的不同构建不会覆盖彼此;正式发布版本与临时分支构建不会混淆。若某个制品仓库对字符、长度或标签格式有额外限制,应在生成阶段统一规范化,并让所有后续 Job 只消费已经生成好的版本变量。
最重要的是保持单一生成点和全链路复用:构建、上传、镜像标签、部署记录和回滚清单都引用同一版本输出。这样版本号才真正成为从代码到制品再到环境的追踪键。