白嫖 HFSpace 的 AWS 基础设施用作 DockerHub 镜像源

HF-Space-DockerHub-Proxy
https://github.com/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，并支持服务端强制注入账号认证，从而实现：

解除限流：将匿名请求转换为认证请求（Pro 账号无限拉取）。
避开风控：不再使用被 Docker Hub 标记的 Cloudflare IP 回源。
抗污能力：前端 Cloudflare 自定义域名解决 SNI 阻断。
🚀 部署指南
第一步：后端部署 (Hugging Face)
1.创建 Space：
1.1 登录 https://huggingface.co/new-space
1.2SDK: 选择 Docker。
1.3Template: 选择 Blank。
1.4Visibility: 建议 Public（私有 Space 需额外处理 Token 鉴权）。
2.配置 Dockerfile：
2.1 在 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)：
3.1 进入 Space 的 Settings -> Variables and secrets，添加以下 Secrets：
3.1.1DOCKER_USER: 你的 Docker Hub 用户名
3.1.2DOCKER_PASSWORD: 你的 Docker Hub Access Token (推荐) 或密码

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

1.准备 Worker 脚本：
1.1 在本地创建一个目录（例如 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：
2.1 登录 Cloudflare Dashboard -> Compute (Workers & Pages) -> Create Application -> Pages -> Upload assets。
2.2 上传包含 _worker.js 的目录。
2.3 部署完成后，进入项目设置，绑定自定义域名（例如 docker.yourdomain.com）。
2.4 注意：必须使用自定义域名，以防止 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" (冷启动)
   2.1 免费版 Hugging Face Space 在闲置 48 小时后会进入休眠状态。
   2.1.1 现象：第一次 docker pull 可能会卡住或超时。
   2.1.2 解决：这是正常现象，HF 正在后台唤醒容器（Building/Starting）。等待约 1 分钟后再次重试即可。
3. 为什么需要 Docker Hub 账号？

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