15.9.3 镜像命名规范与版本策略

镜像命名规范与版本策略是仓库治理的基础，决定可读性、可追溯性与自动化程度。本节给出可落地的命名规则、版本标签与 digest 的组合用法，并通过示例、命令、排错与练习说明如何在仓库内统一执行。

命名规范建议
- 统一格式：仓库域名/命名空间/镜像名:版本标签
- 命名空间与镜像名使用小写字母、数字与短横线：company/order-service
- 镜像名体现业务域与职责：company/web-frontend
- 同一业务不同运行时可用后缀：app-java8、app-java11

版本标签策略
- 基础采用语义化版本：主.次.修订 → 2.4.1
- 预发布/构建元信息：2.4.1-rc.3、2.4.1-build.20240101
- 固定版本与滚动标签并存：2.4.1 与 latest
- 紧急修复：2.4.1-hotfix.1

标签与摘要（digest）原则
- 生产使用 digest 部署，保证不可变
- 标签用于发布流程与可读性，digest 用于审计与锁定
- latest 仅限测试/开发

---

示例：命名与标签落地（含命令解释）#

前提：已安装 Docker 客户端并可访问仓库（Docker Hub/私有 Registry/Harbor）。

1）构建并打多标签

# 变量定义，避免硬编码
REGISTRY=registry.example.com
NAMESPACE=company
IMAGE=order-service
VERSION=2.4.1
BUILD=20240101

# 构建镜像（-t 为标签）
docker build -t ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION} \
             -t ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}-build.${BUILD} \
             -t ${REGISTRY}/${NAMESPACE}/${IMAGE}:latest \
             .

命令解释
- docker build -t：构建并打标签
- 多个 -t：一个镜像绑定多个标签，便于发布与回滚

2）推送镜像到仓库

# 登录仓库（如 Harbor/私有 Registry）
docker login ${REGISTRY}

# 推送所有标签
docker push ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}
docker push ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}-build.${BUILD}
docker push ${REGISTRY}/${NAMESPACE}/${IMAGE}:latest

3）获取 digest 并在部署中锁定

# 拉取并查看 digest
docker pull ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}

# 查看本地 digest
docker inspect --format='{{index .RepoDigests 0}}' \
  ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}

预期输出示例

registry.example.com/company/order-service@sha256:9f3c...e12a

使用 digest 运行

docker run -d --name order-service \
  registry.example.com/company/order-service@sha256:9f3c...e12a

命令解释
- RepoDigests 是镜像内容指纹，确保镜像不可变

---

示例：多环境标签策略#

docker tag ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION} \
  ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}-prod
docker tag ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION} \
  ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}-staging
docker push ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}-prod
docker push ${REGISTRY}/${NAMESPACE}/${IMAGE}:${VERSION}-staging

---

常见排错与修复#

1）错误：tag 格式不合法

invalid reference format

原因：包含大写字母或下划线
修复：改为小写与短横线

# 错误示例
# docker build -t Company/Order_Service:1.0 .

# 正确示例
docker build -t company/order-service:1.0 .

2）错误：推送被拒绝

denied: requested access to the resource is denied

排查
- 未登录或权限不足
- 命名空间不存在

修复

docker login registry.example.com
# 确认命名空间存在或由管理员创建

3）错误：digest 变化导致“无法复现”
原因：依赖 latest 或构建不可重复
修复
- 固定基础镜像版本
- 在 CI 中锁定依赖

# 错误：使用latest
FROM openjdk:latest

# 正确：固定版本
FROM openjdk:17-jdk-slim

---

练习#

1. 以 registry.example.com/company/api-gateway 为例，按 SemVer 打 1.2.0、1.2.0-rc.1、latest 三个标签并推送。
2. 拉取 1.2.0 并输出其 digest，使用 digest 运行容器。
3. 故意将镜像名改为 Company/API_Gateway 触发错误并修复。
4. 为 1.2.0 打 1.2.0-prod 与 1.2.0-staging 标签并推送。