Docker私有镜像仓库镜像管理：删除旧镜像与覆盖问题咨询

DevOps 小满

2026-8-18

本地Docker Registry镜像删除与同名镜像推送问题解答

一、规范删除Registry中镜像的方法

默认Docker Registry禁用镜像删除功能，需先开启权限，再通过API操作标记删除，最后清理存储文件，步骤如下：

开启Registry删除权限
- 若通过容器运行Registry，启动时添加环境变量：
```
docker run -d -p 5000:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true --name registry registry:latest
```
- 或修改Registry配置文件（通常为/etc/docker/registry/config.yml），添加：
```
storage:
  delete:
    enabled: true
```
- 重启Registry容器使配置生效：docker restart registry
通过API删除指定镜像
- 先获取目标镜像的digest值（唯一标识，而非tag）：
```
curl -X GET http://<registry-ip>:5000/v2/<镜像名>/manifests/<tag>
```
  在响应头中找到Docker-Content-Digest字段，格式如sha256:xxxxxx。
- 执行删除请求：
```
curl -X DELETE http://<registry-ip>:5000/v2/<镜像名>/manifests/<digest值>
```
  注意：必须使用digest值，不能用tag——同一tag可能对应多个镜像版本。
执行垃圾回收彻底清理存储
- 删除API仅标记镜像为可删除，实际存储文件仍保留，需运行垃圾回收命令清理：
```
docker exec -it registry bin/registry garbage-collect /etc/docker/registry/config.yml
```
- 若要同时清理所有无tag关联的镜像，添加--delete-untagged参数：
```
docker exec -it registry bin/registry garbage-collect /etc/docker/registry/config.yml --delete-untagged
```
- 最后重启Registry容器，确保缓存失效。

不要手动进入容器删除存储目录文件，这会导致Registry元数据与实际存储不一致，引发拉取/推送错误，且无法通过垃圾回收修复。

结果取决于推送时使用的tag：

若推送的镜像使用已存在的tag（如my-image:latest），新镜像会覆盖该tag对应的旧镜像，但旧版本镜像仍存在于Registry中，只是tag指向了新镜像。其他Docker实例重新拉取该tag时会获取新镜像，本地已拉取的旧版本则保留缓存。
若推送的镜像使用新tag（如my-image:v1.1，之前仅存在my-image:v1.0），则不会覆盖原有镜像，两个版本会同时存在，拉取时指定对应tag即可获取目标版本。

若想让服务器仅能拉取新镜像，除删除旧版本镜像外，也可强制使用固定tag（如latest），并确保所有拉取操作都使用该tag，同时删除旧版本的digest来实现。

内容的提问来源于stack exchange，提问作者Sterling