# 自建 Docker Hub 加速镜像：Nginx 反向代理解决方案

> 详细介绍利用Nginx反向代理自建Docker Hub加速镜像的完整方案，解决国内Docker镜像拉取困难的问题。本文涵盖环境准备、Nginx配置、SSL证书设置、缓存优化以及生产环境部署的最佳实践，帮助开发者构建稳定可靠的私有镜像加速服务

- Canonical: https://www.zeroxin.xin/2025/11/09/self-hosted-docker-hub-mirror/
- Published: 2025-11-09T00:00:00+08:00
- Updated: 2026-06-18T17:19:20+08:00

- Tags: Linux, Docker, 网络技术, Nginx, VPS

## 前言

随着 Docker Hub 官方源被封锁，国内的镜像源也纷纷下架，现在国内企业和个人服务拉取镜像越来越困难。阿里云、腾讯云等镜像源已经只允许自家服务器使用，其他第三方源也存在稳定性和安全性问题。

所以，自建 Docker Hub 加速镜像就显得很有必要。最常见的做法是：用 Nginx 反向代理 Docker Hub 官方仓库，搭一个属于你自己的"加速入口"。

## 准备环境

> 以下是我的环境配置，主打便宜好用，可根据自身情况调整。

- **系统**：Debian / Ubuntu
- **域名**（可选）：NameSilo 免备案、价格便宜(`.xyz`等冷门域名)。没有域名也可以使用自签证书启用 HTTPS

## 安装 Nginx

```bash
sudo apt update
sudo apt install nginx
```

## 开放端口

放行 HTTPS 端口（根据自己服务器情况开放端口，以 ufw 为例）：

```bash
sudo ufw allow 443
```

## 配置 Nginx 反代 Docker Hub

创建新配置文件：

```bash
touch /etc/nginx/conf.d/dockerhub.conf
```

编辑配置文件：

```bash
nano /etc/nginx/conf.d/dockerhub.conf
```

将以下内容粘贴进去，把域名和证书路径改为你自己的，本文示例域名`your.domain.com`。如果还没证书，可以先用 [acme.sh](https://github.com/acmesh-official/acmesh.sh) 申请自动证书。

> 如果用的 NameSilo 的域名，可以参考 acme.sh 的 DNS API 自动申请SSL证书：[https://github.com/acmesh-official/acme.sh/wiki/dnsapi#35-use-namesilocom-api](https://github.com/acmesh-official/acme.sh/wiki/dnsapi#35-use-namesilocom-api)

```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 配置

```bash
sudo nginx -s reload
```

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

## 配置 Docker 镜像源

你现在有一个新的私有镜像仓库：`https://your.domain.com`

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

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

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

```bash
docker pull your.domain.com/ubuntu:latest
```

或者运行：

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

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

- 镜像名前必须加上完整域名（`域名`）
- 若仓库未使用有效证书（自签名或内部 CA），还需要配置 Docker 信任

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

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

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

编辑（或新建）文件：

```bash
sudo nano /etc/docker/daemon.json
```

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

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

然后执行：

```bash
sudo systemctl daemon-reload
sudo systemctl restart docker
```

验证：

```bash
docker info | grep -A1 "Registry Mirrors"
```

输出中应出现：

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

✅ 说明生效。

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

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

```bash
docker login your.domain.com
```

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

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

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

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

解决方法：

1. 创建目录：
   ```bash
   sudo mkdir -p /etc/docker/certs.d/your.domain.com
   ```

2. 将证书（例如 `ca.crt`）复制进去：
   ```bash
   sudo cp ca.crt /etc/docker/certs.d/your.domain.com/
   ```

3. 重启 Docker：
   ```bash
   sudo systemctl restart docker
   ```

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

## 四、验证是否成功

用的临时方案则执行：

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

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

```bash
docker pull hello-world
```

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

## 五、安全配置

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

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

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

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

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

示例：

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

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

修改后重新加载 nginx 配置

```bash
nginx -s reload
```

好了，完事。

---

## 总结

通过本文的详细步骤，您可以成功搭建一个属于自己的 Docker Hub 加速镜像服务。这种方案相比使用公共镜像源有以下优势：

1. **稳定性**：不受公共镜像源服务质量影响
2. **安全性**：可以配置 IP 白名单，限制访问范围
3. **可控性**：完全掌控服务状态和配置
4. **性能优化**：选择距离用户更近的服务器节点

虽然搭建过程相对复杂，但一旦配置完成，就能为您的 Docker 镜像拉取提供稳定可靠的服务保障。

---

*本文转载自[技术好学屋](https://www.itblogcn.com/)，原文地址：[自建 Docker Hub 加速镜像（Nginx 反向代理方案）](https://www.itblogcn.com/article/2702.html)*