HF-Space-DockerHub-Proxy

hohouman/hf-space-dockerhub-proxy

基于 Hugging Face Space + Cloudflare Pages 的高可用、抗污染 Docker Hub 镜像加速方案。

📖 背景与痛点

随着 Docker Hub 对匿名拉取限制的收紧（100次/6小时），以及对 Cloudflare 泛播 IP 的严格风控，传统的 "CF Worker 反代" 方案已难以稳定使用。

本方案通过 Hugging Face Space 作为中间层，利用其 AWS 基础设施“洗白”IP，并支持服务端强制注入账号认证，从而实现：

1. 解除限流：将匿名请求转换为认证请求（Pro 账号无限拉取）。
2. 避开风控：不再使用被 Docker Hub 标记的 Cloudflare IP 回源。
3. 抗污能力：前端 Cloudflare 自定义域名解决 SNI 阻断。

🚀 部署指南

第一步：后端部署 (Hugging Face)

1. 创建 Space：

   • 登录 Hugging Face。
   • SDK: 选择 Docker。
   • Template: 选择 Blank。
   • Visibility: 建议 Public（私有 Space 需额外处理 Token 鉴权）。

2. 配置 Dockerfile：
   在 Space 文件列表中新建 Dockerfile：

   FROM registry:2
   
   USER root
   
   # 端口配置 (HF Space 默认端口)
   ENV REGISTRY_HTTP_ADDR=:7860
   EXPOSE 7860
   
   # 开启 Proxy 模式 (指向官方源)
   ENV REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io
   
   # 注入认证信息 (核心步骤：解决 Rate Limit)
   # 变量值将在 Space 设置中读取，切勿直接写在 Dockerfile 里
   ENV REGISTRY_PROXY_USERNAME=${DOCKER_USER}
   ENV REGISTRY_PROXY_PASSWORD=${DOCKER_PASSWORD}
   
   # 允许删除 (可选)
   ENV REGISTRY_STORAGE_DELETE_ENABLED=true
   
   # 权限修正
   RUN mkdir -p /var/lib/registry && \
       chmod -R 777 /var/lib/registry
   
   CMD ["/etc/docker/registry/config.yml"]

3. 设置环境变量 (Secrets)：
   进入 Space 的 Settings -> Variables and secrets，添加以下 Secrets：

   • DOCKER_USER: 你的 Docker Hub 用户名
   • DOCKER_PASSWORD: 你的 Docker Hub Access Token (推荐) 或密码

第二步：边缘部署 (Cloudflare Pages)

1. 准备 Worker 脚本：
   在本地创建一个目录（例如 proxy），并在其中新建 _worker.js 文件：

   // 请修改为你的 Hugging Face Space 域名
   const UPSTREAM_DOMAIN = "your-space-name.hf.space";
   
   export default {
     async fetch(request, env) {
       const url = new URL(request.url);
   
       // 仅放行 Docker V2 API
       if (!url.pathname.startsWith('/v2/')) {
           return new Response('Registry is active.', { status: 200 });
       }
   
      // 修改回源 Host
       url.hostname = UPSTREAM_DOMAIN;
       url.protocol = 'https:';
   
       // 构建新请求
       const newRequest = new Request(url, {
         method: request.method,
         headers: request.headers,
         body: request.body,
         redirect: 'follow'
       });
   
       return fetch(newRequest);
     }
   };

2. 部署到 Pages：

   • 登录 Cloudflare Dashboard -> Compute (Workers & Pages) -> Create Application -> Pages -> Upload assets。
   • 上传包含 _worker.js 的目录。
   • 部署完成后，进入项目设置，绑定自定义域名（例如 docker.yourdomain.com）。
   • 注意：必须使用自定义域名，以防止CF 分配的 `.pages.dev` 域名在某些地区被DNS污染。*

💻 客户端配置

修改服务器上的 /etc/docker/daemon.json：

{
  "registry-mirrors": [
    "https://docker.yourdomain.com"
  ]
}

重载配置并重启 Docker：

sudo systemctl daemon-reload && sudo systemctl restart docker

✅ 验证与常见问题

1. 测试拉取

docker pull busybox

如果能正常拉取，说明链路已打通。

2. 关于 "Cold Start" (冷启动)

免费版 Hugging Face Space 在闲置 48 小时后会进入休眠状态。

• 现象：第一次 docker pull 可能会卡住或超时。
• 解决：这是正常现象，HF 正在后台唤醒容器（Building/Starting）。等待约 1 分钟后再次重试即可。

3. 为什么需要 Docker Hub 账号？

如果不配置 DOCKER_USER 和 PASSWORD，请求实际上还是匿名的。虽然 HF 的 IP 质量比 CF 好，但依然受到 Docker Hub 对 IP 的匿名限流（单 IP 限制）。配置账号后，限制将变为针对账号（免费号 200次/6小时），且多个 HF Space 实例可复用同一账号额度。