Harbor v2.5.3-- 搭建Docker私有仓库

官方参考文档：https://goharbor.io/docs/2.5.0/install-config/

Harbor -- 搭建Docker私有仓库（2022-08-10 官方目前发行到当前使用就是该版本2.5.3版本请悉知！当前使用就是该版本）

本文档Harbor 安装部署内容如下：

1. Harbor 安装先决条件。
2. 下载 Harbour 安装程序
3. 配置对 Harbor 的 HTTPS 访问
4. 开始部署或重新配置 Harbor
5. 验证 HTTPS 连接(默认设置)验证HTTP连接(根据需要设置)
6. 其他问题处理6.1 重置密码6.2 数据备份6.3 版本更新

如果安装失败，请参阅 Harbor 安装故障排除。

1、Harbor 安装先决条件

硬件

下表列出了部署 Harbor 的最低和推荐硬件配置。

软件

下表列出了必须在目标主机上安装的软件版本。

网络端口

Harbor 要求在目标主机上打开以下端口。

2、下载 Harbor 安装程序

您可以从 官方发布页面下载 Harbor 安装程序。下载在线安装程序或离线安装程序。

• 在线安装程序：在线安装程序从 Docker 中心下载 Harbor 镜像。因此，安装程序的尺寸非常小。
• 离线安装程序：如果正在部署 Harbor 的主机没有连接到 Internet，请使用离线安装程序。离线安装程序包含预先构建的映像，因此它比在线安装程序大。

在线和离线安装程序的安装过程几乎相同。

tar解压安装包：

• 在线安装程序：

  tar xzvf harbor-online-installer-*.tgz

• 离线安装程序：

  tar xzvf harbor-offline-installer-*.tgz

更改存放路径到

mkdir -p /data && mv harbor /data

3、配置对 Harbor 的 HTTPS 访问

默认情况下，Harbor 不附带证书。在生产环境中，始终使用 HTTPS。如果您启用 Content Trust with Notary 以正确签署所有图像，则必须使用 HTTPS。

下面的过程假设您的 Harbor 注册中心的主机名是harbor.l-t.top，并且它的 DNS 记录指向您正在运行 Harbor 的主机。

生成证书颁发机构证书

在生产环境中，您应该从 CA 获得证书。在测试或开发环境中，您可以生成自己的 CA。要生成 CA 证书，请运行以下命令。

1.生成 CA 证书私钥。

openssl genrsa -out ca.key 4096

2.生成 CA 证书。

调整-subj选项中的值以反映您的组织。如果您使用 FQDN 连接您的 Harbor 主机，则必须将其指定为公用名 ( CN) 属性。

openssl req -x509 -new -nodes -sha512 -days 3650 \
 -subj "/C=CN/ST=YunNan/L=KunMing/O=example/OU=Personal/CN=harbor.l-t.top" \
 -key ca.key \
 -out ca.crt

注释：

通用名称：harbor.l-t.top

部门(OU)：Personal

省 份 (S)：YunNan （云南）

城 市 (L)：KunMing （昆明）

国 家 (C)：CN ( 国际标准组织ISO国码2位国家代号。中国请填CN )

生成服务器证书

证书通常包含一个.crt文件和一个.key文件，例如，harbor.l-t.top.crt和harbor.l-t.top.key.

1. 生成私钥。

   openssl genrsa -out harbor.l-t.top.key 4096

2. 生成证书签名请求 (CSR)。调整-subj选项中的值以反映您的组织。如果您使用 FQDN 连接您的 Harbor 主机，则必须将其指定为公用名 ( CN) 属性并在密钥和 CSR 文件名中使用它。

   openssl req -sha512 -new \
       -subj "/C=CN/ST=YunNan/L=KunMing/O=example/OU=Personal/CN=harbor.l-t.top" \
       -key harbor.l-t.top.key \
       -out harbor.l-t.top.csr

3. 生成 x509 v3 扩展文件。无论您是使用 FQDN 还是 IP 地址来连接到您的 Harbor 主机，您都必须创建此文件，以便您可以为您的 Harbor 主机生成符合主题备用名称 (SAN) 和 x509 v3 的证书扩展要求。替换DNS条目以反映您的域。

   cat > v3.ext <<-EOF
   authorityKeyIdentifier=keyid,issuer
   basicConstraints=CA:FALSE
   keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
   extendedKeyUsage = serverAuth
   subjectAltName = @alt_names
   
   [alt_names]
   DNS.1=harbor.l-t.top
   DNS.2=l-t.top
   DNS.3=hostname
   EOF

4. 使用该v3.ext文件为您的 Harbor 主机生成证书。将harbor.l-t.topCRS 和 CRT 文件名中的 替换为 Harbor 主机名。

   openssl x509 -req -sha512 -days 3650 \
       -extfile v3.ext \
       -CA ca.crt -CAkey ca.key -CAcreateserial \
       -in harbor.l-t.top.csr \
       -out harbor.l-t.top.crt

修改Harbor配置文件

1、修改配置harbor.yml，将服务器证书和密钥复制到 Harbor 主机上的/data/harbor/cert文件夹中。

cp harbor.yml.tmpl harbor.yml
cp harbor.l-t.top.crt /data/harbor/cert
cp harbor.l-t.top.key /data/harbor/cert

2、修改harbor配置文件：（仅列出修改部分内容）

vi harbor.yml

#hostname不可使用localhost和127.0.0.1，请使用IP地址或者域名
hostname: harbor.l-t.top
http:
  port: 80
https:
#https协议需要证书，并且需要指明证书存放位置,harbor默认使用SSL加密认证
  port: 443
  certificate: /data/harbor/cert/harbor.l-t.top.crt
  private_key: /data/harbor/cert/harbor.l-t.top.key
#harbor网页段默认登录帐号admin  默认密码：Harbor123，密码请使用随机生成密码）
harbor_admin_password: uSzzRki(OQhe5qa8oF
database:
#（数据库密码请使用随机生成密码，默认root123）
password: pR1f_wphZ*1FGStm3z
  max_idle_conns: 100
  max_open_conns: 900
#指定数据存放位置
data_volume: /data/harbor/data
log:
#定义日志记录级别，这里使用默认级别
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M
    #定义日志存放位置
    location: /data/harbor/logs/

使用docker login 命令登录Harbor的证书设置

1. 在客户端服务器上创建一个文件夹路径为 /etc/docker/certs.d/harbor.l-t.top 的层级目录，命令如下：

   mkdir –p /etc/docker/certs.d/harbor.l-t.top

2. 拷贝部署 Harbor 的服务器上证书文件ca.crt、harbor.l-t.top.crt和harbor.l-t.top.key到客户端服务器刚创建文件夹中。

   cp harbor.l-t.top.cert /etc/docker/certs.d/harbor.l-t.top/
   cp harbor.l-t.top.key /etc/docker/certs.d/harbor.l-t.top/
   cp ca.crt /etc/docker/certs.d/harbor.l-t.top/

   如果您将默认nginx端口 443 映射到不同的端口，请创建文件夹/etc/docker/certs.d/harbor.l-t.top:port或/etc/docker/certs.d/harbor_IP:port.

   以下示例使用自定义证书的配置：

   /etc/docker/certs.d/
       └── harbor.l-t.top:port
          ├── harbor.l-t.top.cert  <-- 由CA签名的服务器证书
          ├── harbor.l-t.top.key   <-- 由CA签名的服务器密钥
          └── ca.crt               <-- 签署注册表证书的证书颁发机构

3. 重启docker服务已生效

   systemctl restart docker

   Tips：

   当 Docker 守护程序在某些操作系统上运行时，您可能需要在操作系统级别信任证书。需要运行以下命令。

   • Ubuntu：

     cp harbor.l-t.top.crt /usr/local/share/ca-certificates/harbor.l-t.top.crt 
     update-ca-certificates

   • RedHat（CentOS 等）：

     cp harbor.l-t.top.crt /etc/pki/ca-trust/source/anchors/harbor.l-t.top.crt
     update-ca-trust

4、开始部署或重新配置 Harbor

如果您尚未部署 Harbor，请参阅 配置 Harbor YML 文件以了解有关如何配置 Harbor 以通过在 中指定hostname和https属性来使用证书的信息harbor.yml。

如果您已经使用 HTTP 部署了 Harbor，并希望将其重新配置为使用 HTTPS，请执行以下步骤。

1. 运行prepare脚本以启用 HTTPS。Harbor 使用nginx实例作为所有服务的反向代理。您使用prepare脚本配置nginx为使用 HTTPS。位于Harbor 安装程序包中，与脚本prepare处于同一级别。install.sh使用 ./prepare --help 查看相关参数配置

   ./prepare --with-notary --with-trivy --with-chartmuseum
   #参数说明：（默认不加，根据实际需求添加）
   #--with-notary: 安装镜像签名组件Notary（包括Notary Server和Notary Singer），必须配置HTTPS方可指定该参数;
   #--with-clair：安装镜像扫描工具Clair；（2.3.1已弃用）;
   #--with-trivy：安装镜像扫描工具Trivy;
   #--with-chartmuseum：安装Char文件管理组件ChartMuseum；

2. 如果 Harbor 正在运行，请停止并删除现有实例。您的镜像数据挂载保留在系统中，因此不会丢失任何数据。

   docker-compose down -v

3. 重启Harbor ：

   docker-compose up -d

5、验证 HTTPS 连接(默认设置)

为 Harbor 设置 HTTPS 后，您可以通过执行以下步骤来验证 HTTPS 连接。

• 打开浏览器并输入https://harbor.l-t.top。它应该显示 Harbor 界面。tips：某些浏览器可能会显示一条警告，指出证书颁发机构 (CA) 未知。当使用不是来自受信任的第三方 CA 的自签名 CA 时，会发生这种情况。您可以将 CA 导入浏览器以删除警告。
• 在运行 Docker 守护程序的机器上，检查/etc/docker/daemon.json文件以确保-insecure-registry未设置https://harbor.l-t.top该选项。
• 从 Docker 客户端登录到 Harbor。

  docker login harbor.l-t.top

  登录成功如下图所示：

  

  如果您已将nginx443 端口映射到其他端口，请在login命令中添加该端口。

  docker login harbor.l-t.top:port

5、验证HTTP连接(根据需要设置)

在运行 Docker 守护程序的机器上，检查/etc/docker/daemon.json文件以确保-insecure-registry设置了harbor.l-t.top该选项。

cat /etc/docker/daemon.json
{
"insecure-registries": ["harbor.l-t.top"],
}

修改/etc/docker/daemon.json文件后，需要重启服务

systemctl daemon-reload
systemctl restart docker

6、其他问题处理：

6.1 重置密码（ 如何重置和找回忘记的 Harbor 管理员密码 ）

# 进入 harbor-db 容器内
docker exec -it harbor-db /bin/bash
# 登录pgsql
psql -U postgres -d postgres
# 切换到harbor所在数据库
\c registry
# 查看 harbor_user 表
select * from harbor_user;
# 清空密码，重启服务后重置为默认 Harbor12345
update harbor_user set salt='', password='' where user_id='1'; 
# 退出
\q
exit
#重启服务
docker-compose down -v 
docker-compose up -d

Tips:由于harbor v2.3之后使用了PostgreSQL v13.2，需要用到高版本docker，将docker升级到20.10.8 之后版本

6.2 数据备份

Harbor所依赖的数据可分为两大类： 临时数据和持久化数据

6.2.1 临时数据

在 Harbor 安装期间通过配置文件生成的数据，主要是 Harbor 组件所依赖的配置文件和环境变量。

这些数据通常在 Harbor 安装目录的 common 目录下（如果 Harbor 是通过源代码安装的，则这些数据在源码目录的“make/common”目录下）

6.2.2 持久化数据

在 Harbor 各组件启动时会被挂载到对应的容器中。虽然临时数据对服务的顺利运行至关重要，但是安装程序每次都会读取 Harbor 配置文件重新生成一份临时数据，所以我们仅需备份配置文件即可，不必将整个 common 目录全部备份

data目录包含的文件夹和相应的作用如下

ca_download：存放用户访问Harbor时所需的CA
cert：Harbor启动HTTPS服务时所需的证书和密钥。
chart_storage：存放Helm v2版本的Chart数据。
database：存放数据库的目录，Harbor、Clair和Notary数据库的数据都在此目录下。
job_logs：存放JobService的日志信息。
redis：存放Redis数据。
registry：存放OCI Artifacts数据（对于大部分用户来说是镜像数据）。
secret：存放Harbor内部组件通信所需的加密信息。

注意：

Harbor在启动时需要挂载这些目录下的文件，在Harbor各组件的容器中除了log容器（依赖logrotate，必须以root权限运行）其他容器都是以非root用户身份运行的，这些文件的用户组信息及权限信息与其在容器中的信息不匹配，在容器中就会发生读取权限相关的错误

所以在主机上需要将这些目录和文件设置成容器的指定用户和用户组，这些文件的用户和权限信息主要有如下两类：

• 数据库和Redis：以999：999的用户组运行容器，即harbor-db组件和harbor-redis组件；
• Harbor的其他容器：以10000：10000的用户组运行容器

6.2.3 Harbor备份

1 备份harbor安装目录

cp -rf /data/harbor /data/harbor_bak

2 备份 harbor data

harbor.yml 中data_volume 值为 持久化数据目录

cp -rf /data/harbor/data /data/harbor/data_backup

6.3 版本更新

软件的版本升级一般分为两个阶段：现有 Harbor 实例的数据迁移和 Harbor 软件升级。

1.数据迁移

在升级 Harbor 版本之前，我们首先需要对现有的数据进行迁移，以适配新的版本。需要迁移的数据有两类：数据库模式（schema）和配置文件数据

数据库模式，也就是数据库中表的结构，每次新版本发布时新的功能及对老功能、代码的重构都会导致数据库模型的变更，因此几乎每次升级都需要升级数据库模式
配置文件数据，是指 Harbor 组件的配置文件，在部分新功能或者新的组件出现时，都需要在配置文件中新增其参数；在老功能、组件重构或者废弃时，也会对配置文件进行更新
如果升级时不做数据迁移，则会导致数据与新版本不兼容而引发问题。而数据迁移是一个高风险操作，操作中出现问题会造成数据丢失等严重后果，所以一定要先进行数据备份，主要就是数据库的数据导出备份。

1.1 数据库迁移

其实每次启动 Harbor 实例时，它的数据库模式都是自动升级的

其原理为：Harbor 在每次启动时都会调用第三方库 “golang-migrate”，它会检测当前数据库模式的版本，如果实例的版本比当前数据库的版本更高，则会自动升级。

1.2 配置升级

因为数据库升级是自动完成，用户其实只需操作配置文件的迁移即可。需要用户手动执行升级配置文件的命令行工具包。此工具包与 Harbor 一同发布，被包含在“goharbor/prepare”镜像中

Harbor的升级遵循一个约定：小版本的升级不会涉及配置文件和数据库的修改，大版本升级不能大于2个版本号，如2.3可以直接升级到2.5

用户可以在 Harbor 的离线安装包导入，也可以在 Docker Hub 上获取：

docker pull goharbor/prepare:version

运行以下命令进行配置文件迁移：

docker run -v /:/hostfs goharbor/prepare:v2.5.0 migrate --input  /usr/local/harbor/harbor-2.4.2.yml --output /usr/local/harbor/harbor-2.5.0.yml --target 2.5.0
# 其中，“-v /:/hostfs” 是将主机的根目录 “/”  挂载到容器中的“/hostfs”目录。
# 因为命令是运行在容器中的，而文件是在宿主机上的，为了能在容器中访问到指定的文件，需要这样挂载，之后 prepare 会对 “/hostfs” 这个文件做特殊处理，使得在容器里也能访问主机上的指定文件
#migrate 命令有如下3个参数。
#--input（缩写形式为“-i”）：是输入文件的绝对路径，也就是需要升级的原配置文件。
#--output（缩写形式为“-o”）：是输出文件的绝对路径，也是升级后的配置文件，是可选参数，如果取默认值，则升级后的文件会被写回输入文件中。
#--target（缩写形式为“-t”）：是目标版本，也就是打算升级到的版本，也是可选参数，如果取默认值，则版本为此工具发布时所支持的最新版
# 所以上命令是将 Harbor 2.4.2 的配置文件 “/usr/local/harbor/harbor-2.4.2.yml” 升级到 Harbor 2.5.0 版本，并且保存到 “/usr/local/harbor/harbor-2.5.0.yml” 目录下。若使用缩写和默认的参数，则命令可以简化如下：
docker run -v /:/hostfs goharbor/prepare:v2.5.0 migrate -i /usr/local/harbor/harbor-2.4.2.yml

2.完整升级操作

#停止 harbor
docker-compose down -v
#备份旧版本 harbor 安装路径
mv harbor /path/harbor_install_backup
#备份数据
cp -rp /data/database /habor_data_backup
#数据迁移
docker run -v /:/hostfs goharbor/prepare:v2.5.0 migrate -i ${原harbor.yml路径}
#参考 1.1 数据迁移详细操作

#使用新配置文件安装Harbor
tar zxf ${新版本Harbor离线包}
cd ${新版本Harbor解压的文件夹}
cp ${新生成的harbor.yml} ${新版本Harbor目录}
./install.sh 

FAQ:升级后 harbor-db 无法启动
通过修改 docker-compose.yml

#在 postgresql 下 添加 
privileged: true