自建 Docker Hub 镜像代理，彻底解决 Docker 拉取镜像慢、失败的问题

1. 需要准备什么

• Cloudflare 账户。
• 一个 Cloudflare Worker。
• 建议准备一个自有域名，并把 DNS 托管到 Cloudflare，例如将 docker.example.com 绑定给 Worker。
• Docker Hub 账号（强烈建议），以及为它创建的 Personal Access Token（PAT）。
  
  

Cloudflare Worker 虽可使用部署后提供的 workers.dev 地址，但稳定使用 Docker registry mirror 时，建议绑定自己的域名。绑定位置为 Cloudflare Dashboard → Workers & Pages → 你的 Worker → Settings → Domains & Routes → Add。

2. 工作方式
Docker 客户端
  ↓ GET /v2/...
你的域名（Cloudflare Worker）
  ├─ registry-1.docker.io：manifest、tag
  ├─ auth.docker.io：鉴权 token
  └─ Docker CDN：镜像 blob 的 307 跳转由 Worker 统一回源

脚本会自动为官方镜像补齐 library 命名空间，例如 docker.example.com/nginx 等价于 Docker Hub 的 library/nginx。

3. 部署步骤：在 Cloudflare 控制台部署

• 登录 Cloudflare Dashboard。
• 进入 Workers & Pages → Create application → Create Worker。
• 设置名称，例如 docker-hub-proxy，然后点击 Deploy。
• 打开刚创建的 Worker，点击 Edit code。
• 删除默认代码，粘贴 docker-proxy-worker.text的全部内容。
• 点击 Deploy。
• 打开 Settings → Domains & Routes → Add，绑定 docker.example.com。
• 等待 Cloudflare 域名和 HTTPS 证书状态就绪。
  docker-poxy-worker.txt下载地址
  

  1. https://wwbto.lanzouv.com/i3RYm3xrn0xa

  复制代码
  
  

首次验证：

curl -i https://docker.example.com/v2/
docker pull docker.example.com/alpine:latest
docker pull docker.example.com/nginx:latest

其中 /v2/ 返回 401 Unauthorized 且含 WWW-Authenticate 是 Docker Registry 的正常鉴权流程，Docker 客户端会自动取 token 并重试。

4. 三个核心变量

变量	是否必需	保存位置	用途
DH_USERNAME	否，但强烈建议	Worker Secret	Docker Hub 用户名
DH_PASSWORD	否，但强烈建议	Worker Secret	Docker Hub 密码或 PAT
PROXY_TOKEN_KEY	否，但公开服务强烈建议	Worker Secret	为代理 token 做 HMAC-SHA256 签名的随机密钥

未设置 Docker Hub 凭据时会匿名拉取。匿名请求使用 Cloudflare 共享出口 IP，容易出现 429 TOOMANYREQUESTS。

• 4.1 配置 DH_USERNAME
  
  用途：Worker 用此用户名向 Docker Hub 获取账户级拉取 token，避免匿名共享额度。
  如何获取：登录 Docker Hub，在账户菜单或 Account Settings 中查看 Docker Hub 用户名。通常不要填邮箱。
  配置位置：
  
  
  • 控制台：Worker → Settings → Variables and Secrets → Secrets → Add。名称填写 DH_USERNAME。
    
    
  4.2 配置 DH_PASSWORD
  
  用途：与 DH_USERNAME 配对，供 Worker 向 Docker Hub 鉴权。
  推荐使用 Docker Hub Personal Access Token（PAT），不要使用日常登录密码。PAT 可独立撤销，泄露后的风险更可控。
  获取方法：
  • 登录 Docker Hub。
  • 在 Account Settings 中找到 Personal access tokens。
  • 新建 token，名称例如 cloudflare-docker-proxy。
  • 按 Docker Hub 页面选择满足拉取用途的最小权限。
  • 创建后立即复制 token；通常无法再次查看，遗失后只能重新创建。
    
    
  配置位置：
  • 控制台：新增 Secret，名称 DH_PASSWORD，值为 Docker Hub PAT。
    
    
  4.3 配置 PROXY_TOKEN_KEY
  
  用途：启用 token 保护。未启用时，客户端可能从 /token 获得真实 Docker Hub token。启用后，Worker 只向客户端签发本代理有效的 proxy token；Docker Hub 的真实 token 留在 Worker 内部。
  来源：这是你自己生成的高强度随机秘密，不需要从 Cloudflare 或 Docker Hub 申请。
  生成并设置：
  1. openssl rand -base64 32 | tr -d '\n' | npx wrangler secret put PROXY_TOKEN_KEY

  复制代码
  如无 OpenSSL，可用 Node.js 生成：
  1. node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

  复制代码
  也可在控制台新增一个名称为 PROXY_TOKEN_KEY 的 Secret，将上述命令的输出粘贴进去。
  注意：轮换该密钥会使已签发的旧 proxy token 失效；项目的 token 默认生命周期较短，影响通常仅限于当前拉取重新鉴权。
  
  
  5. 配置加速器配置
  
  在Nas Docker应用中加速器配置添加 你在Cloudflare Worker配置的域名。
  

  1. https://docker.example.com

  复制代码
  6. 安全与故障排查
  
  • 公开服务务必设置 PROXY_TOKEN_KEY。
  • 账号池或单账号额度由所有使用者共享；若只供特定人使用，请设置 ACCESS_KEY。
  • 怀疑 Docker Hub PAT 泄露时，在 Docker Hub 立即撤销，创建新 PAT，并覆盖 DH_PASSWORD。
  • 429 TOOMANYREQUESTS：先检查是否已配置 DH_USERNAME、DH_PASSWORD；高频场景配置 D1 账号池。
  • 不支持 docker push 是设计限制，不是配置错误。
  • 自定义域名必须能在 Cloudflare 账户中管理，且 HTTPS 证书状态应正常。