镜像标签命名规范：从 :latest 到语义化版本

概述

Docker 镜像标签（Tag）是镜像版本的标识符。一个合理的标签命名规范能让你清楚地知道：这个镜像是什么、什么时候构建的、基于什么代码、适用于什么环境。反之，混乱的标签（全是 :latest 或日期乱写）会导致部署混乱、回滚困难、环境混淆。

默认标签的风险

# ❌ 最常见的错误：所有镜像都用 :latest
docker build -t myapp:latest .
docker build -t myapp:latest .
docker build -t myapp:latest .

# 这三栋镜像完全不同，但名字一样
# 你根本不知道容器里跑了哪个版本！

flowchart LR
    subgraph "混乱的标签"
        A["myapp:latest\n（今早构建）"] --> D["都不知道\n是什么版本"]
        B["myapp:latest\n（昨天构建）"] --> D
        C["myapp:latest\n（上周构建）"] --> D
    end

    subgraph "清晰的标签"
        E["myapp:1.2.0"] --> I["v1.2.0 发布版本"]
        F["myapp:1.2.1-rc.1"] --> J["1.2.1 候选版"]
        G["myapp:abcdef1"] --> K["commit abcdef1"]
    end

命名规范的核心要素

一个好的标签应该包含哪些信息：

信息维度	常见表示	例子
语义版本号	`X.Y.Z`	`1.2.3`
Git commit	`git` 短哈希	`a1b2c3d`
构建时间	`YYYYMMDD` 或 Unix 时间戳	`20250101`
构建编号	CI/CD 的流水线编号	`build.1234`
环境标识	`prod`/`staging`/`dev`	`myapp:prod`
架构标识	`amd64`/`arm64`	`myapp:1.2.0-arm64`

主流标签策略

策略 1：语义化版本（SemVer）

最常见的方案：

# 格式：主版本.次版本.补丁
docker tag myapp:1.0.0 myrepo/myapp:1.0.0
docker tag myapp:1.0.1 myrepo/myapp:1.0.1
docker tag myapp:1.1.0 myrepo/myapp:1.1.0
docker tag myapp:2.0.0 myrepo/myapp:2.0.0

# 额外别名
docker tag myapp:1.0.0 myrepo/myapp:1.0
docker tag myapp:1.0.0 myrepo/myapp:1
docker tag myapp:2.0.0 myrepo/myapp:2

# docker-compose.yml
version: '3.8'
services:
  api:
    image: myrepo/myapp:1.2.0  # 锁定准确版本

策略 2：Git Commit 哈希

# 适合开发环境，每个 commit 对应一个镜像
export COMMIT_SHA=$(git rev-parse --short HEAD)
docker build -t myapp:${COMMIT_SHA} .
docker push myapp:${COMMIT_SHA}

策略 3：组合标签

# 版本 + 构建信息
docker tag myapp:1.2.0 myrepo/myapp:1.2.0-b20250101

# 版本 + 架构
docker tag myapp:1.2.0 myrepo/myapp:1.2.0-amd64
docker tag myapp:1.2.0 myrepo/myapp:1.2.0-arm64

# 版本 + 环境
docker tag myapp:1.2.0 myrepo/myapp:1.2.0-prod
docker tag myapp:1.2.0-rc.1 myrepo/myapp:1.2.0-staging

策略 4：CI/CD 自动标签

# GitHub Actions 示例
name: Build and Push

on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set Docker tags
        id: tags
        run: |
          # 如果是 Tag 推送
          if [[ $GITHUB_REF == refs/tags/v* ]]; then
            VERSION=${GITHUB_REF#refs/tags/v}
            echo "tags=$VERSION,latest" >> $GITHUB_OUTPUT
          else
            # 分支推送
            SHA=${GITHUB_SHA::7}
            echo "tags=$SHA,main" >> $GITHUB_OUTPUT
          fi

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          tags: ${{ steps.tags.outputs.tags }}
          push: true

标签的多重索引

# 一个镜像可以有多个标签
docker tag myapp:1.2.0 myrepo/myapp:1.2.0
docker tag myapp:1.2.0 myrepo/myapp:1.2        # 次版本
docker tag myapp:1.2.0 myrepo/myapp:1           # 主版本
docker tag myapp:1.2.0 myrepo/myapp:latest      # 最新版

# 推送一次，三个标签
docker push myrepo/myapp --all-tags

flowchart LR
    subgraph "镜像 ID: sha256:abc123"
        A["Image Digest\n不可变"]
    end

    subgraph "可变引用（标签）"
        B["myapp:1.2.0"]
        C["myapp:1.2"]
        D["myapp:1"]
        E["myapp:latest"]
    end

    A --- B
    A --- C
    A --- D
    A --- E

    F["新的镜像 ID\nsha256:def456"] --> G["myapp:1.3.0"]
    G --> C2["myapp:1.3"]
    G --> D2["myapp:1"]
    G --> E2["myapp:latest\n（移动了！）"]

生产环境的最佳实践

1. 永远不要在生产用 :latest

# ❌ 生产环境
docker run myrepo/myapp:latest

# ✅ 生产环境
docker run myrepo/myapp:1.2.0
docker run myrepo/myapp@sha256:abc123def456...  # 最保险

2. 使用 Digest 保证不可变性

# 查看 digest
docker images --digests myrepo/myapp
# REPOSITORY    TAG       DIGEST                                    
# myrepo/myapp  1.2.0     sha256:abc123...

# 通过 digest 运行（无法被篡改）
docker run myrepo/myapp@sha256:abc123...

3. 区分官方镜像和自定义镜像

# 官方镜像直接引用
FROM node:18-alpine

# 自定义加前缀
FROM myregistry.example.com/myteam/myapp:1.2.0

# 或公司级前缀
FROM docker.company.com/base-images/java:17-jre

标签清理策略

# 查看所有标签
docker image ls --format "table {{.Repository}}\t{{.Tag}}"

# 清理旧的 latest 标签
docker image rm myapp:latest

# 保留最近 N 个版本
# 在 CI 中自动清理

常见反模式

反模式	问题	正确做法
只用 `:latest`	无法区分版本	语义版本 + 别名
混杂大小写	可能造成拉取失败	全小写
版本号不含分隔符	`myapp123` 无法解析	`myapp:1.2.3`
过长标签	超过 128 字符会报错	控制在 50 字符内
敏感信息做标签	`myapp:password123`	永远不要
标签对应不同镜像	同标签不同镜像导致混乱	不变的是下载 digest

总结

不要依赖 :latest——它是可变引用，今天和昨天的可能不同
使用语义化版本 主版本.次版本.补丁 作为主标签
CI/CD 自动生成标签——git commit、构建编号、时间戳
多重标签——一个镜像可以同时打多个标签
生产环境用 Digest——保证不可变部署
清理旧标签——避免镜像仓库爆炸
全小写、短横线分隔——符合 Docker 官方推荐

镜像标签命名规范：从 :latest 到语义化版本

镜像标签命名规范：从 :latest 到语义化版本

概述

默认标签的风险

命名规范的核心要素

主流标签策略

策略 1：语义化版本（SemVer）

策略 2：Git Commit 哈希

策略 3：组合标签

策略 4：CI/CD 自动标签

标签的多重索引

生产环境的最佳实践

1. 永远不要在生产用 :latest

2. 使用 Digest 保证不可变性

3. 区分官方镜像和自定义镜像

标签清理策略

常见反模式

总结

推荐标签方案

请登录后发表评论