自建Docker Hub镜像方法

为啥要自建 Docker 镜像源

2023 年 5 月开始,中国大陆访问 Docker Hub 官方域名 hub.docker.com 越来越不稳。一开始还能用国内镜像源(网易、阿里、腾讯、中科大、上交、南大、dockerproxy 等)勉强续命,但到 2024-2025 年,大部分国内 Docker 镜像源相继停服或限制访问:

• 网易、百度 —— 早就死了
• 南京大学、中科大、上海交大 —— 2024 年明确停止 Docker 镜像缓存服务
• dockerproxy —— 被墙
• 腾讯云 / 微软 —— 据说内网可用,公网不行
• 阿里云 —— 登录后能拿到子域名(每个账号独享一个加速地址)

结果就是,日常 docker pull nginx 这种本来 10 秒的事,现在要么超时要么慢得抓狂。自建一个 Docker 镜像代理就成了刚需。

本文介绍两种自建方法,各有适用场景:

• 方式一:Cloudflare Worker —— 不要服务器,只要域名,免费额度够个人用
• 方式二:境外 VPS —— 自己跑 Nginx 反向代理,完全可控但要付服务器费

方式一:用 Cloudflare Worker

注册 Cloudflare 账号(邮箱免费注册),前提是有自己的域名。Cloudflare Workers 免费版每天 10 万次请求,个人足够用。

步骤 1:创建 Worker

1. 登录 Cloudflare,左侧菜单 → "Workers 和 Pages" → "创建应用程序" → "创建 Worker"
2. 起个名字,比如 docker-proxy,点"保存"
3. 点"完成",会跳到 Worker 列表
4. 点击你刚创建的 Worker → "编辑代码"

步骤 2:粘贴代理代码

'use strict'

/**
 * Docker Hub 镜像代理 — Cloudflare Worker
 * 部署后把下面的 workers_url 改成你绑定的自定义域名
 */
let hub_host = 'registry-1.docker.io'   // Docker 官方镜像仓库
let auth_url = 'https://auth.docker.io' // Docker 官方授权服务
let workers_url = 'https://你的域名'     // ← 改成你的 Worker 自定义域名

const PREFLIGHT_INIT = {
  status: 204,
  headers: new Headers({
    'access-control-allow-origin': '*',
    'access-control-allow-methods': 'GET,POST,PUT,PATCH,TRACE,DELETE,HEAD,OPTIONS',
    'access-control-max-age': '1728000',
  }),
}

function makeRes(body, status = 200, headers = {}) {
  headers['access-control-allow-origin'] = '*'
  return new Response(body, { status, headers })
}

function newUrl(urlStr) {
  try {
    return new URL(urlStr)
  } catch (err) {
    return null
  }
}

addEventListener('fetch', e => {
  const ret = fetchHandler(e)
    .catch(err => makeRes('cfworker error:n' + err.stack, 502))
  e.respondWith(ret)
})

async function fetchHandler(e) {
  const getReqHeader = (key) => e.request.headers.get(key)

  let url = new URL(e.request.url)

  // /token 请求转发到 Docker 授权服务
  if (url.pathname === '/token') {
    let token_parameter = {
      headers: {
        'Host': 'auth.docker.io',
        'User-Agent': getReqHeader('User-Agent'),
        'Accept': getReqHeader('Accept'),
        'Accept-Language': getReqHeader('Accept-Language'),
        'Accept-Encoding': getReqHeader('Accept-Encoding'),
        'Connection': 'keep-alive',
        'Cache-Control': 'no-cache',
      },
    }
    let token_url = auth_url + url.pathname + url.search
    return fetch(new Request(token_url, e.request), token_parameter)
  }

  // 其余请求转发到 Docker Hub
  url.hostname = hub_host

  let parameter = {
    headers: {
      'Host': hub_host,
      'User-Agent': getReqHeader('User-Agent'),
      'Accept': getReqHeader('Accept'),
      'Accept-Language': getReqHeader('Accept-Language'),
      'Accept-Encoding': getReqHeader('Accept-Encoding'),
      'Connection': 'keep-alive',
      'Cache-Control': 'no-cache',
    },
    cacheTtl: 3600,
  }

  if (e.request.headers.has('Authorization')) {
    parameter.headers.Authorization = getReqHeader('Authorization')
  }

  let original_response = await fetch(new Request(url, e.request), parameter)
  let original_response_clone = original_response.clone()
  let original_text = original_response_clone.body
  let response_headers = original_response.headers
  let new_response_headers = new Headers(response_headers)
  let status = original_response.status

  // 把鉴权地址改写成走自己的 Worker
  if (new_response_headers.get('Www-Authenticate')) {
    let re = new RegExp(auth_url, 'g')
    new_response_headers.set(
      'Www-Authenticate',
      response_headers.get('Www-Authenticate').replace(re, workers_url)
    )
  }

  // 镜像层 302 跳转,继续代理
  if (new_response_headers.get('Location')) {
    return httpHandler(e.request, new_response_headers.get('Location'))
  }

  return new Response(original_text, {
    status,
    headers: new_response_headers,
  })
}

function httpHandler(req, pathname) {
  const reqHdrRaw = req.headers

  if (
    req.method === 'OPTIONS' &&
    reqHdrRaw.has('access-control-request-headers')
  ) {
    return new Response(null, PREFLIGHT_INIT)
  }

  const reqHdrNew = new Headers(reqHdrRaw)
  const urlObj = newUrl(pathname)

  const reqInit = {
    method: req.method,
    headers: reqHdrNew,
    redirect: 'follow',
    body: req.body,
  }
  return proxy(urlObj, reqInit)
}

async function proxy(urlObj, reqInit) {
  const res = await fetch(urlObj.href, reqInit)
  const resHdrNew = new Headers(res.headers)

  resHdrNew.set('access-control-expose-headers', '*')
  resHdrNew.set('access-control-allow-origin', '*')
  resHdrNew.set('Cache-Control', 'max-age=1500')

  resHdrNew.delete('content-security-policy')
  resHdrNew.delete('content-security-policy-report-only')
  resHdrNew.delete('clear-site-data')

  return new Response(res.body, {
    status: res.status,
    headers: resHdrNew,
  })
}

把默认的 hello world 代码删掉,粘贴上面这段。点"保存并部署"。

步骤 3:绑定自定义域名

这一步必须 —— Worker 默认给你的 your-worker.workers.dev 域名国内访问不稳定。绑自己的域名后,通过你域名访问就 OK。

1. Worker 详情页 → "触发器" → "自定义域" → 添加
2. 填一个你的子域名,比如 docker.example.com
3. Cloudflare 会自动配 DNS 和 SSL,几分钟生效

步骤 4:配置 Docker 使用代理

修改本机 Docker 的 daemon 配置文件:

echo '{"registry-mirrors": ["https://你的域名"]}' | sudo tee /etc/docker/daemon.json > /dev/null

重启 Docker:

sudo systemctl restart docker

现在 docker pull nginx 实际访问的就是 docker.example.com,Cloudflare Worker 中转到 Docker Hub。延迟 200ms,速度跑满你的带宽。

方式二:用境外 VPS + Nginx

如果你有一台境外的 VPS(美国、香港、新加坡都行),可以直接用 Nginx 做反代,更稳定、更可控。

Nginx 配置

bash <(curl -sL https://raw.githubusercontent.com/lainbo/gists-hub/master/src/Linux/sh/deploy_registry.sh)

关键点:

• proxy_pass 转发到 registry-1.docker.io(Docker 真正的镜像服务器)
• 必须保留 Host 头,Docker Hub 鉴权依赖这个
• proxy_redirect 改写 302 跳转里的 URL,让 Docker 客户端不直接跳到原域名

使用

#version: '3' #最新版本docker 不需要此字段
services:
  registry:
    image: registry:2
    ports:
      - "17951:5000"
    environment:
      REGISTRY_PROXY_REMOTEURL: https://registry-1.docker.io  # 上游源
      REGISTRY_STORAGE_CACHE_BLOBDESCRIPTOR: inmemory # 内存缓存
    volumes:
      - ./data:/var/lib/registry

同方式一,改 /etc/docker/daemon.json 然后重启 Docker。

其他配置文件示例

如果你部署的是更复杂的 Docker Compose 项目:

echo '{"registry-mirrors": ["https://你反代的域名"]}' | sudo tee /etc/docker/daemon.json > /dev/null

验证代理生效:

sudo systemctl restart docker

看到 Successfully tagged ... + 跳传速度,就是用上代理了。

对比两种方式

个人 / 小团队优先 Cloudflare Worker。规模上来(团队几十个开发同时拉镜像)用 VPS,再上量就要考虑搭自己的 registry 镜像加缓存。

替代方案:用 GHCR / 自己的私有 registry

除了代理 Docker Hub,还可以:

• 把镜像同步到 GitHub Container Registry (GHCR) —— GitHub Actions 配置自动同步,然后 pull ghcr.io/your-name/image。GHCR 国内速度比 Hub 好。
• 搭自己的 registry —— docker run -d -p 5000:5000 registry:2 一行命令,做团队内部镜像中转。
• 用国内云厂商的容器镜像服务 —— 阿里云 ACR、腾讯云 TCR、华为云 SWR,免费版能用,适合个人项目。

2024-2025 年 Docker 镜像可用性变化非常快,这个清单可能半年后又得更新。维护一个自己的 worker / 反代,长期来看比依赖任何公共镜像源都靠谱。

—— 别看了 · 2026