> ## Content Index
> Fetch the complete content index at: https://isoziyuan.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 彻底告别Docker pull超时解决：2026零基础自建Docker镜像加速与registry mirror配置保姆级教程
- URL: https://isoziyuan.com/p/100124/
- Published: 2026-09-02T12:22:57.000Z
- Updated: 2026-09-02T12:22:57.000Z
- Author: Isoziyuan
- Tags: Docker, 错误排查, VPS

## 直击痛点：为什么2026年我们必须自建镜像加速？

如果你经常在国内 VPS 上折腾容器，大概率遇到过这个让人崩溃的画面：敲下 `docker pull` 后，进度条卡死不动，几分钟后无情地甩出一个 `net/http: TLS handshake timeout` 或 `context deadline exceeded`。

时间来到 2026 年 9 月，随着各大公共镜像站（如阿里、中科大、上交等）的策略调整或关停，依赖公共服务的时代已经彻底过去。对于开发者而言，**Docker pull超时解决**已经成了部署环境的第一道坎。

与其到处寻找朝生暮死的野生公共镜像源，不如把命运掌握在自己手里。今天，我将手把手带你完成**自建Docker镜像加速**服务。这不仅是一篇教程，更是为你梳理**Docker网络新手疑问**、掌握**VPS网络排查**的系统性指南。

---

## 准备工作与环境依赖

在开始之前，我们需要准备以下“弹药”（*注：本文基于 2026 年主流的 Ubuntu 24.04 LTS 系统编写，其他 Linux 发行版命令基本通用*）：

1. **一台海外 VPS**：作为拉取镜像的“中转站”和缓存节点（建议 1GB 内存以上，带宽充裕）。
2. **一台国内 VPS**：你需要拉取镜像的目标服务器。
3. **一个域名**：解析到海外 VPS 的 IP 上（本文假设域名为 `mirror.yourdomain.com`）。
4. **基础环境**：海外 VPS 已安装好 Docker 和 Docker Compose。

**💡 核心架构揭秘**：我们将使用官方的 `registry:2` 镜像开启 `Pull-through cache`（拉取透传缓存）模式，并配合 `Caddy` 自动配置 HTTPS。你的国内 VPS 请求该服务时，如果海外 VPS 有缓存则直接返回，没有则由海外 VPS 代为向 Docker Hub 拉取并缓存。

---

## 分步实战指令：搭建私有镜像加速服务

### 第一步：在海外 VPS 部署加速服务端

登录你的**海外 VPS**，创建一个工作目录并进入：

```bash
mkdir -p /opt/docker-mirror && cd /opt/docker-mirror

```

创建 `docker-compose.yml` 文件：

```bash
nano docker-compose.yml

```

填入以下核心配置（注意看注释）：

```yaml
version: '3.8'

services:
  registry:
    image: registry:2
    container_name: mirror-registry
    restart: always
    environment:
      # 开启缓存模式，指定上游为官方 Docker Hub
      - REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io
    volumes:
      # 将缓存的镜像数据持久化到本地
      - ./data:/var/lib/registry
    ports:
      - "127.0.0.1:5000:5000" # 仅监听本地，安全第一

  caddy:
    image: caddy:2-alpine
    container_name: mirror-caddy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data

```

接着，创建 `Caddyfile`。Caddy 是极其强大的 Web 服务器，能**自动帮我们申请和续期 SSL 证书**。

```bash
nano Caddyfile

```

填入以下配置，**实现白名单访问，防止你的节点被全网白嫖**：

```text
mirror.yourdomain.com {
    # 替换为你国内 VPS 的真实公网 IP
    @blocked not remote_ip 114.114.114.114 
    abort @blocked
    
    reverse_proxy 172.17.0.1:5000
}

```

*(注：`172.17.0.1` 通常是 Docker 宿主机默认网桥 IP，确保 Caddy 能把流量转发给宿主机 5000 端口的 registry)*

启动服务：

```bash
docker-compose up -d

```

### 第二步：在国内 VPS 进行 registry mirror配置

现在，登录你的**国内 VPS**，告诉 Docker 以后拉取镜像走我们自己的节点。

编辑 Docker 配置文件：

```bash
sudo mkdir -p /etc/docker
sudo nano /etc/docker/daemon.json

```

写入以下 JSON 配置（如果文件已有内容，请注意 JSON 格式的逗号）：

```json
{
  "registry-mirrors": [
    "https://mirror.yourdomain.com"
  ]
}

```

重启 Docker 服务使配置生效：

```bash
sudo systemctl restart docker

```

### 第三步：见证奇迹的时刻

在国内 VPS 上，验证配置是否成功：

```bash
docker info | grep "Registry Mirrors" -A 1

```

如果输出中包含你的域名，说明配置已加载！现在，尝试拉取一个镜像：

```bash
docker pull ubuntu:24.04

```

你会发现，原本卡死不动的进度条，现在正以海外 VPS 的网络带宽飞速下载！

---

## 常见排错指南 (FAQ & Troubleshooting)

在实战中，网络环境千变万化。以下是我总结的**容器拉取失败报错处理**经验。

### 1\. 报错：`Error response from daemon: Get "https://...": dial tcp... i/o timeout`

**诊断**：这是最典型的网络连通性问题。  
**VPS网络排查步骤**：

- 在国内 VPS 上执行 `ping mirror.yourdomain.com`，看是否能解析出海外 VPS 的 IP。
- 执行 `curl -I https://mirror.yourdomain.com/v2/`。如果一直卡住，说明你的海外 VPS IP 或特定端口可能已被 GFW 阻断。
- **解决方案**：考虑更换海外 VPS 的 IP，或者在两台 VPS 之间建立更底层的加密隧道（如 WireGuard），将 registry 监听在隧道内网 IP 上。

### 2\. 报错：`http: server gave HTTP response to HTTPS client`

**诊断**：Docker 默认要求镜像源必须提供安全的 HTTPS 连接。  
**解决方案**：检查海外 VPS 上的 Caddy 日志 `docker logs mirror-caddy`，确认 SSL 证书是否申请成功。如果你执意要用 HTTP（强烈不建议），必须在国内 VPS 的 `daemon.json` 中添加 `"insecure-registries": ["http://mirror.yourdomain.com"]`。

### 3\. 报错：`unauthorized: authentication required` 或拉取私有镜像失败

**诊断**：官方的 `registry:2` 作为代理缓存时（`REGISTRY_PROXY_REMOTEURL`），**仅支持代理公共镜像**。  
**解决方案**：如果你需要拉取私有仓库的镜像，不能通过 `registry-mirrors` 机制。你必须在国内 VPS 上直接 `docker login` 目标仓库，并考虑为 Docker Daemon 配置 HTTP/HTTPS Proxy，而不是使用 Mirror。

### 4\. Docker网络新手疑问：给 Docker 配置代理和自建 Mirror 有什么区别？

很多新手问：“我直接在国内 VPS 的 `/etc/systemd/system/docker.service.d/http-proxy.conf` 里配个代理不就行了？”

- **全局代理**：会把 Docker 的所有流量（包括拉取镜像、甚至部分容器内的网络构建）都走代理，容易引发不可预知的网络冲突。
- **自建 Mirror**：属于**按需拉取+永久缓存**。第一次拉取 `nginx` 镜像时，海外 VPS 下载并缓存，国内 VPS 从海外拉取；第二次在国内其他 VPS 上配置同一个 Mirror 拉取 `nginx` 时，海外 VPS 直接从本地硬盘秒传，极大地节省了国际出口带宽和时间！

## 结语

通过这套方案，你不仅完美实现了**Docker pull超时解决**，还顺带搭建了一个专属的团队级镜像缓存中心。技术在不断演进，网络环境也在随时变化，但只要掌握了底层的网络流转逻辑和排错思路，无论 2026 年还是未来，你都能从容应对。

如果这篇教程对你有帮助，欢迎点赞转发。遇到任何奇怪的报错，也欢迎在评论区贴出你的日志，我们一起探讨！