基于AWS ECR搭建Docker拉取缓存Registry遇‘manifest unknown’问题求助

背景与需求 #

• 我们在AWS ECR托管私有Docker镜像仓库，开发团队分布在全球多站点，需搭建本地Docker拉取缓存，让同一站点工程师共享缓存，减少云端拉取耗时。
• 现有两台机器：
  • Machine A：部署本地Registry
  • Machine B：客户端拉取镜像

期望流程 #

1. Machine B向Machine A（本地Registry）发起Docker镜像拉取请求
2. Machine A检查本地Registry与远程AWS ECR私有仓库中目标镜像的差异
3. 若镜像存在差异则从远程仓库拉取，否则直接从本地Registry提供

已尝试的配置 #

Machine A（本地Registry）配置 #

修改/etc/registry/config.yml，添加代理配置：

proxy:
    remoteurl: https://<your-ecr-registry>.dkr.ecr.<region>.amazonaws.com
    username: <username>
    password: <your-ecr-authorization-token>

Machine B（客户端）配置 #

修改/etc/docker/daemon.json，添加镜像仓库镜像配置：

{
    "registry-mirror": ["https://<my-docker-mirror-host>"]
}

遇到的问题 #

配置完成后，Machine B拉取镜像时出现manifest unknown error，说明本地Registry无法从AWS ECR拉取目标镜像。

排查思路与解决方案参考 #

核心问题分析 #

AWS ECR的授权Token具有时效性（默认12小时），若配置中使用过期Token，会导致本地Registry身份验证失败，进而无法拉取镜像触发manifest错误。此外，ECR地址格式、权限配置也可能是诱因。

具体排查步骤 #

1. 验证ECR授权Token有效性

   • 重新生成有效Token：执行aws ecr get-login-password --region <region>获取最新Token，替换Machine A配置中的password字段，随后重启本地Registry服务。
   • 注意：ECR的username固定为AWS，请勿填写其他值，此为常见配置错误点。

2. 检查本地Registry的权限与网络

   • 验证Machine A能否正常访问AWS ECR：在Machine A上执行curl -u AWS:<token> https://<ecr-registry-url>/v2/<repo-name>/manifests/<tag>，确认是否能获取镜像manifest。
   • 查看本地Registry日志（通常在/var/log/registry/或通过docker logs <registry-container>），排查是否存在身份验证失败、网络连接超时等错误。

3. 修正客户端配置逻辑

   • 使用registry-mirror时需注意镜像拉取路径映射：拉取xxx.ecr.region.amazonaws.com/my-image:tag这类格式的镜像时，本地Registry需正确代理到对应ECR仓库，路径不匹配会导致代理找不到镜像。
   • 替代方案：在Machine B的/etc/hosts中将ECR的Registry域名指向Machine A的IP，客户端拉取ECR镜像时会直接请求本地Registry，规避registry-mirror的路径匹配问题。

4. 社区解决方案参考

针对ECR的代理配置，需注意以下几点：

1. ECR授权Token必须实时生成，不能使用过期Token，建议通过脚本定期更新本地Registry配置并重启服务。
2. 本地Registry的proxy配置中，remoteurl必须是完整的ECR Registry域名，不能包含仓库路径。
3. 确保本地Registry运行用户具备配置文件读取权限，且配置文件YAML格式正确（如缩进、冒号后需加空格）。

内容的提问来源于stack exchange，提问作者fti-sshendre