Docker Manifest创建失败：Registry版本不支持及权限问题求助

一、直接创建清单报unsupported registry version的原因及修复 #

1. Docker版本过低：docker manifest命令完整支持清单列表（Manifest List/OCI Index）需要Docker 19.03及以上版本。先检查本地Docker版本：

   docker version
   

   若版本低于19.03，直接升级Docker即可。

2. 未启用Experimental特性：早期docker manifest属于实验性功能，需手动开启：

   • 修改用户目录下的~/.docker/config.json，添加"experimental": "enabled"
   • 或重启Docker daemon时添加--experimental启动参数

3. Registry版本不兼容：Docker Registry v2.3及以上才支持Manifest List。若你的registry版本过低，需升级到v2.3+，或确认registry配置中开启了对OCI manifest的支持。

正确的远程创建清单命令：

# 创建清单列表
docker manifest create hub.domain.com/image:tag \
  hub.domain.com/image:tag-amd64 \
  hub.domain.com/image:tag-arm64

# 推送清单到registry
docker manifest push hub.domain.com/image:tag

二、本地创建清单报错/权限拒绝的修复 #

1. 拉取镜像到本地后，确保标签格式正确：
   拉取镜像时保留完整registry域名标签，避免push时默认指向Docker Hub：

   docker pull hub.domain.com/image:tag-amd64
   docker pull hub.domain.com/image:tag-arm64
   

2. 权限拒绝排查：

   • 确认登录的是目标registry，不要遗漏域名：

     docker login hub.domain.com
     

   • 检查registry权限配置：部分私有registry需要ACL允许用户推送Manifest List类型资源，确认你的账号拥有对应权限。
   • 避免使用不带registry域名的本地自定义标签创建清单，必须用包含完整registry地址的标签操作，否则push时会找不到目标registry。

本地创建并推送的正确流程：

# 创建清单列表（基于本地拉取的镜像）
docker manifest create hub.domain.com/image:tag \
  hub.domain.com/image:tag-amd64 \
  hub.domain.com/image:tag-arm64

# 推送清单
docker manifest push hub.domain.com/image:tag

三、不同Dockerfile用buildx创建多平台清单的方案 #

如果两个平台的Dockerfile不同，buildx依然支持通过指定不同Dockerfile或构建上下文生成统一清单列表：

方案1：指定不同Dockerfile构建 #

# 创建并使用buildx builder实例
docker buildx create --use

# 构建并推送多平台镜像（自动生成清单列表）
docker buildx build --platform linux/amd64,linux/arm64 \
  -f Dockerfile.amd64 --target amd64 \
  -f Dockerfile.arm64 --target arm64 \
  -t hub.domain.com/image:tag \
  --push .

注：--target可选，若Dockerfile有多阶段构建目标，可指定对应平台的构建阶段。

方案2：不同目录的构建上下文 #

若两个平台的代码/依赖完全分离在不同目录：

docker buildx build --platform linux/amd64,linux/arm64 \
  --build-context amd64=./amd64-context \
  --build-context arm64=./arm64-context \
  -f ./amd64-context/Dockerfile --target amd64 \
  -f ./arm64-context/Dockerfile --target arm64 \
  -t hub.domain.com/image:tag \
  --push .

方案3：统一Dockerfile通过参数区分平台（推荐） #

将不同平台的差异逻辑用TARGETPLATFORM变量整合到一个Dockerfile中，简化维护：

ARG TARGETPLATFORM

# 安装不同平台的依赖
RUN case "$TARGETPLATFORM" in \
    "linux/amd64") apt-get install -y amd64-package ;; \
    "linux/arm64") apt-get install -y arm64-package ;; \
    esac

# 其他通用构建步骤

然后用buildx一键构建推送：

docker buildx build --platform linux/amd64,linux/arm64 \
  -t hub.domain.com/image:tag \
  --push .

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