镜像标签管理是贯穿构建、推送、拉取、部署、清理全链路的运维关键点，必须采用语义化版本（如v1.4.2）、结合git哈希或ci构建号、区分环境（如v1.4.2-prod），禁用latest用于生产，打标后校验image id，定期清理悬空与过期标签，并依赖摘要而非标签定位真实镜像。
镜像标签管理不是“打个标就完事”，而是贯穿构建、推送、拉取、部署、清理全链路的运维关键点。标签用错，轻则环境不一致，重则生产事故；标签不清，久而久之仓库堆积如山，排查成本陡增。
标签命名必须明确可追溯
标签是版本的“人眼可读接口”，不能靠猜。生产环境严禁单独依赖 latest，它不指向固定内容，每次 docker pull 可能拉到不同镜像ID。
- 推荐使用语义化版本：如
v1.4.2、v2.0.0-rc1，便于回滚与发布说明对齐 - 结合构建上下文：CI流水线中自动生成
build-1287或git-9f3a1b2，实现代码→镜像精准映射 - 区分环境用途：开发用
dev-main，测试用test-pr-45，生产只认v1.4.2-prod，避免误推误拉 - 禁用空格、下划线、大写字母和特殊符号；统一小写+连字符，例如
202610-release而非2026_10_Release
打标与推送务必验证一致性
docker tag 不复制镜像，只是添加一个新指针。常有人打完标就推，却没确认目标标签是否真指向预期镜像ID。
- 打标后立即检查：
docker images myapp，核对IMAGE ID是否与源镜像一致 - 推送前加一层校验：
docker inspect myapp:v1.4.2 --format='{{.Id}}'和源镜像比对 - 私有仓库（如 Harbor）启用“标签保留策略”或“不可变标签”，防止同名覆盖导致部署错乱
- 避免在 CI 脚本中写死
latest推送逻辑，应显式声明目标标签，例如docker push myapp:${VERSION}
本地与远程标签清理要分场景执行
不清理会累积悬空镜像、过期测试标签、重复构建产物，占用磁盘且干扰排查。
Docker Image Puller
下载
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 清理悬空镜像（无标签、无容器引用）：
docker image prune -f - 批量删旧版但保留最新：
docker images "myapp" --format "{{.Tag}} {{.ID}}" | grep -v "prod\|v[0-9]" | xargs -r -L1 sh -c 'docker rmi "$1"' _ - 按时间清理（保留最近7天）：
docker image prune -a --filter "until=168h" -f - 远程仓库清理需谨慎：Harbor 支持基于正则匹配标签自动清理，建议配置
dev-*标签7天过期、test-*14天过期，v*永久保留
排错核心：从标签快速定位真实镜像状态
遇到“明明推了却拉不到”“容器启动报错说找不到二进制”等问题，本质常是标签与实际内容脱节。
- 查本地是否真有该标签：
docker images | grep myapp，注意<none></none>表示悬空 - 确认远程是否存在：
curl -X GET "https://registry.example.com/v2/myapp/manifests/v1.4.2" -H "Accept: application/vnd.docker.distribution.manifest.v2+json" - 比对摘要（Digest）：
docker pull myapp@sha256:abc123...是唯一可信标识，标签可能被覆盖，摘要不会变 - 容器内检查实际运行镜像：
docker inspect <container_id> --format='{{.Image}}'</container_id>，输出为摘要而非标签，再反查对应标签
标签管理不复杂，但容易忽略细节。一套清晰的命名规则 + 一次打标一次验证 + 定期自动化清理 + 出问题先看摘要，基本就能覆盖 95% 的标签相关故障。
