【Docker】Harbor 代理缓存（Pull-Through Cache）配置与使用指南

背景

在内网环境中，Docker 主机无法直接访问 Docker Hub，或希望加速镜像拉取、减少外网带宽消耗时，可以将 Harbor 配置为代理缓存仓库。首次拉取镜像时，Harbor 自动从上游 Docker Hub 获取并缓存到本地，后续拉取直接从本地获取。

架构

复制代码

Docker Client
    │
    ▼
nginx-proxy (443, 正式证书, harbor.xxx.com)
    │
    ▼
Harbor (8443, 自签名证书)
    │
    ▼ (缓存未命中时)
Docker Hub (hub.docker.com)

一、Harbor 端配置

1.1 添加上游 Registry

在 Harbor 管理界面或通过 API 添加 Docker Hub 作为上游仓库：

界面操作 ：系统管理 → Registry → 新建 → 类型选 Docker Hub

API 操作：

bash 复制代码

curl -sk -u admin:Harbor12345 -X POST \
  'https://harbor.lilibaai.com/api/v2.0/registries' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "dockerhub",
    "url": "https://hub.docker.com",
    "type": "docker-hub",
    "credential": {
      "type": "basic",
      "access_key": "",
      "access_secret": ""
    }
  }'

如果 Docker Hub 有速率限制问题，填写 Docker Hub 账号的 access_key/access_secret。

1.2 创建代理缓存项目

创建一个绑定上游 Registry 的项目，必须在创建时就绑定，事后无法修改：

界面操作 ：项目 → 新建项目 → 名称 dockerhub → 勾选「镜像代理」→ 选择上一步添加的 Docker Hub registry

API 操作：

bash 复制代码

# 先查询 registry ID
curl -sk -u admin:Harbor12345 \
  'https://harbor.lilibaai.com/api/v2.0/registries'

# 创建项目，registry_id 填上一步返回的 ID
curl -sk -u admin:Harbor12345 -X POST \
  'https://harbor.lilibaai.com/api/v2.0/projects' \
  -H 'Content-Type: application/json' \
  -d '{
    "project_name": "dockerhub",
    "public": true,
    "registry_id": 1,
    "metadata": { "public": "true" },
    "storage_limit": -1
  }'

1.3 验证项目配置

bash 复制代码

curl -sk -u admin:Harbor12345 \
  'https://harbor.lilibaai.com/api/v2.0/projects/dockerhub' | python3 -c "
import json, sys
d = json.load(sys.stdin)
print(f'Project: {d[\"name\"]}')
print(f'Registry ID: {d.get(\"registry_id\")}')
print(f'Public: {d.get(\"metadata\", {}).get(\"public\")}')
"

预期输出：

复制代码

Project: dockerhub
Registry ID: 1
Public: true

二、Docker 客户端配置

2.1 登录 Harbor

bash 复制代码

docker login harbor.lilibaai.com -u admin -p <密码>

代理缓存项目设为 public 时，匿名用户也能拉取，但建议登录以避免速率限制。

2.2 配置 insecure-registries（仅 Harbor 使用自签名证书时需要）

如果 Harbor 前面有 nginx 反代且配置了正式证书（如本环境），不需要 此配置。

如果直接访问 Harbor 的 8443 自签名端口，需要配置：

bash 复制代码

# /etc/docker/daemon.json
{
  "insecure-registries": ["192.168.1.15:8443"]
}

bash 复制代码

systemctl restart docker

三、使用方法

3.1 镜像名称转换规则

将 Docker Hub 镜像名替换为 Harbor 代理缓存路径：

复制代码

原始名称                              →  Harbor 代理缓存名称
─────────────────────────────────────────────────────────────────
nginx:stable                          →  harbor.lilibaai.com/dockerhub/library/nginx:stable
redis:7-alpine                        →  harbor.lilibaai.com/dockerhub/library/redis:7-alpine
maven:3.9.11-eclipse-temurin-21       →  harbor.lilibaai.com/dockerhub/library/maven:3.9.11-eclipse-temurin-21
node:22-alpine                        →  harbor.lilibaai.com/dockerhub/library/node:22-alpine

library/ 是 Docker Hub 官方镜像的默认命名空间，不能省略。

3.2 拉取镜像

bash 复制代码

# 首次拉取：Harbor 缓存未命中，自动从 Docker Hub 代理拉取
docker pull harbor.lilibaai.com/dockerhub/library/redis:7-alpine

# 后续拉取：直接从 Harbor 本地缓存获取，速度更快
docker pull harbor.lilibaai.com/dockerhub/library/redis:7-alpine

3.3 在 Dockerfile 中使用

dockerfile 复制代码

# 之前
FROM maven:3.9.11-eclipse-temurin-21 AS build

# 之后
FROM harbor.lilibaai.com/dockerhub/library/maven:3.9.11-eclipse-temurin-21 AS build

3.4 在 docker-compose.yml 中使用

yaml 复制代码

services:
  app:
    image: harbor.lilibaai.com/dockerhub/library/node:22-alpine

3.5 镜像 tag/retag 推送到 Harbor 普通项目

如果希望将代理缓存的镜像推送到自己的项目（如 develop）方便管理：

bash 复制代码

# 拉取代理缓存镜像
docker pull harbor.lilibaai.com/dockerhub/library/node:22-alpine

# retag 到自己的项目
docker tag harbor.lilibaai.com/dockerhub/library/node:22-alpine \
           harbor.lilibaai.com/develop/node:22-alpine

# 推送
docker push harbor.lilibaai.com/develop/node:22-alpine

四、验证缓存效果

4.1 查看已缓存的镜像

bash 复制代码

curl -sk -u admin:Harbor12345 \
  'https://harbor.lilibaai.com/api/v2.0/projects/dockerhub/repositories' | python3 -c "
import json, sys
for r in json.load(sys.stdin):
    print(f'{r[\"name\"]}  ({r[\"artifact_count\"]} artifacts)')
"

4.2 Harbor 管理界面查看

浏览器访问 https://harbor.lilibaai.com → 项目 → dockerhub，可以看到所有已缓存的镜像和 tag。

五、注意事项

代理缓存项目是只读的 ，不能直接 docker push 到该项目的 library/* 路径下
首次拉取会较慢（需要从 Docker Hub 下载），后续拉取走本地缓存
Docker Hub 速率限制：匿名用户 100 次/6 小时，建议配置 Docker Hub 账号凭证
缓存清理：Harbor 不会自动清理代理缓存，需在管理界面手动配置清理策略
项目必须创建时就绑定 Registry，创建后无法修改为代理缓存项目
nginx 反代的 client_max_body_size 需设为 0（不限制），否则推送大镜像会 413 错误

六、当前环境信息

项目	值
Harbor 版本	v2.14.0
Harbor 地址	`harbor.lilibaai.com`（443, nginx 反代, 正式证书）
Harbor 内部地址	`192.168.1.15:8443`（自签名证书）
代理缓存项目	`dockerhub`（public, 绑定 Docker Hub）
上游 Registry	Docker Hub（Registry ID: 1）
存储后端	MinIO（`192.168.1.7:9000`, bucket: `harbor-images`）