Docker Registry镜像失效，报"Manifest Unknown"错误求助

环境与现象 #

• 运行环境：Unraid系统，最新版Docker Registry（registry:2）
• 现象：/mnt/user/appdata/registry/目录大小不再增长，Registry无法从Docker Hub获取镜像清单，返回manifest unknown错误（404）
• 本地Unraid的Docker可正常拉取镜像，Registry无论登录与否、测试公共镜像均无法解决，清空数据重新部署问题依旧

启动命令 #

docker run
  -d
  --name='DockerRegistry'
  --net='bridge'
  -e TZ="Europe/Budapest"
  -e HOST_OS="Unraid"
  -e HOST_HOSTNAME="Pac-Man-2"
  -e HOST_CONTAINERNAME="DockerRegistry"
  -l net.unraid.docker.managed=dockerman
  -l net.unraid.docker.icon='https://github.com/juusujanar/unraid-templates/raw/master/img/DockerRegistry-logo.png'
  -p '5000:5000/tcp'
  -v '/mnt/user/appdata/registry':'/var/lib/registry':'rw' 'registry:2'

容器日志 #

192.168.47.141 - - [09/May/2023:11:37:42 +0000] "HEAD /v2/runpod/pytorch/manifests/latest HTTP/1.1" 404 96 "" "docker/23.0.5 go/go1.19.8 git-commit/94d3ad6 kernel/5.4.0-148-generic os/linux arch/amd64 UpstreamClient(Go-http-client/1.1)"
time="2023-05-09T11:37:42.687812344Z" level=error msg="response completed with error" err.code="manifest unknown" err.detail="unknown tag=latest" err.message="manifest unknown" go.version=go1.16.15 http.request.host="192.168.47.100:5000" http.request.id=6bfb3a39-0a12-459a-824a-fdeedcf4608f http.request.method=HEAD http.request.remoteaddr="192.168.47.141:51660" http.request.uri="/v2/runpod/pytorch/manifests/latest" http.request.useragent="docker/23.0.5 go/go1.19.8 git-commit/94d3ad6 kernel/5.4.0-148-generic os/linux arch/amd64 UpstreamClient(Go-http-client/1.1)" http.response.contenttype="application/json; charset=utf-8" http.response.duration=4.856565ms http.response.status=404 http.response.written=96 vars.name="runpod/pytorch" vars.reference=latest

当前配置 #

• 数据目录：/mnt/user/appdata/registry
• 端口：5000（默认）

问题原因与解决方法 #

默认的Docker Registry（registry:2）只是本地私有镜像仓库，本身没有自动从Docker Hub拉取镜像清单的功能。404错误是因为Registry内没有对应镜像，它不会主动去上游Docker Hub获取。要实现同步，需配置pull-through缓存模式。

步骤1：创建Registry配置文件 #

在Unraid的/mnt/user/appdata/registry目录下新建config.yml文件，内容如下：

version: 0.1
log:
  fields:
    service: registry
storage:
  cache:
    blobdescriptor: inmemory
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
proxy:
  remoteurl: https://registry-1.docker.io
  username: # 可选：Docker Hub用户名（拉取私有镜像时需要）
  password: # 可选：Docker Hub密码/访问令牌（拉取私有镜像时需要）

步骤2：修改启动命令，挂载配置文件 #

在原有启动命令中添加挂载配置文件的参数，修改后命令如下：

docker run
  -d
  --name='DockerRegistry'
  --net='bridge'
  -e TZ="Europe/Budapest"
  -e HOST_OS="Unraid"
  -e HOST_HOSTNAME="Pac-Man-2"
  -e HOST_CONTAINERNAME="DockerRegistry"
  -l net.unraid.docker.managed=dockerman
  -l net.unraid.docker.icon='https://github.com/juusujanar/unraid-templates/raw/master/img/DockerRegistry-logo.png'
  -p '5000:5000/tcp'
  -v '/mnt/user/appdata/registry':'/var/lib/registry':'rw'
  -v '/mnt/user/appdata/registry/config.yml':'/etc/docker/registry/config.yml':'ro'
  'registry:2'

步骤3：重启Registry容器 #

先停止并删除旧容器，再执行修改后的启动命令：

docker stop DockerRegistry && docker rm DockerRegistry
# 运行上面修改后的docker run命令

步骤4：测试拉取镜像 #

现在通过Registry拉取Docker Hub镜像，格式如下：

docker pull 192.168.47.100:5000/runpod/pytorch:latest

此时Registry会自动从Docker Hub拉取镜像清单和层，存储到指定数据目录，目录大小会开始增长。

额外说明 #

• 无需拉取私有镜像时，可删除配置文件中的username和password字段
• 确保Unraid系统能正常访问Docker Hub（已确认本地Docker可拉取，网络无问题）
• 拉取过的镜像会被缓存，再次拉取时直接读取本地数据

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