常见问题

4 months ago
fc5fd50

当使用毫秒镜像拉取镜像失败时，可以按照以下步骤进行系统化排查和解决。

排查步骤

1. 检查镜像地址配置

首先确认Docker是否已正确配置镜像加速地址：

docker info

在输出中查找Registry Mirrors部分，确认是否包含docker.1ms.run。如图
301d4b1393227fc1d7cc5dd838543648.png

2. 测试直接拉取镜像

尝试直接拉取镜像测试连接性：

    docker pull docker.1ms.run/library/nginx

3. 检查镜像版本可用性

当遇到镜像拉取失败时，一个重要但常被忽视的环节是确认目标镜像版本是否存在。可以通过以下方式验证：

1.访问镜像仓库搜索页面​​：
打开浏览器访问：

https://1ms.run/search?query={镜像名称}

将{镜像名称}替换为你实际需要拉取的镜像名（如nginx、redis等）

  1. ​​验证镜像版本​​：

    • 在搜索结果中确认所需镜像版本是否存在于仓库中
    • 特别注意镜像的tag（版本标签）是否正确
    • 检查镜像的更新时间，避免使用已过期的版本

  2. ​​获取正确的拉取命令​​：
    在确认镜像可用后，可以直接复制页面提供的标准拉取命令，例如：

docker pull docker.1ms.run/library/nginx:1.25.3

这样可以确保使用的镜像地址和版本完全正确。

注意事项​​：

  • 某些镜像可能有不同的仓库路径（如library/前缀）

4.检查网络连通性

如果直接拉取失败，检查网络连接：

ping docker.1ms.run

5.验证系统时间

不正确的系统时间可能导致SSL证书验证失败：

date

如果时间不正确，进行时间校准：

sudo yum install ca-certificates

6. DNS问题

9E8DFB45EAC006ABFC8917319A9D30F2.jpg

shell执行下面的命令

echo "nameserver 114.114.114.114" >> /etc/resolv.conf

如果非root用户使用如下命令

echo "nameserver 114.114.114.114" | sudo tee /etc/resolv.conf

7. 检查Docker版本

查看当前Docker版本：

docker --version
docker info

如果版本过低，建议升级到最新版本。

Ubuntu/Debian

# 更新软件包索引
sudo apt-get update

# 卸载旧版本
sudo apt-get remove docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 设置稳定版仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装最新版Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# 验证安装
docker --version

CentOS/RHEL

# 卸载旧版本
sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine

# 安装依赖
sudo yum install -y yum-utils

# 设置仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装最新版Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 启动Docker
sudo systemctl start docker
sudo systemctl enable docker

# 验证安装
docker --version

8. 推荐的重装docker后执行命令

如果重新安装Docker，重装后推荐使用以下命令：

curl -s https://static.1ms.run/1ms-helper/scripts/install.sh | sudo bash /dev/stdin config:mirror

9. docker desktop

desktop.webp

  • 在shell执行拉取确认网络和服务是否正常（步骤2）
  • desktop的假重启。要关掉软件进程重新启动。

10. docker search 报错？

  1. search 命令，需要全路径
 docker search docker.1ms.run/tomcat
  1. 用网页搜索结果， 比如： https://1ms.run/search?query=tomcat

11. unsupported media type 错误？

升级至最新版本可解决

Docker 26（旧版）

只支持: application/vnd.oci.image.manifest.v1+json
不支持: application/vnd.oci.empty.v1+json (OCI v1.1+)

Docker 29+（新版）

支持所有OCI v1.1规范

docker pull docker.1ms.run/bitnami/postgresql:sha256-3a49168b603ca7956979e7fec71716764dfcf6f76c0558e6c825ef8e5dd239b5
sha256-3a49168b603ca7956979e7fec71716764dfcf6f76c0558e6c825ef8e5dd239b5: Pulling from bitnami/postgresql
unsupported media type application/vnd.oci.empty.v1+json

docker 26 拉取失败

docker 29 拉取成功

docker buildx build 报错

导致这个现象的原因在于 docker build 和 docker buildx build 底层使用的构建引擎和配置加载方式不同。

从你的截图中可以看到右上角写着 docker-container:multiarch，这意味着你正在使用 docker-container 驱动来进行 buildx 构建。

  • 普通的 docker build 直接使用宿主机上的 Docker Daemon，它会自动读取 /etc/docker/daemon.json 中配置的 registry-mirrors 镜像加速器。
  • docker buildx (使用 docker-container 驱动时) 会启动一个独立的 BuildKit 容器（也就是你截图里的那个实例）来执行构建。这个独立的 BuildKit 容器默认并不会继承宿主机 daemon.json 里的镜像加速配置，所以它依然会尝试直接连接 registry-1.docker.io，导致 i/o timeout 网络超时。

要解决这个问题，你需要显式地为 BuildKit 实例配置镜像加速器。以下是具体的解决步骤：

解决方案：为 BuildKit 配置镜像加速器

你需要创建一个配置文件，然后用这个配置文件创建一个新的 buildx 实例。

第一步：创建 BuildKit 配置文件

在你的当前目录或者任意位置创建一个名为 buildkitd.toml 的文件，写入以下内容：

debug = true
[registry."docker.io"]
  mirrors = ["https://你的镜像加速器地址"]

注意：请把 https://你的镜像加速器地址 替换为你已经在 daemon.json 中配置并确认有效的那个加速器地址（例如阿里云、腾讯云或其他可用镜像站）。

第二步：使用该配置创建新的 buildx 实例

在终端依次运行以下命令，删除旧的实例（可选），并使用刚才的配置创建并启用新实例：

# 1. (可选) 清理现有的失败的构建器，假设你之前使用的是 multiarch 
# docker buildx rm multiarch

# 2. 创建一个新的 builder 实例，并挂载刚刚的配置文件
docker buildx create --use --name mybuilder --driver docker-container --config ./buildkitd.toml

# 3. 启动并检查该实例
docker buildx inspect mybuilder --bootstrap

完成这一步后，再次运行你的构建命令：
docker buildx build --platform linux/arm64 -t netbouncer-test-arm64 .
此时它就会通过你配置的加速器去拉取 Ubuntu 等基础镜像了。

missing signature key 错误

请升级Docker。版本太低，该版本的docker官方已经废弃支持。最低升级到docker 24 ,建议升级到最新版本。

是否免费？

毫秒镜像提供 免费 和 付费 两个版本。
免费版 使用 cloudflare 提供的CDN分发能力对外提供下载拉取能力。
付费版 使用 中国大陆 的多家CDN服务商的分发能力和对象存储服务，为付费用户提供稳定快速的镜像下载和拉取能力。

毫秒镜像 免费版 使用的是Cloudflare付费版本。
为保障 免费版 的可用性，镜像清单服务免费版和付费版服务相同。
免费版 和 付费版 仅在CDN线路和SLA稳定性保证不一样（企业版提供额外定制）

毫秒镜像是否盈利？

镜像服务至今无法覆盖服务器、CDN、对象存储和人力成本，木雷坞不依靠 毫秒镜像 的个人用户赚钱。（除去人力，勉强覆盖成本）

毫秒搜不到我需要的镜像

毫秒镜像的网站数据是被动更新，如果你没找到，可以尝试直接拉取镜像，如若源仓库真实存在是可以下载成功的（违法镜像无法搜索，拉取会提示相应提示），拉取成功后毫秒镜像的服务会在随后的几分钟内同步数据到页面展示。

镜像源与登录鉴权 Q/A

Q1：为什么已经配置毫秒镜像，Docker CLI 仍然读取 Docker Hub 的鉴权参数？

因为 registry-mirrors 是 Docker Hub 的透明拉取加速配置，不是默认仓库替换配置。执行 docker pull nginx 时，镜像仍然属于 docker.io/library/nginx，所以 Docker CLI 会按 docker.io 查找凭据；Docker Daemon 随后才决定通过毫秒镜像还是 Docker Hub 下载。

这是 Docker 的正常工作机制，不代表镜像源配置没有生效。可以通过 docker info 中的 Registry Mirrors 确认镜像源是否已经加载。

Q2：为什么执行 docker login docker.1ms.run 后，docker pull nginx 没有使用毫秒镜像账号？

Docker 凭据按仓库主机名保存。docker login docker.1ms.run 保存的是 docker.1ms.run 的凭据，而 docker pull nginx 对应的逻辑仓库是 docker.io，两者不是同一个凭据条目。

原版登录后，请使用带毫秒镜像前缀的命令：

docker pull docker.1ms.run/library/nginx:latest

如果希望继续使用不带前缀的命令：

docker pull nginx:latest

付费用户可以选择以下任一方式：

  • 使用一键登录完成所需配置。
  • 创建并配置专属域名。将 Docker Hub 专属域名设置为 registry-mirrors 后，可以免登录使用无前缀命令。

Q3：daemon.json 和 ~/.docker/config.json 有什么区别？

  • /etc/docker/daemon.json 是 Docker Daemon 配置，registry-mirrors 决定优先访问哪些镜像下载端点。
  • ~/.docker/config.json 是当前用户的 Docker CLI 配置，保存或引用各个仓库的登录凭据。

修改 daemon.json 不会自动创建或迁移 CLI 登录凭据；执行 docker login 也不会自动修改 registry-mirrors。

Q4：为什么错误日志里仍然出现 registry-1.docker.io 或 auth.docker.io？

可能有以下原因：

  1. 配置的镜像源访问失败，Docker 回退到了 Docker Hub。
  2. 使用 docker buildx 的 docker-container 驱动，独立 BuildKit 没有继承宿主机的 daemon.json。
  3. 当前操作需要按镜像的逻辑来源完成鉴权，所以日志中仍会出现 Docker Hub 的认证地址。

先运行 docker info 检查 Registry Mirrors，再直接测试：

docker pull docker.1ms.run/library/nginx:latest

如果普通拉取正常、只有 docker buildx build 失败，请参考本文前面的 BuildKit 镜像源配置方法。

Q5：可以把毫秒镜像账号密码写进 registry-mirrors 地址吗？

不建议，也不要使用类似下面的配置：

{
  "registry-mirrors": [
    "https://用户名:密码@docker.1ms.run"
  ]
}

Docker 的镜像源配置没有提供独立的 CLI 凭据映射；把密钥放进 URL 还可能出现在配置文件、日志、备份或诊断信息中。请使用一键登录、配置专属域名，或者通过 docker login docker.1ms.run 配合带前缀的镜像地址。

问题仍未解决？

通过以上系统化的排查步骤，您应该已经解决了大部分Docker镜像拉取的问题。如果问题依然存在，我们为您提供了以下支持渠道：

1. 加入技术交流群

欢迎加入我们的Docker技术交流QQ群，与众多开发者一起讨论解决方案：

QQ 企业微信
QQ群号：697500389
获得免费技术支持		 扫描上方二维码加入微信群

2. 问题反馈建议

为了更高效地解决问题，建议反馈时提供以下信息：

  • 操作步骤和执行的命令
  • 操作系统和Docker版本信息
  • 网络环境描述

我们的技术团队会在收到问题后尽快为您提供解决方案。