三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

14-Docker镜像版本管理：微服务镜像标签规范、版本留存与清理

发布时间：2026/8/13 0:27:33 三亩地 编程学习日记
14-Docker镜像版本管理：微服务镜像标签规范、版本留存与清理

14-Docker镜像版本管理：微服务镜像标签规范、版本留存与清理

一、为什么镜像标签需要规范？

先看一个反面教材：

registry/smart-agri/user-service:latest registry/smart-agri/user-service:latest registry/smart-agri/user-service:v1 registry/smart-agri/user-service:新版本

四个latest到底哪个是哪个？v1是一周前的还是一个月前的？新版本这种中文标签，同事看了想打人。

镜像标签不规范，导致的问题非常实际：

  • 线上跑的是哪个版本？不知道，回滚时抓瞎
  • 测试说有bug，开发说"我推了新镜像啊"——结果测试环境拉的还是缓存里的旧latest
  • 镜像仓库越来越满，阿里云/腾讯云开始按存储量收费，一看账单500G

所以，标签规范不是形式主义，是工程纪律。

二、镜像标签规范设计

2.1 标签命名规则

我们采用以下标签体系：

标签格式用途示例
{version}-{commit}-{time}完整版本标签（主要使用）1.2.0-a3f5c2e1-20260807
{branch}-{commit}分支构建标签develop-a3f5c2e1
latest最新稳定版（仅main分支）latest
{semver}正式发版标签1.2.0、1.2.1-rc.1

核心原则：每个镜像标签都能追溯到具体的commit和构建时间。

2.2 CI/CD中的标签生成

在.gitlab-ci.yml中自动生成规范标签：

package-job:stage:packagescript:# 从pom.xml提取版本号-APP_VERSION=$(mvn help:evaluate-Dexpression=project.version-q-DforceStdout)# 去掉SNAPSHOT后缀-APP_VERSION=${APP_VERSION%-SNAPSHOT}# 组合标签：版本号-commit短hash-日期-IMAGE_TAG="${APP_VERSION}-${CI_COMMIT_SHORT_SHA}-$(date +%Y%m%d%H%M)"-docker build-t $REGISTRY/$NAMESPACE/$SERVICE:$IMAGE_TAG .-docker push $REGISTRY/$NAMESPACE/$SERVICE:$IMAGE_TAG# main分支额外打latest和正式版本号标签-if["$CI_COMMIT_BRANCH" = "main"]; then docker tag $REGISTRY/$NAMESPACE/$SERVICE:$IMAGE_TAG $REGISTRY/$NAMESPACE/$SERVICE:latest; docker tag $REGISTRY/$NAMESPACE/$SERVICE:$IMAGE_TAG $REGISTRY/$NAMESPACE/$SERVICE:$APP_VERSION; docker push $REGISTRY/$NAMESPACE/$SERVICE:latest; docker push $REGISTRY/$NAMESPACE/$SERVICE:$APP_VERSION; fi

2.3 关于latest标签的使用建议

latest是Docker的默认标签，也是最容易出问题的标签。核心原则：

  • latest只指向main分支的最新稳定版，不指向开发分支
  • 生产环境绝不使用latest，必须指定具体版本号
  • 测试环境谨慎使用latest，拉取时加--pull-always避免缓存
# 生产环境部署——错误写法dockerpull registry/user-service:latest# 生产环境部署——正确写法dockerpull registry/user-service:1.2.0-a3f5c2e1-20260807

三、镜像版本留存策略

3.1 保留多少个版本？

不是所有镜像都要留。一个微服务每天构建5次，10个微服务，一年就是18000个镜像。没有清理策略，仓库迟早爆。

推荐策略：

环境保留策略说明
生产环境保留最近10个版本 + 所有正式发版正式发版永久保留，方便回滚
测试环境保留最近5个版本够排查问题就行
开发环境保留最近3个版本过了就删

3.2 自动清理脚本

以阿里云容器镜像服务（ACR）为例，通过API自动清理旧版本：

#!/usr/bin/env python3""" 镜像仓库自动清理脚本 策略：保留最近N个版本，其余删除 """importrequestsimportdatetime REGISTRY_URL="https://registry.cn-shenzhen.aliyuncs.com"NAMESPACE="alspd/smart-agri"KEEP_COUNT=10# 每个仓库保留最近10个版本defget_access_token():"""获取阿里云API访问令牌"""# 实际项目中从环境变量读取importos url=f"https://dockerauth.cn-shenzhen.aliyuncs.com/auth"params={"service":"registry.cn-shenzhen.aliyuncs.com","scope":f"repository:{NAMESPACE}/*:pull,push"}resp=requests.get(url,params=params,auth=(os.getenv("REG_USER"),os.getenv("REG_PASS")))returnresp.json()["token"]deflist_tags(repo_name,token):"""获取仓库所有标签"""url=f"{REGISTRY_URL}/v2/{NAMESPACE}/{repo_name}/tags/list"headers={"Authorization":f"Bearer{token}"}resp=requests.get(url,headers=headers)returnresp.json().get("tags",[])defget_manifest(repo_name,tag,token):"""获取镜像manifest，包含创建时间"""url=f"{REGISTRY_URL}/v2/{NAMESPACE}/{repo_name}/manifests/{tag}"headers={"Authorization":f"Bearer{token}","Accept":"application/vnd.docker.distribution.manifest.v2+json"}resp=requests.get(url,headers=headers)digest=resp.headers.get("Docker-Content-Digest","")returndigestdefdelete_tag(repo_name,tag,token):"""删除指定标签的镜像"""digest=get_manifest(repo_name,tag,token)ifnotdigest:print(f" 跳过{tag}：无法获取digest")returnurl=f"{REGISTRY_URL}/v2/{NAMESPACE}/{repo_name}/manifests/{digest}"headers={"Authorization":f"Bearer{token}"}resp=requests.delete(url,headers=headers)ifresp.status_code==202:print(f" 已删除：{tag}")else:print(f" 删除失败：{tag}({resp.status_code})")defcleanup_repo(repo_name,token):"""清理单个仓库的旧版本"""tags=list_tags(repo_name,token)ifnottags:return# 排除 latest 和正式版本号（如 1.2.0）protected_tags=[tfortintagsift=="latest"ort.startswith("v")or(t.count(".")==2and"-"notint)]cleanable=[tfortintagsiftnotinprotected_tags]# 按时间排序，保留最近KEEP_COUNT个cleanable.sort(reverse=True)# 简化：按标签名字排序to_delete=cleanable[KEEP_COUNT:]print(f"仓库{repo_name}：共{len(tags)}个标签，删除{len(to_delete)}个")fortaginto_delete:delete_tag(repo_name,tag,token)if__name__=="__main__":token=get_access_token()repos=["user-service","device-service","order-service","gateway-service"]forrepoinrepos:cleanup_repo(repo,token)

在GitLab CI中配置定时任务（Scheduled Pipeline），每周日凌晨自动执行清理：

# 每周日凌晨2点执行清理image-cleanup:stage:cleanupimage:python:3.9script:-pip install requests-python scripts/registry_cleanup.pyrules:-if:$CI_PIPELINE_SOURCE == "schedule"

四、多架构镜像构建（amd64/arm64）

4.1 为什么需要多架构？

我们的无人售货柜场景中：

  • 云端服务器：x86架构（amd64），运行微服务
  • 工控设备/边缘盒子：瑞芯微RK3588，ARM架构（arm64），运行设备端服务

同一个镜像需要在两种架构上运行，就必须构建多架构镜像（Multi-arch Image）。

4.2 使用docker buildx构建多架构镜像

# 创建并使用buildx builderdockerbuildx create--namemultiarch--usedockerbuildx inspect--bootstrap# 单次命令构建多架构镜像并推送dockerbuildx build\--platformlinux/amd64,linux/arm64\-tregistry.cn-shenzhen.aliyuncs.com/alspd/smart-agri/device-agent:1.0.0\--push\.

拉取时Docker会自动选择匹配当前架构的镜像：

# 在x86服务器上拉取 → 自动获取amd64版本# 在RK3588设备上拉取 → 自动获取arm64版本dockerpull registry.cn-shenzhen.aliyuncs.com/alspd/smart-agri/device-agent:1.0.0

4.3 CI/CD中集成多架构构建

multiarch-build:stage:packageimage:docker:20.10services:-name:docker:20.10-dindcommand:["--experimental"]variables:DOCKER_CLI_EXPERIMENTAL:enabledscript:-docker run--rm--privileged multiarch/qemu-user-static--reset-p yes-docker buildx create--use--name multiarch-docker buildx inspect--bootstrap-docker login-u $CI_REGISTRY_USER-p $CI_REGISTRY_PASSWORD $IMAGE_REGISTRY-|docker buildx build \ --platform linux/amd64,linux/arm64 \ -t $IMAGE_REGISTRY/$NAMESPACE/$CI_PROJECT_NAME:$IMAGE_TAG \ --push .rules:-if:$CI_COMMIT_BRANCH == "main"

QEMU的作用是模拟不同架构的指令集，让x86机器上也能构建arm64镜像。虽然构建速度比原生慢，但省去了准备ARM构建机的成本。

4.4 Dockerfile适配多架构

FROM openjdk:8-jre-slim # 根据目标架构安装不同的 native 库 ARG TARGETARCH RUN if [ "$TARGETARCH" = "arm64" ]; then \ apt-get update && apt-get install -y libffi-dev libssl-dev; \ fi WORKDIR /app COPY target/*.jar app.jar EXPOSE 8080 ENTRYPOINT ["java", "-jar", "app.jar"]

TARGETARCH是 buildx 自动注入的变量，值为amd64或arm64，可以用来做架构差异处理。

五、镜像仓库空间管理实践

5.1 监控仓库存储用量

定期检查镜像仓库的存储占用：

#!/bin/bash# 统计各仓库镜像数量和总大小REPOS=("user-service""device-service""order-service""gateway-service")TOTAL=0forrepoin"${REPOS[@]}";doCOUNT=$(curl-s"https://$REGISTRY/v2/$NAMESPACE/$repo/tags/list"\-H"Authorization: Bearer$TOKEN"|jq'.tags | length')echo"$repo:$COUNT个标签"TOTAL=$((TOTAL+COUNT))doneecho"总计：$TOTAL个镜像标签"

5.2 镜像层复用优化

多个微服务的Dockerfile如果基础镜像一致（都用openjdk:8-jre-slim），镜像仓库会自动复用基础层，不会重复存储。所以：

  • 统一基础镜像版本，别一个服务用openjdk:8-jre-slim，另一个用openjdk:11-jre-slim
  • 统一基础镜像来源，别一个用Docker Hub，一个用阿里云镜像——层没法复用

六、小结

镜像版本管理三件事：标签要规范、留存要有策略、清理要自动化。在微服务架构下，十几个服务的镜像如果不管好，仓库就是一颗定时炸弹。下一篇我们进入K8s部署阶段，聊聊SaaS系统的不停机灰度发布。

编程学习 学习日记 实战经验
← 返回列表