4. 语义化标签设计：基于语义化版本（SemVer）的标签规范
容器镜像标签是运行时发布的“身份证”。缺乏规范的标签体系会导致镜像版本混乱、回滚困难、环境部署不一致。本节将基于语义化版本（SemVer）规范，设计一套适用于容器镜像的标签体系，确保从开发到生产的全链路可追溯、可控制。
4.1 语义化版本（SemVer）核心概念
语义化版本规范（semver.org）定义了版本号的格式与递增规则：主版本号.次版本号.修订号。在容器镜像场景中，我们将其扩展为包含预发布信息和构建元数据。
| 组成部分 | 格式 | 示例 | 变更触发条件 |
|---|---|---|---|
| 主版本号 | MAJOR |
2 |
不兼容的 API 或重大架构变更 |
| 次版本号 | MINOR |
3 |
向下兼容的功能新增 |
| 修订号 | PATCH |
1 |
向下兼容的问题修复 |
| 预发布标签 | -PRERELEASE |
-rc.1, -alpha.2 |
发布前的测试、候选版本 |
| 构建元数据 | +BUILD |
+20250301, +git.abc123 |
构建标识，不参与版本比较 |
实践要点：构建元数据（
+ 之后的部分）在 SemVer 比较时被忽略，适合携带构建日期、CI 流水线 ID 或 Git 提交哈希，用于快速定位构建来源。
4.2 容器镜像标签的 SemVer 规范设计
针对容器镜像的不可变特性，我们设计以下标签规范，确保每个标签唯一指向一个不可变镜像摘要（digest）。
标准标签格式：
# 正式发布版
registry.example.com/app:1.2.3
registry.example.com/app:v1.2.3
# 预发布版
registry.example.com/app:1.2.3-rc.1
registry.example.com/app:1.2.3-beta.2
# 带构建元数据（用于追溯）
registry.example.com/app:1.2.3+20250301
registry.example.com/app:1.2.3+git.a1b2c3d标签命名规则：
- 强制使用数字版本：主版本、次版本、修订号必须为非负整数，不允许前导零（如
01.2.3非法）。 - 预发布标签优先级：
alpha<beta<rc，数字后缀越大版本越新（如1.0.0-rc.2>1.0.0-rc.1）。 - 禁止可变标签：
latest、stable等可变标签仅作为别名使用，不可用于部署声明。 - v 前缀可选但需统一：团队约定是否带
v前缀（如v1.2.3），一旦选定，全仓库统一。
4.3 标签与 Git 分支/标签的映射关系
容器镜像标签应与 Git 仓库的版本标签严格对应，实现代码与镜像的双向追溯。
| Git 标签 | 容器镜像标签 | 说明 |
|---|---|---|
v1.2.3 |
1.2.3 或 v1.2.3 |
正式发布，对应 Git Release |
v1.2.3-rc.1 |
1.2.3-rc.1 |
候选发布，用于预发布环境验证 |
v1.2.3-beta.2 |
1.2.3-beta.2 |
内测版本，用于开发/测试环境 |
v1.2.3-alpha.1 |
1.2.3-alpha.1 |
早期开发版本，功能未冻结 |
常见陷阱：不要将 Git 分支名（如
main、develop）直接作为镜像标签用于生产环境。分支是可变指针，会导致镜像标签覆盖，破坏不可变性。分支构建应使用 分支名-构建序号 格式（如 main-20250301）并定期清理。
4.4 语义化标签的版本递增策略
下图展示了基于 SemVer 的镜像标签版本递增流程，从开发到生产各阶段的标签演变路径。
4.5 多架构镜像的标签策略
当镜像支持多架构（amd64、arm64、ppc64le）时，SemVer 标签需要与架构信息协同管理。
| 策略 | 标签示例 | 适用场景 | 注意事项 |
|---|---|---|---|
| 单标签 + Manifest List | 1.2.3 |
Kubernetes 多架构集群 | 客户端需支持 OCI Manifest List |
| 架构后缀标签 | 1.2.3-amd64, 1.2.3-arm64 |
传统 Docker 环境 | 部署时需手动指定架构 |
| 混合策略 | 1.2.3 (Manifest List) + 1.2.3-amd64 (具体架构) |
兼容新旧环境 | 确保 Manifest List 与具体标签指向相同 digest |
推荐做法：优先使用 Manifest List（OCI Index）方式，一个 SemVer 标签自动对应多个架构的镜像。在 CI 流水线中，为每个架构构建独立镜像并推送架构标签，最后创建或更新 Manifest List 指向所有架构。
4.6 标签生命周期管理
基于 SemVer 的标签需要配合生命周期策略，防止镜像仓库无限膨胀。
- 保留策略：
- 所有正式发布标签（如
1.2.3）永久保留。 - 预发布标签（如
1.2.3-rc.1）保留 90 天或对应正式版发布后 30 天。 - 构建元数据标签（如
1.2.3+20250301）保留 30 天。
- 所有正式发布标签（如
- 清理规则：
- 使用 Harbor、ECR 或 GitLab Container Registry 的自动清理策略。
- 基于标签正则匹配：
^[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.[0-9]+)?(\+.*)?$。 - 保留每个主版本的最新 N 个次版本（如保留最近 3 个次版本）。
- 不可变标签强制：在镜像仓库启用“不可变标签”功能，禁止覆盖已存在的 SemVer 标签。
安全警示：如果镜像仓库不支持不可变标签，务必在 CI 流水线中增加标签冲突检测。一旦发现试图推送已存在的 SemVer 标签，立即中断构建并告警，防止意外覆盖历史版本。
4.7 标签规范检查清单
在落地 SemVer 标签规范时，建议使用以下检查清单进行合规性验证：
| 检查项 | 合规要求 | 验证方式 |
|---|---|---|
| 版本号格式 | 符合 X.Y.Z 且 X、Y、Z 为非负整数 |
正则 ^[0-9]+\.[0-9]+\.[0-9]+ |
| 预发布标签顺序 | alpha < beta < rc，数字递增 | SemVer 比较库校验 |
| 标签不可变性 | 同一标签不可指向不同 digest | 仓库不可变标签配置 + CI 冲突检测 |
| Git 标签对应 | 镜像标签与 Git tag 一致（去除 v 前缀可选） | CI 流水线自动比对 |
| 构建元数据 | 仅用于追溯，不参与版本比较 | SemVer 解析忽略 + 部分 |
| 多架构一致性 | Manifest List 内所有架构 digest 与架构标签一致 | 定期巡检 Manifest 完整性 |
通过以上规范设计，容器镜像标签从“随意字符串”转变为“结构化版本标识”，为后续的自动化发布、回滚、多环境部署奠定坚实基础。