部署 Harbor 作为私有镜像仓库并对 GitHub Container Registry (GHCR) 进行镜像加速

前言

Harbor 也是一个我从接触容器这个概念开始，就一直在自己的项目中常驻的基础设施。
趁着这次重构记录一下整个部署和配置的流程，同时也试用一下它自带的镜像加速功能。

方案概述

安装 Docker 环境
安装 Harbor
1. 下载安装包
2. 配置 Harbor
3. 安装 Harbor
4. 配置 Caddy 反代
配置镜像加速功能
1. 创建对应提供者的仓库
2. 创建项目并设置为镜像代理
测试推送和拉取镜像
1. 构建镜像并推送镜像到 Harbor
2. 测试拉取 Harbor 的镜像
3. 测试拉取加速过后的镜像
配置 Harbor 的镜像保存与清理策略

操作步骤

一、安装 Docker 环境

Harbor 官方虽然提供了安装脚本，但实际的启动是使用 docker compose 的。
因此在安装 Harbor 之前，一定要提前安装好 Docker 和 Docker Compose。
你可以直接复制下面的、适配 Ubuntu/Debian 环境的命令来安装：

sudo apt-get update -y
sudo apt-get install ca-certificates curl gnupg lsb-release -y
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update -y
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y
docker -v

相关文章：Ubuntu 20.04 从官方源安装最新的 Docker

二、安装 Harbor

1、下载安装包

Harbor 官方提供了离线版和在线版安装包：Releases
我使用的是境外的服务器，网络情况较好，因此选择在线版进行安装：

# 目录为 /opt/harbor
mkdir -vp /opt/harbor
cd /opt/harbor

# 截止 2026/04/20 最新的版本是 v2.15.0
wget https://github.com/goharbor/harbor/releases/download/v2.15.0/harbor-online-installer-v2.15.0.tgz
tar -zxvf harbor-online-installer-v2.15.0.tgz -C /opt/harbor --strip-components=1

# 清理安装包
rm -vf harbor-online-installer-v2.15.0.tgz

2、配置 Harbor

在正式安装之前，我们需要先修改下配置文件，填入我们的域名、用户密码等信息：

cp /opt/harbor/harbor.yml.tmpl /opt/harbor/harbor.yml
nano /opt/harbor/harbor.yml

# 配置你的域名
hostname: harbor.example.com

# 修改 http 端口为 8080 防止与 Caddy 冲突
http:
  port: 8080

# 注释 https 相关配置来禁用 HTTPS
# https:
  # port: 443
  # certificate: /your/certificate/path
  # private_key: /your/private/key/path

# 你实际反代后的地址，一定要填写
# （不填的话默认会使用 http://hostname:8080 来进行 login 等操作）
external_url: https://harbor.example.com

# Harbor 管理员密码
harbor_admin_password: your_admin_password

# 配置数据库
database:
  password: harbor_database_password

# 数据持久化目录
data_volume: /opt/harbor/data

确认没问题后，保存并退出。

3、安装 Harbor

依然是在 /opt/harbor 目录下执行安装脚本：

./install.sh

看到这样的输出就说明安装成功了：
Harbor 安装成功

4、配置 `Caddy` 反代

在 /etc/caddy/Caddyfile 中添加以下配置：

nano /etc/caddy/Caddyfile

harbor.example.com {
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

保存后，重新加载 Caddy 配置：

sudo systemctl reload caddy

此时你就可以通过 https://harbor.example.com 访问 Harbor 了：
Harbor 登录界面

三、配置镜像加速功能

Harbor 自带了镜像加速功能，这也是我使用了 5 年来第一次知道…

1、创建对应提供者的仓库

只需要在 系统管理 > 仓库管理 中选择 + 新建目标，就能自由选择想要加速的镜像源了：

我选择创建一个提供者为 GitHub Container Registry 的仓库：
GHCR

2、创建项目并设置为镜像代理

还要去菜单最上方的 项目 中选择 + 新建项目，创建一个项目：

稍等片刻完成后，你就能在 项目 中看到刚刚创建的项目了：
GHCR-cache

四、测试推送和拉取镜像

全程的操作都是在另一台服务器上进行的。

1、构建镜像并推送镜像到 `Harbor`

首先拉取下 hello-world 镜像并改名为 hello-harbor：

docker pull hello-world
docker tag hello-world harbor.example.com/library/hello-world:latest
docker images

然后推送镜像到 Harbor：

docker push harbor.example.com/library/hello-harbor:latest

报错了：

The push refers to repository [harbor.example.com/library/hello-world] 4f55086f7dd0: Unavailable push access denied, repository does not exist or may require authorization: authorization failed: no basic auth credentials

诶，library 仓库不是公开的吗？并且官方给的提示也是 docker push 啊：
官方提示

这里就引出了概念：Harbor 的仓库所谓的公开只是针对拉取的，如果要推送依然需要进行登录！
用管理员账户 docker login harbor.example.com 登录一下：

再次尝试推送镜像：

docker push harbor.example.com/library/hello-world:latest

无视多架构支持相关的错误：

i Info → Not all multiplatform-content is present and only the available single-platform image was pushed

成功推送镜像后，你就能在 Harbor 中看到刚刚推送的镜像了：
推送成功

2、测试拉取 `Harbor` 的镜像

删一下本地的镜像并登出：

docker rmi harbor.example.com/library/hello-world:latest
docker logout harbor.example.com

然后拉取镜像：

docker pull harbor.example.com/library/hello-world:latest
docker images

如果看到拉取成功，说明 Harbor 本身的镜像拉取功能是正常的。

3、测试拉取加速过后的镜像

由于我们设置的镜像加速项目是私有的（如果是放在公网上，强烈建议设置私有防止被滥用），因此一样需要先登录：

docker login harbor.example.com

否则会报错：

Error response from daemon: failed to resolve reference “harbor.example.com/ghcr-cache/jonashackt/hello-world:latest”: pull access denied, repository does not exist or may require authorization: authorization failed: no basic auth credentials

拉取加速镜像时，需要修改原有的镜像地址：在你的域名和想要拉取的镜像名称中间，加上你刚才创建的代理项目名称。
例如原镜像为 ghcr.io/jonashackt/hello-world:latest，替换后的命令如下：

docker pull harbor.example.com/ghcr-cache/jonashackt/hello-world:latest
docker images

此时再去 Harbor 控制台的 ghcr-cache 项目里看，就会发现这个镜像已经被缓存到我们的服务器上了！测试没有问题，一切正常。
至此，所有基础功能就都测试通过了。

五、配置 Harbor 的镜像保存与清理策略

我的云服务只有 35GB 的硬盘空间，因此我将设置非常激进的清理策略。
核心指标为：

镜像代理服务只保留最近拉取的 1 个镜像版本（每小时定时执行一次）
Harbor 私有仓库保留最近 3 个镜像版本（每小时定时执行一次）
被上面 2 个定时任务标记为需要清理的镜像，每小时清理一次

这步一定不要忘记，如果不配置的话，虽然镜像会被标记为删除，但实际依然占着硬盘空间。

先在对应的项目中分别设置（标记删除的）策略：
镜像代理服务
私有仓库

然后在 系统管理 > 清理任务 中设置实际的删除任务，允许回收无 tag 的 artifacts 一定要勾选！

到这里就全部配置完成了。

结束。