# 镜像加速器
#### 设置镜像加速器后还是拉取失败，可能原因：
1. [国内网络访问 DockerHub 镜像仓库异常通知](https://support.huaweicloud.com/bulletin-swr/swr_bulletin_0001.html)。如果您无法解决拉取失败的问题请[提交工单](https://console.huaweicloud.com/ticket/#/ticketindex/createIndex)。
2. 开源镜像源DockerHub中不存在您要拉取的镜像。
3. 容器引擎所在的虚拟机节点配置异常，请[提交工单](https://console.huaweicloud.com/ticket/#/ticketindex/createIndex)进行处理。
 
#### 配置的镜像加速器地址不正确，导致无法拉取开源镜像
1. 排查 Docker 客户端配置的镜像加速器是否正确，通过执行以下命令确认是否为本局点 SWR 镜像加速器地址：
   ```
   docker info | grep -A 5 "Registry Mirrors"
   ```
   
2. 确认输出的镜像加速器地址与当前区域 SWR 的镜像加速器地址一致。如不一致，请修改 /etc/docker/daemon.json 中的 registry-mirrors 配置并重启 Docker 服务。
 
#### 执行 docker search 报错
原因：镜像加速器不支持 docker search 检索功能。
解决方式
明确镜像版本后，直接执行以下命令拉取：
```
docker pull ${namespace}/${repository}:${tag}
```
#### 操作系统安装 Docker 29.x.x 版本后无法拉取镜像
Docker 29.x.x 及以上版本存在兼容性问题，可能导致通过镜像加速器拉取镜像失败。建议卸载 29.x.x 版本并安装 18.06\~28.5 范围内的 Docker 版本。卸载和重装操作请参见[部署Docker](https://support.huaweicloud.com/bestpractice-ecs/zh-cn_topic_0141067581.html)。
#### 镜像层已拉取，但最后一个接口失败
**问题现象：** 镜像层下载完成后，Docker 在请求 referrers接口时返回失败，导致镜像拉取不完整。
![](https://support.huaweicloud.com/swr_faq/zh-cn_image_0000002770145851.png "点击放大")
**原因分析：** SWR 镜像加速器不支持 referrers 接口，Docker 28 及以上版本默认启用 containerd image store，会调用该接口，从而导致拉取失败。
**解决方案：**
- **方案一（推荐）：安装 Docker 28 以下版本**
  建议安装 Docker 18.06\~28.5 范围内的 Docker 版本，从[Docker 官方安装指南](https://docs.docker.com/engine/install/ubuntu/) 中选取具体版本进行安装，然后配置镜像加速器拉取镜像。
  **方案二：Docker 29 版本关闭 containerd image store**
  如果已安装 Docker 29.x.x，在 /etc/docker/daemon.json 中增加如下配置，重启 Docker 后即可正常使用镜像加速器拉取镜像：
  ```
  {
    "features": {
      "containerd-snapshotter": false
    }
  }
  ```
  ![](https://support.huaweicloud.com/swr_faq/public_sys-resources/caution_3.0-zh-cn.png)
  此配置为 JSON 格式，需确保格式正确（引号、逗号等），修改完成后执行 systemctl restart docker 重启 Docker 引擎使其生效。
  
 
#### Docker Hub 中存在对应版本镜像，但无法拉取
确认 Docker Hub 中镜像存在但通过镜像加速器无法拉取时，排查方法如下：
- 确认镜像架构与虚拟机架构是否一致。
- 确认镜像加速器地址正确，执行 docker info 检查配置。
- 确认镜像名称和版本号拼写正确，包括 namespace、repository 和 tag 的大小写。