自建 Docker Hub 加速镜像（Nginx 反向代理方案）

#反代docker hub镜像源
server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /etc/nginx/ssl/your.domain.com.crt;
    ssl_certificate_key /etc/nginx/ssl/your.domain.com.key;

    ssl_session_timeout 24h;
    ssl_protocols TLSv1.2 TLSv1.3;

    # /v2/ → https://registry-1.docker.io
    location /v2/ {
        proxy_pass https://registry-1.docker.io;  # Docker Hub 的官方镜像仓库
        proxy_set_header Host registry-1.docker.io;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 关闭缓存
        proxy_buffering off;

        # 转发认证相关的头部
        proxy_set_header Authorization $http_authorization;
        proxy_pass_header  Authorization;

        # 重写 www-authenticate 头为你的反代地址
        proxy_hide_header www-authenticate;
        add_header www-authenticate 'Bearer realm="https://your.domain.com/token",service="registry.docker.io"' always;
        # always 参数确保该头部在返回 401 错误时无论什么情况下都会被添加。

        # 对 upstream 状态码检查，实现 error_page 错误重定向
        proxy_intercept_errors on;
        # error_page 指令默认只检查了第一次后端返回的状态码，开启后可以跟随多次重定向。
        recursive_error_pages on;
        # 根据状态码执行对应操作，以下为301、302、307状态码都会触发
        error_page 301 302 307 = @handle_redirect;

    }
    # 处理 Docker OAuth2 Token 认证请求
    # 把返回的 `WWW-Authenticate` 头改写为你的入口地址，保证客户端能在你这儿拿到 token。
    # /token → https://auth.docker.io
    location /token {
        resolver 1.1.1.1 valid=600s;
        proxy_pass https://auth.docker.io;  # Docker 认证服务器

        # 设置请求头，确保转发正确
        proxy_set_header Host auth.docker.io;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 传递 Authorization 头信息，获取 Token
        proxy_set_header Authorization $http_authorization;
        proxy_pass_header Authorization;

        # 禁用缓存
        proxy_buffering off;
    }
    location @handle_redirect {
        resolver 1.1.1.1;
        set $saved_redirect_location '$upstream_http_location';
        proxy_pass $saved_redirect_location;
    }
}

保存退出（Ctrl+O → 回车 → Ctrl+X）。

重载加载 Nginx 配置

sudo nginx -s reload

如果没有报错说明配置生效。

配置 Docker 镜像源

你现在有一个新的私有镜像仓库：

https://your.domain.com

接下来让 Docker 走这个仓库，而不是默认的 https://registry-1.docker.io。
下面我分几种常见情况讲清楚该怎么做👇

一、临时使用（单次命令）

如果只是想临时从该仓库拉取镜像，例如：

docker pull your.domain.com/ubuntu:latest

或者运行：

docker run -it your.domain.com/ubuntu bash

这种方式不需要修改配置文件。
但要注意：

镜像名前必须加上完整域名（域名）

若仓库未使用有效证书（自签名或内部 CA），还需要配置 Docker 信任。

二、长期替换默认仓库（推荐）

如果你想让 Docker 默认就从新的仓库拉取镜像，可以通过以下两种方式配置：

方式 1️⃣：修改 /etc/docker/daemon.json

编辑（或新建）文件：

sudo nano /etc/docker/daemon.json

加入以下内容（若已有其他字段请合并）：

{
  "registry-mirrors": ["https://your.domain.com"]
}

然后执行：

sudo systemctl daemon-reload
sudo systemctl restart docker

验证：

docker info | grep -A1 "Registry Mirrors"

输出中应出现：

Registry Mirrors:
 https://your.domain.com/

✅ 说明生效。

方式 2️⃣：使用自定义私有仓库（带认证）

如果你的仓库需要登录（例如 Harbor、Nexus 等），可登录：

docker login your.domain.com

然后输入用户名密码。
成功后会在 ~/.docker/config.json 中保存凭据。

注意！如果利用反代服务器登录 docker hub 仓库，反代服务器是可以获取到你的账号密码的，所以请谨慎使用他人搭建的服务登录！
如果没有拉取自己的私有仓库的镜像的需求，保持匿名拉取相对会安全一些。

三、如果是自签名证书（HTTPS）

若你的 https://your.domain.com 使用自签名证书（非 Let’s Encrypt 等正规证书），Docker 会拒绝连接。

解决方法：

创建目录：

sudo mkdir -p /etc/docker/certs.d/your.domain.com

将证书（例如 ca.crt）复制进去：

sudo cp ca.crt /etc/docker/certs.d/your.domain.com/

重启 Docker：
```
sudo systemctl restart docker
```

如果你没有证书，可以临时在 daemon.json 加上：
{ "insecure-registries": ["your.domain.com"] }
但⚠️这只适合内网或测试环境，生产环境请务必使用 HTTPS 证书。

四、验证是否成功

用的临时方案则执行：

docker pull your.domain.com/library/hello-world

用的替换默认仓库方案则执行：

docker pull hello-world

拉取成功，你的加速镜像已经生效！

五、安全配置

目前你的 Nginx Docker Hub 镜像是搭建成功了，但默认是公开可访问的，
任何人只要知道你的域名，都能用你的服务器中转 Docker Hub。
如果被人滥用，会导致：

你的服务器带宽被占满；
Docker Hub 对你服务器的出口 IP 限速；
甚至触发风控或账单暴涨。

所以确实需要加一层访问控制，让只有你（或你的机器）能用。很多教程都忽略了这一点。

IP 白名单限制（推荐小团队/个人）

最简单的办法就是IP 白名单限制，在你的反代配置/etc/nginx/conf.d/dockerhub.conf里，只允许特定 IP 访问 /v2/ 和 /token。

示例：

location /v2/ {
    allow 你的本地公网IP;      # 比如 allow 123.45.67.89;
    allow 你的公司出口IP;      # 可写多个 allow
    deny all;                # 其他一律拒绝
    ...
}
location /token {
    allow 你的本地公网IP;
    allow 你的公司出口IP;
    deny all;
    ...
}

✅ 优点：简单高效，无需额外配置
⚠️ 缺点：如果你经常换网络（如笔电或多地服务器），需要手动更新 IP。

修改后重新加载 nginx 配置

nginx -s reload

好了，完事。

自建 Docker Hub 加速镜像（Nginx 反向代理方案）

前言