Harbor仓库从讲解到部署实战

Harbor 私有镜像仓库部署笔记

一、Harbor 简介

Harbor 是一个企业级开源容器镜像仓库，由 VMware 公司开发并开源。它在 Docker 官方 Registry 的基础上进行了二次封装，增加了 Web 管理界面、镜像复制、漏洞扫描、角色权限管理等企业级功能。

Harbor 的主要组件包括：

组件	功能
Proxy (nginx)	前端代理，分发 UI 访问和镜像上传/下载流量
UI (Portal)	Web 管理页面，提供前端界面和后端 API
Registry	镜像仓库，负责存储镜像文件
Adminserver	系统配置管理中心，附带存储用量检查
Jobservice	负责镜像复制等后台任务
Log	日志汇总组件

二、环境准备

2.1 硬件要求

根据 Harbor 官方文档，部署 Harbor 的硬件配置要求如下：

资源	最低配置	推荐配置
CPU	2 核	4 核
内存	4 GB	8 GB
磁盘	40 GB	160 GB

2.2 软件要求

Harbor 以 Docker 容器方式部署，因此目标主机需要安装以下软件：

软件	版本要求
Docker Engine	20.10.10-ce+ 或更高
Docker Compose	v1.18.0+ 或 v2 (docker-compose-plugin)
OpenSSL	最新版（用于生成证书）

2.3 网络端口

Harbor 需要开放以下端口：

端口	协议	用途
443	HTTPS	Harbor Portal 和 Core API
4443	HTTPS	Docker Content Trust 服务
80	HTTP	Harbor Portal 和 Core API

2.4 操作系统基础配置

注意：以下配置基于 CentOS/RHEL 系列 Linux 发行版，其他发行版请相应调整。

1. 修改主机名

bash 复制代码

hostnamectl hostname harbor

2. 配置静态 IP（以 ens160 网卡为例）

bash 复制代码

nmcli c m ens160 ipv4.method manual ipv4.address 192.168.10.20/24 ipv4.gateway 192.168.10.200 ipv4.dns "223.5.5.5 8.8.8.8" connection.autoconnect yes
nmcli c up ens160

3. 开启路由转发

bash 复制代码

echo 'net.ipv4.ip_forward = 1' >> /etc/sysctl.conf
sysctl -p

4. 配置主机映射

bash 复制代码

cat >> /etc/hosts <<EOF
192.168.10.20 hb.reg.com harbor
EOF

三、安装 Docker 和 Docker Compose

3.1 安装 Docker

添加 Docker 源

bash 复制代码

dnf install yum-utils -y
yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/rhel/docker-ce.repo

安装 Docker

bash 复制代码

dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

配置 Docker

bash 复制代码

cat > /etc/docker/daemon.json <<EOF
{
  "data-root": "/data/docker",
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "50"
  },
  "insecure-registries": ["https://hb.reg.com"],
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.imgdb.de"
  ]
}
EOF

注意：insecure-registries 中的地址需与后续 Harbor 配置的域名保持一致。如果使用自签名证书，也需要在此配置。

启动 Docker

bash 复制代码

systemctl enable --now docker

验证安装

bash 复制代码

docker info

3.2 安装 Docker Compose

下载 Docker Compose

bash 复制代码

wget https://github.com/docker/compose/releases/download/v2.35.1/docker-compose-linux-x86_64

安装并赋权

bash 复制代码

mv docker-compose-linux-x86_64 /usr/bin/docker-compose
chmod +x /usr/bin/docker-compose

验证安装

bash 复制代码

docker-compose --version

四、下载 Harbor 安装包

4.1 创建数据目录

bash 复制代码

mkdir -p /data
cd /data

4.2 下载离线安装包

Harbor 提供两种安装方式：

在线安装包 (harbor-online-installer)：安装时从 Docker Hub 拉取镜像
离线安装包 (harbor-offline-installer)：所有镜像已打包在安装包中

建议：在国内网络环境下，推荐使用离线安装包，避免镜像拉取失败或速度过慢的问题。

bash 复制代码

# 下载离线安装包（以 v2.13.2 为例）
wget https://github.com/goharbor/harbor/releases/download/v2.13.2/harbor-offline-installer-v2.13.2.tgz

4.3 解压安装包

bash 复制代码

tar -xzf harbor-offline-installer-v2.13.2.tgz
cd harbor/
ls
# 输出：common.sh harbor.v2.13.2.tar.gz harbor.yml.tmp1 install.sh LICENSE prepare

五、配置 HTTPS 证书

重要：在生产环境中始终使用 HTTPS。虽然 Harbor 可以在不启用安全性的情况下通过 HTTP 运行，但这仅适用于隔离的测试或开发环境。

5.1 创建证书目录

bash 复制代码

mkdir -p /data/cert
cd /data/harbor
mkdir ssl && cd ssl

5.2 生成 CA 证书

bash 复制代码

# 生成 CA 私钥
openssl genrsa -out ca.key 4096

# 生成 CA 证书
openssl req -x509 -new -nodes -sha512 -days 3650 \
  -subj "/C=CN/ST=Chongqing/L=Banan/O=Example/OU=Personal/CN=MyPersonal Root CA" \
  -key ca.key \
  -out ca.crt

5.3 生成服务器证书

bash 复制代码

# 1. 生成服务器私钥
openssl genrsa -out hb.reg.com.key 4096

# 2. 生成证书签名请求 (CSR)
openssl req -sha512 -new \
  -subj "/C=CN/ST=Chongqing/L=Banan/O=Example/OU=Personal/CN=hb.reg.com" \
  -key hb.reg.com.key \
  -out hb.reg.com.csr

5.4 创建 SAN 扩展文件

无论使用 FQDN 还是 IP 地址访问 Harbor，都需要创建此文件以满足 Subject Alternative Name (SAN) 和 x509 v3 扩展要求。

bash 复制代码

cat > v3.ext <<EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1=hb.reg.com
DNS.2=hb.reg
DNS.3=harbor
EOF

5.5 生成服务器证书

bash 复制代码

openssl x509 -req -sha512 -days 3650 \
  -extfile v3.ext \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -in hb.reg.com.csr \
  -out hb.reg.com.crt

5.6 部署证书

bash 复制代码

# 1. 复制证书到 Harbor 证书目录
cp hb.reg.com.crt /data/cert/
cp hb.reg.com.key /data/cert/

# 2. 转换证书格式供 Docker 使用
openssl x509 -inform PEM -in hb.reg.com.crt -out hb.reg.com.cert

# 3. 创建 Docker 证书目录并复制证书
mkdir -p /etc/docker/certs.d/hb.reg.com:443
cp hb.reg.com.cert /etc/docker/certs.d/hb.reg.com:443/
cp hb.reg.com.key /etc/docker/certs.d/hb.reg.com:443/
cp ca.crt /etc/docker/certs.d/hb.reg.com:443/

# 4. 重启 Docker
systemctl restart docker

简化方式：如果只是测试环境，也可以使用自签名证书一步到位：
bash 复制代码
openssl genrsa -out hb.reg.com.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
-subj "/C=CN/ST=Chongqing/L=Banan/O=Example/OU=Personal/CN=hb.reg.com" \
-key hb.reg.com.key \
-out hb.reg.com.crt

六、配置 Harbor

6.1 复制配置文件

bash 复制代码

cp harbor.yml.tmp1 harbor.yml

6.2 编辑配置文件

bash 复制代码

vim harbor.yml

需要修改的关键配置项：

yaml 复制代码

# 主机名（必填，不能使用 localhost 或 127.0.0.1）
hostname: hb.reg.com

# HTTP 配置
http:
  port: 80

# HTTPS 配置
https:
  port: 443
  certificate: /data/cert/hb.reg.com.cert
  private_key: /data/cert/hb.reg.com.key

# 管理员初始密码（默认 Harbor12345）
# harbor_admin_password: Harbor12345

# 数据库密码（默认随机生成）
# database:
#   password: root123

6.3 加载 Harbor 镜像

bash 复制代码

docker load -i harbor.v2.13.2.tar.gz

查看已加载的镜像：

bash 复制代码

docker images | grep harbor

七、安装 Harbor

7.1 检查安装环境

bash 复制代码

./prepare

prepare 脚本会：

生成各组件的配置文件
创建必要的密钥和证书
生成 docker-compose.yml 文件

7.2 执行安装

bash 复制代码

./install.sh

安装过程会依次执行：

检查 Docker 是否安装
检查 Docker Compose 是否安装
加载 Harbor 镜像
准备环境
生成 Harbor 配置
启动所有容器

安装成功后，会看到类似输出：

复制代码

✔ ----Harbor has been installed and started successfully.

7.3 查看运行状态

bash 复制代码

docker-compose ps

正常应该看到以下容器均处于 Up 状态：

harbor-core
harbor-db
harbor-jobservice
harbor-log
harbor-portal
nginx (proxy)
redis
registry
registryctl

八、配置 Harbor 系统服务

为了方便管理，将 Harbor 配置为 systemd 服务。

8.1 创建服务文件

bash 复制代码

vim /usr/lib/systemd/system/harbor.service

内容如下：

ini 复制代码

[Unit]
Description=Harbor
After=docker.service systemd-networkd.service systemd-resolved.service
Requires=docker.service
Documentation=http://github.com/vmware/harbor

[Service]
Type=simple
Restart=on-failure
RestartSec=5
ExecStart=/usr/bin/docker-compose --file /data/harbor/docker-compose.yml up
ExecStop=/usr/bin/docker-compose --file /data/harbor/docker-compose.yml down

[Install]
WantedBy=multi-user.target

8.2 启动并设置开机自启

bash 复制代码

systemctl daemon-reload
systemctl start harbor
systemctl enable harbor

8.3 查看服务状态

bash 复制代码

systemctl status harbor

九、访问 Harbor

9.1 配置客户端 hosts

在访问 Harbor 的客户端机器上，配置 hosts 映射：

复制代码

192.168.10.20 hb.reg.com

9.2 Web 登录

打开浏览器访问 https://hb.reg.com

用户名：admin
密码：Harbor12345（默认密码，如已修改请使用新密码）

十、测试 Harbor 仓库

10.1 拉取测试镜像

bash 复制代码

docker pull nginx:1.28.0
docker pull mysql:8.4.4

10.2 镜像打标签

格式：仓库地址/项目名称/镜像名称:标签

bash 复制代码

docker tag nginx:1.28.0 hb.reg.com/library/nginx:1.28.0
docker tag mysql:8.4.4 hb.reg.com/library/mysql:8.4.4

10.3 登录 Harbor

bash 复制代码

docker login hb.reg.com
# 用户名: admin
# 密码: Harbor12345

10.4 推送镜像

bash 复制代码

docker push hb.reg.com/library/nginx:1.28.0
docker push hb.reg.com/library/mysql:8.4.4

10.5 拉取镜像验证

删除本地镜像后重新拉取：

bash 复制代码

docker rmi hb.reg.com/library/nginx:1.28.0
docker pull hb.reg.com/library/nginx:1.28.0

10.6 通过 API 查看镜像列表

bash 复制代码

curl -k -u 'admin:Harbor12345' 'https://hb.reg.com/api/v2.0/projects/library/repositories'

十一、常见运维操作

11.1 停止 Harbor

bash 复制代码

systemctl stop harbor
# 或
docker-compose down

11.2 启动 Harbor

bash 复制代码

systemctl start harbor
# 或
docker-compose up -d

11.3 查看日志

bash 复制代码

docker-compose logs -f
# 查看特定服务日志
docker-compose logs -f harbor-core

11.4 更新 Harbor 配置

修改 harbor.yml 后，需要重新执行：

bash 复制代码

./prepare
docker-compose down
docker-compose up -d

十二、补充：高可用部署（参考）

对于生产环境，Harbor 支持通过 Helm 在 Kubernetes 集群上部署以实现高可用。

高可用部署的先决条件：

Kubernetes 集群 1.10+
Helm 2.8.0+
高可用 Ingress Controller
高可用 PostgreSQL 9.6+
高可用 Redis（注意：Harbor 目前不支持 Redis Cluster 或基于 TLS 的连接）
支持跨节点读写的 PVC 或外部对象存储

安装命令：

bash 复制代码

helm repo add harbor https://helm.goharbor.io
helm fetch harbor/harbor --untar
# 配置 values.yaml 后执行安装
helm install harbor harbor/harbor

详细配置请参考 Harbor 官方文档。

附录：常见问题

Q1: 推送镜像时提示 `denied: requested access to the resource is denied`

原因：未登录或项目不存在。

解决：执行 docker login hb.reg.com，或在 Harbor Web 界面中创建对应的项目。

Q2: 推送镜像时提示 `x509: certificate signed by unknown authority`

原因：Docker 不信任自签名证书。

解决：

在 /etc/docker/daemon.json 中添加 "insecure-registries": ["https://hb.reg.com"]
或将证书复制到 /etc/docker/certs.d/hb.reg.com:443/ 目录

Q3: Harbor 服务启动失败

解决：

检查端口是否被占用：netstat -tlnp | grep -E '80|443'
查看容器日志：docker-compose logs
检查配置文件语法是否正确

Q4: 忘记 admin 密码

解决：进入 Harbor 数据库容器重置密码：

bash 复制代码

docker exec -it harbor-db psql -U postgres -d registry
UPDATE harbor_user SET password='' WHERE username='admin';

Harbor仓库从讲解到部署实战

Harbor 私有镜像仓库部署笔记

一、Harbor 简介

二、环境准备

2.1 硬件要求

2.2 软件要求

2.3 网络端口

2.4 操作系统基础配置

三、安装 Docker 和 Docker Compose

3.1 安装 Docker

3.2 安装 Docker Compose

四、下载 Harbor 安装包

4.1 创建数据目录

4.2 下载离线安装包

4.3 解压安装包

五、配置 HTTPS 证书

5.1 创建证书目录

5.2 生成 CA 证书

5.3 生成服务器证书

5.4 创建 SAN 扩展文件

5.5 生成服务器证书

5.6 部署证书

六、配置 Harbor

6.1 复制配置文件

6.2 编辑配置文件

6.3 加载 Harbor 镜像

七、安装 Harbor

7.1 检查安装环境

7.2 执行安装

7.3 查看运行状态

八、配置 Harbor 系统服务

8.1 创建服务文件

8.2 启动并设置开机自启

8.3 查看服务状态

九、访问 Harbor

9.1 配置客户端 hosts

9.2 Web 登录

十、测试 Harbor 仓库

10.1 拉取测试镜像

10.2 镜像打标签

10.3 登录 Harbor

10.4 推送镜像

10.5 拉取镜像验证

10.6 通过 API 查看镜像列表

十一、常见运维操作

11.1 停止 Harbor

11.2 启动 Harbor

11.3 查看日志

11.4 更新 Harbor 配置

十二、补充：高可用部署（参考）

附录：常见问题

Q1: 推送镜像时提示 denied: requested access to the resource is denied

Q2: 推送镜像时提示 x509: certificate signed by unknown authority

Q3: Harbor 服务启动失败

Q4: 忘记 admin 密码

Q1: 推送镜像时提示 `denied: requested access to the resource is denied`

Q2: 推送镜像时提示 `x509: certificate signed by unknown authority`