Container 镜像拉取问题排查手册

最后更新: 2026-02-07 摘要: 解决国内环境下 Docker 镜像拉取卡顿、超时或失败的常见方法汇总。

1. 现象描述

• docker pull 进度条长时间不动。
• 提示 error pulling image configuration: download failed。
• 提示 Get "https://registry-1.docker.io/...": dial tcp ...: i/o timeout。

2. 解决方案 (按推荐顺序)

方案 A: 使用第三方镜像加速源 (当前推荐)

国内云厂商（阿里/腾讯/网易）的加速器经常失效，目前推荐使用第三方维护的代理镜像源。

常用代理源列表 (2026):

• docker.1panel.live (1Panel 维护)
• docker.m.daocloud.io (DaoCloud)
• dockerproxy.com
• docker.nju.edu.cn (南京大学 - 仅限部分教育网)

使用方法 1: 修改 daemon.json (全局生效) 修改 /etc/docker/daemon.json:

{
  "registry-mirrors": [
    "https://docker.1panel.live",
    "https://docker.m.daocloud.io"
  ]
}

重启 Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

使用方法 2: 修改 docker-compose.yml (推荐) 直接 stere image 字段前加上镜像源地址。这样更明确，且不受宿主机配置影响。

services:
  trilium:
    # 原: zadam/trilium:latest
    image: docker.1panel.live/zadam/trilium:latest

  nextcloud:
    # 原: nextcloud:28
    image: docker.1panel.live/library/nextcloud:28

---

方案 B: 手动拉取并重命名 (临时救急)

如果不想修改配置文件，可以手动拉取后再 tag 回原名（可选）。

# 1. 从代理源拉取
docker pull docker.1panel.live/zadam/trilium:latest

# 2. (可选) 重命名为官方名称
docker tag docker.1panel.live/zadam/trilium:latest zadam/trilium:latest

# 3. (可选) 删除代理名称
docker rmi docker.1panel.live/zadam/trilium:latest

---

方案 C: 配置 HTTP 代理 (终极方案)

如果有可用的 HTTP 代理服务器，可以让 Docker 守护进程走代理。

1. 创建配置目录

sudo mkdir -p /etc/systemd/system/docker.service.d

2. 创建代理配置文件 编辑 /etc/systemd/system/docker.service.d/http-proxy.conf:

[Service]
Environment="HTTP_PROXY=http://192.168.1.5:7890"
Environment="HTTPS_PROXY=http://192.168.1.5:7890"
Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.somecorporation.com"

3. 重启 Docker

sudo systemctl daemon-reload
sudo systemctl restart docker

4. 验证

sudo systemctl show --property=Environment docker

---

3. 常见问题

• Q: 为什么阿里云加速器不行了？
  • A: 由于网络管制和 Docker Hub 策略调整，官方和云厂商的公开加速器经常处于不可用状态。
• Q: docker-compose 里的 image 修改后，还需要改回来吗？
  • A: 不需要。代理源通常会同步官方镜像，长期使用也没问题。只要能拉下来就行。