2024 年云原生运维实战文档 99 篇原创计划 第 010 篇 ｜Docker 最佳实战「2024」系列 第 009 篇
你好，欢迎来到运维有术。
今天分享的内容是 Docker 最佳实战「2024」 系列文档中的 Docker 离线部署 Harbor 实战。
生产环境中 Harbor 的部署有在线和离线安装两种，离线方式用的更多，所以今天聊一聊 Harbor 的离线部署。
内容导图
实战服务器配置 (架构 1:1 复刻小规模生产环境，配置略有不同)
| 主机名 | IP | CPU（核） | 内存（GB） | 系统盘（GB） | 数据盘（GB） | 用途 |
|---|---|---|---|---|---|---|
| docker-node-1 | 192.168.9.81 | 4 | 16 | 40 | 100 | Docker 节点 1 |
| docker-node-2 | 192.168.9.82 | 4 | 16 | 40 | 100 | Docker 节点 2 |
| docker-node-3 | 192.168.9.83 | 4 | 16 | 40 | 100 | Docker 节点 3 |
| Harbor | 192.168.9.29 | 4 | 8 | 40 | 500 | Harbor 服务节点 |
| 合计 | 4 | 12 | 56 | 160 | 800 |
实战环境涉及软件版本信息
- 操作系统：openEuler 22.03 LTS SP3
- Docker：24.0.9
- Docker Compose： v2.24.7
- Harbor：2.10.2
1. 先决条件
1.1 硬件需求
- 官方建议的资源需求
| Resource（资源） | Minimum（最小） | Recommended（建议） |
|---|---|---|
| CPU | 2 CPU | 4 CPU |
| Mem | 4 GB | 8 GB |
| Disk | 40 GB | 160 GB |
- 实际分配资源
| Resource（资源） | Minimum | 说明 |
|---|---|---|
| CPU | 4 CPU | 个人或是小集群使用不频繁的场景 2C 即可 中、大规模集群且使用频繁的场景建议初期配置 4C，后期根据实际运行情况再扩容 |
| Mem | 8 GB | 前期给 8 GB 足够了，后期不够再扩容 |
| Disk | 500 GB | 根据计划存储的镜像数量和容量规划 |
1.2 Docker 软件需求
- 官方建议的需求
| Software（软件） | Version（版本） | Description（说明） |
|---|---|---|
| Docker Engine | Version 20.10.10-ce+ or higher | 不建议选择目前的最新 26.0.2，建议 20.10.24 或是 24.0.9 |
| Docker Compose | docker-compose (v1.18.0+) or docker compose v2 (docker-compose-plugin) | 不建议使用目前的最新版 v2.26.1，建议使用v2.24.7 |
- 实际部署
| Software（软件） | Version（版本） | Description（说明） |
|---|---|---|
| Docker Engine | 24.0.9（二进制包） | Docker 离线安装包下载, 也可以安装 docker-ce 镜像仓库适配不同操作系统的安装包，参考清华开源镜像站帮助文档 |
| Docker Compose | v2.24.7（二进制包） | Docker Compose 离线安装包，也可以使用 docker-ce 镜像仓库安装 docker-compose-plugin 包，实际使用时的命令为 docker compose |
- 部署文档
详细的 Docker 和 Docker Compose 的安装部署请参考Docker 和 Docker Compose 离线部署实战。
1.3 网络需求
- 需要防火墙开放的网络端口
| Port | Protocol | Description |
|---|---|---|
| 443 | HTTPS | Harbor portal and core API accept HTTPS requests on this port. HTTPS 请求端口，可以在配置文件中修改该端口。 |
| 4443 | HTTPS | Connections to the Docker Content Trust service for Harbor. 可以在配置文件中修改该端口 . |
| 80 | HTTP | Harbor portal and core API accept HTTP requests on this port. HTTPS 请求端口，可以在配置文件中修改该端口。 |
| 8443 | HTTPS | 本文自定义的外部访问服务端口，你可以根据实际情况自定义 |
1.4 Harbor 离线安装包
- 在能联网的机器，从 Harbor releases page 下载 Harbor 离线安装包。
wget https://github.com/goharbor/harbor/releases/download/v2.10.2/harbor-offline-installer-v2.10.2.tgz
- 上传离线安装包到 Harbor 服务器的
/srv目录 (个人习惯)
cd /srv
- 解压到
/data/harbor目录
tar zxvf harbor-offline-installer-v2.10.2.tgz -C /data
- 解压后的文件内容如下
[root@docker-node-1 srv]# ls /data/harbor
common.sh harbor.v2.10.2.tar.gz harbor.yml.tmpl install.sh LICENSE prepare
2. 安装部署 Harbor
2.1 配置 HTTPS 访问 Harbor
默认安装的 Harbor 是通过不带证书的 HTTP 协议提供服务。生产环境请一定配置 HTTPS。
配置 HTTPS 访问，需要创建证书，证书的创建有两种方式：
- 使用由一个可信的第三方 CA 签名的证书（免费、收费）
- 使用自签名（self-signed）证书
这两种创建证书的方式各有利弊：
- 自签名的证书，需要特殊配置，才可以被 Docker 和 K8S 主机使用，配置虽然算不上麻烦，但是对于新手来说也不是很友好。
- 第三方 CA 签名的证书不需要做额外的配置就可以被 Docker 和 K8S 主机使用，但是收费的太贵了，个人不建议购买。
- 免费的第三方 CA 签名的证书可用时间越来越短，三个月就需要换一次，对于新手来说也不是很友好。
现在网上有很多可以自动申请更换免费的第三方 CA 签名证书的工具。因此，个人还是建议尽量选择购买域名并使用免费的第三方 CA 签名证书。
本文介绍的方案也是使用购买的域名 opsxlab.cn 在腾讯申请免费的 SSL 证书的方式。后期再介绍，如何利用第三方工具自动申请更换证书的方法。
在腾讯云申请免费的 SSL 证书，我运气还算挺好，在免费期可以是一年的最后时间申请时间内，申请了有效期一年的 SSL 证书。
2024 年 4 月 25 号以后申请的免费证书有效期都变成 90 天了，详细的申请过程不做过多描述，关键的过程说明如下：
- 腾讯云（或是其他服务商）申请免费的 SSL 证书
- 填写证书及域名验证方式（选择手动验证）
- 域名管理控制台按要求配置域名
- 申请 SSL 证书的页面验证域名有效
- 提交申请等待审核（过程很快）
- SSL 证书申请成功后，下载 Nginx 或是其他类型的证书。
将下载的证书文件放到服务器指定目录，例如 /srv，解压证书到规划的证书存放目录 /data/harbor-cert。
cd /srv
yum install unzip -y
unzip registry.opsxlab.cn_nginx.zip -d /data/harbor-cert
2.2 配置 Harbor 组件内部通讯使用 TLS
本文介绍如何启用 TLS 认证实现 Harbor 内部组件安全通信。
默认情况下，Harbor 服务内部组件 (harbor-core,harbor-jobservice,proxy,harbor-portal,registry,registryctl,trivy_adapter,chartmuseum) 之间的通信使用 HTTP 协议。
这种配置对于某些生产环境来说可能不满足安全要求。而且，在生产环境中，始终使用 HTTPS 也是推荐的最佳实践。
从 Harbor v2.0 开始，TLS 认证可以用于 Harbor 各组件间的内部网络通信，官方也提供了自带的 prepare 工具的镜像。
- 导入 Harbor 组件的镜像
# 为了使用生成 TLS 证书的工具，需要先导入离线镜像
docker load -i /data/harbor/harbor.v2.10.2.tar.gz
- 查看导入的镜像
[root@docker-node-1 harbor]# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
goharbor/harbor-exporter v2.10.2 9befcab0cee2 2 weeks ago 111MB
goharbor/redis-photon v2.10.2 9d1db211d49a 2 weeks ago 170MB
goharbor/trivy-adapter-photon v2.10.2 8f9e0b6b43ce 2 weeks ago 509MB
goharbor/harbor-registryctl v2.10.2 e5a807ba1f59 2 weeks ago 155MB
goharbor/registry-photon v2.10.2 850d2b3f27f3 2 weeks ago 89MB
goharbor/nginx-photon v2.10.2 9282c21c2fee 2 weeks ago 159MB
goharbor/harbor-log v2.10.2 f288fe2baa96 2 weeks ago 168MB
goharbor/harbor-jobservice v2.10.2 a3247b57a920 2 weeks ago 146MB
goharbor/harbor-core v2.10.2 6cd434d62456 2 weeks ago 174MB
goharbor/harbor-portal v2.10.2 7e5a522c7853 2 weeks ago 167MB
goharbor/harbor-db v2.10.2 cd385df354d4 2 weeks ago 274MB
goharbor/prepare v2.10.2 bf4632d26b65 2 weeks ago 214MB
- 使用
prepare工具生成 TLS Certs 文件
[root@docker-node-1 harbor]# docker run -v /data/harbor-cert:/hostfs goharbor/prepare:v2.10.2 gencert -p /internal/tls/cert -d 3650
注意 : -d 3650，生成一个有效期 10 年的证书，默认是 365 天。 -p 证书存放路径，可以自定义，本文如此设置是为了体现内部用的 tls 证书。
- 查看生成的证书
[root@docker-node-1 harbor]# ls /data/harbor-cert/internal/tls/cert/
core.crt harbor_db.key job_service.key proxy.key registry.key
core.csr harbor_internal_ca.crt portal.crt registry.crt trivy_adapter.crt
core.key harbor_internal_ca.key portal.csr registry.csr trivy_adapter.csr
extfile.cnf harbor_internal_ca.srl portal.key registryctl.crt trivy_adapter.key
harbor_db.crt job_service.crt proxy.crt registryctl.csr
harbor_db.csr job_service.csr proxy.csr registryctl.key
说明 : 生成的文件比较多，具体的每个文件的用途请参考 Harbor 官方文档 Internal TLS communication 说明
- 验证证书有效期
# 以 registy.crt 为例
[root@docker-node-1 data]# openssl x509 -in /data/harbor-cert/internal/tls/cert/registry.crt -noout -dates
notBefore=Apr 26 14:03:43 2024 GMT
notAfter=Apr 24 14:03:43 2034 GMT
2.3 编辑 Harbor YML 文件
本文只介绍需要修改的重点参数，更完整的参数说明，请参考官方文档Configure the Harbor YML File。
本文部署的 Harbor 采用自定义的 https 8443 端口，提供给内网客户端直接访问。同时，启用 external_url 配置项，设置值为 https://registry.opsxlab.cn:8433 通过防火墙转发给外部用户访问。
- 编辑配置文件
cd /data//harbor
cp harbor.yml.tmpl harbor.yml
vi harbor.yml
- 必须修改的参数
# Harbor 服务器的主机名或是 IP
hostname: registry.opsxlab.cn
# 生产环境一定要使用 https
https:
# https 端口, 默认 443, 可根据实际环境修改。但是一定要与 external_url 参数的端口号一致
port: 8443
# Nginx 使用的 cert 和 key 文件(绝对路径)
certificate: /data/harbor-cert/registry.opsxlab.cn_nginx/registry.opsxlab.cn_bundle.pem
private_key: /data/harbor-cert/registry.opsxlab.cn_nginx/registry.opsxlab.cn.key
# 启用内部组件 TLS 通信
internal_tls:
enabled: true
dir: /data/harbor-cert/internal/tls/cert/
# 纯内网使用不需要配置。如果 Harbor 需要通过防火墙或是其他方式转发给外部访问，需要配置此参数为外网 IP 或是外部域名。端口号一定要与 https.port 的端口号保持一致。
external_url: https://registry.opsxlab.cn:8433
# Harbor admin 用户的初始密码，配置文件里可以不用改，但是部署完必须第一时间登录 Harbor，更改密码
harbor_admin_password: Harbor12345
# Harbor DB configuration
database:
# Harbor DB root 用户的密码, 必须修改.
password: OpsXlab2024!
# Harbor 数据存储路径
data_volume: /data/harbor-storage
- 非必需但是重要参数
# 如果是离线内网环境，并且启用 trivy 的场景，还需要配置以下两个参数
trivy:
# skipUpdate The flag to enable or disable Trivy DB downloads from GitHub
#
# You might want to enable this flag in test or CI/CD environments to avoid GitHub rate limiting issues.
# If the flag is enabled you have to download the `trivy-offline.tar.gz` archive manually, extract `trivy.db` and
# `metadata.json` files and mount them in the `/home/scanner/.cache/trivy/db` path.
skip_update: true
#
# The offline_scan option prevents Trivy from sending API requests to identify dependencies.
# Scanning JAR files and pom.xml may require Internet access for better detection, but this option tries to avoid it.
# For example, the offline mode will not try to resolve transitive dependencies in pom.xml when the dependency doesn't
# exist in the local repositories. It means a number of detected vulnerabilities might be fewer in offline mode.
# It would work if all the dependencies are in local.
# This option doesn’t affect DB download. You need to specify "skip-update" as well as "offline-scan" in an air-gapped environment.
offline_scan: true
2.4 运行安装脚本
官方默认安装命令没有启用容器漏洞扫描组件 Trivy，生产环境建议启用。执行下面的命令开始安装 启用了 Trivy 组件的 Harbor 服务。
./install.sh --with-trivy
2.5 正确的安装结果
当看到类似下面的输出，说明安装成功。
[Step 5]: starting Harbor ...
[+] Running 10/11
⠼ Network harbor_harbor Created 2.5s
✔ Container harbor-log Started 0.4s
✔ Container redis Started 1.2s
✔ Container harbor-db Started 1.0s
✔ Container harbor-portal Started 0.9s
✔ Container registryctl Started 1.2s
✔ Container registry Started 0.9s
✔ Container trivy-adapter Started 1.7s
✔ Container harbor-core Started 1.7s
✔ Container harbor-jobservice Started 2.1s
✔ Container nginx Started 2.2s
✔ ----Harbor has been installed and started successfully.----
注意： 但是这个时候 Harbor 并没有真正的启动成功，请按下面的异常解决流程处理。
2.6 异常解决
此节内容为可选内容，如果你部署过程中遇到了跟我一样的问题，可以参考下面的内容解决。
- 问题现象
容器 harbor-jobservice 和 nginx 一直处于 Restarting 状态，并有如下报错日志
nginx | nginx: [emerg] SSL_CTX_load_verify_locations("/harbor_cust_cert/harbor_internal_ca.crt") failed (SSL: error:80000002:system library::No such file or directory:calling fopen(/harbor_cust_cert/harbor_internal_ca.crt, r) error:10000080:BIO routines::no such file error:05880002:x509 certificate routines::system lib)
nginx | 2024/04/26 14:21:22 [emerg] 1#0: SSL_CTX_load_verify_locations("/harbor_cust_cert/harbor_internal_ca.crt") failed (SSL: error:80000002:system library::No such file or directory:calling fopen(/harbor_cust_cert/harbor_internal_ca.crt, r) error:10000080:BIO routines::no such file error:05880002:x509 certificate routines::system lib)
- 解决方案
上面出现异常是因为 Harbor 的部署启用了 TLS 认证，在不启用 TLS 认证的场景，安装脚本执行成功后 Harbor 就能正常使用。
怀疑是 Bug 但我没证据，也不去深究了，采用一个临时解决方案。
cp /data/harbor-cert/internal/tls/cert/harbor_internal_ca.crt /data/harbor/common/config/shared/trust-certificates/
docker-compose stop
docker-compose start
3. Harbor 初始化配置
3.1 修改 admin 用户密码
初次登陆系统，必须修改 admin 用户的默认密码。
- 使用服务器 IP 通过浏览器访问 Harbor 控制台，默认用户 admin，默认密码 Harbor12345
- 登录成功默认显示项目页面，点击右上角 「admin」-> 「修改密码」
- 在弹出的修改密码对话框，输入当前密码并设置新密码，然后点击「确认」按钮。
3.2 创建管理员用户
创建一个新的具有管理员权限的用户用于日常管理。
- 「系统管理」-> 「用户管理」->「创建用户」，在弹出的创建用户对话框中按提示输入用户信息。
- 用户创建完成后，自动返回用户管理页面，选择新创建的用户，点击设置为管理员。
3.3 创建测试项目
Harbor 部署完成后，默认会创建一个名为 library 的公开项目，该项目我们一般用于存储 Docker Hub 官方的公开镜像。
后期我们准备用 Harbor 存储 KubeSphere 和 Kubernetes 相关的镜像，因此，先创建一个名为 kubesphere 的私有项目测试验证 Harbor 的功能。
- 点击「项目」-> 「新建项目」，在弹出的新建项目对话框中按提示输入项目信息（访问级别不要勾选 公开）
- 信息填写完成后，点击「确认」，创建项目
4. Harbor 验证测试
Harbor 安装完成后，我们需要验证 Harbor 是否能正常上传、下载镜像。
我们选择节点 docker-node-1 做为客户端验证测试 Harbor 的功能是否正常。
4.1 配置客户端
由于我们使用的是可信的第三方 CA 签名的证书。因此，Docker 和 Containerd 等容器运行时不需要做特殊的配置。如果是自签名的证书则需要将证书放到指定的目录并特殊配置，自签名的方案本文不涉及，如果需求多后期可以专门写一篇自签名证书的 Harbor 部署教程。
但是，由于我们在内网服务器使用域名 registry.opsxlab.cn 访问 Harbor 服务。因此，所有访问 Harbor 的服务器需要手动配置 /etc/hosts 文件解析。
echo "192.168.9.29 registry.opsxlab.cn" >> /etc/hosts
4.2 验证测试
- 登录 Harbor
[root@docker-node-1 ~]# docker login registry.opsxlab.cn:8443
Username: opsxlab
Password:
WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded
- 上传测试镜像
# 查看已有 image
[root@docker-node-1 ~]# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
kubesphere/pause 3.9 e6f181688397 18 months ago 744kB
# 重新打标签
docker tag kubesphere/pause:3.9 registry.opsxlab.cn:8443/kubesphere/pause:3.9
# 上传
[root@docker-node-1 ~]# docker push registry.opsxlab.cn:8443/kubesphere/pause:3.9
The push refers to repository [registry.opsxlab.cn:8443/kubesphere/pause]
e3e5579ddd43: Pushed
3.9: digest: sha256:0fc1f3b764be56f7c881a69cbd553ae25a2b5523c6901fbacb8270307c29d0c4 size: 526
- 在 Harbor 中查看
- 下载镜像
# 为了更好的测试，先删除本地刚上传的镜像
[root@docker-node-1 ~]# docker rmi kubesphere/pause:3.9
Untagged: kubesphere/pause:3.9
Untagged: kubesphere/pause@sha256:7031c1b283388d2c2e09b57badb803c05ebed362dc88d84b480cc47f72a21097
[root@docker-node-1 ~]# docker rmi registry.opsxlab.cn:8443/kubesphere/pause:3.9
Untagged: registry.opsxlab.cn:8443/kubesphere/pause:3.9
Untagged: registry.opsxlab.cn:8443/kubesphere/pause@sha256:0fc1f3b764be56f7c881a69cbd553ae25a2b5523c6901fbacb8270307c29d0c4
Deleted: sha256:e6f1816883972d4be47bd48879a08919b96afcd344132622e4d444987919323c
Deleted: sha256:e3e5579ddd43c08e4b5c74dc12941a4ef656fab070b1087a1fd5a8a836b71e7d
[root@docker-node-1 ~]# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
# 下载镜像
[root@docker-node-1 ~]# docker pull registry.opsxlab.cn:8443/kubesphere/pause:3.9
3.9: Pulling from kubesphere/pause
61fec91190a0: Pull complete
Digest: sha256:0fc1f3b764be56f7c881a69cbd553ae25a2b5523c6901fbacb8270307c29d0c4
Status: Downloaded newer image for registry.opsxlab.cn:8443/kubesphere/pause:3.9
registry.opsxlab.cn:8443/kubesphere/pause:3.9
至此，我们完成了镜像仓库 Harbor 的安装部署和测试验证。
5. 总结
本文分享了离线部署 Harbor 服务的详细流程及注意事项。主要内容概括如下：
- Harbor 部署的先决条件
- Harbor 配置 HTTPS 访问
- Harbor 启用 TLS 认证
- Harbor 的安装部署和初始化配置
- Harbor 验证测试
免责声明：
- 笔者水平有限，尽管经过多次验证和检查，尽力确保内容的准确性，但仍可能存在疏漏之处。敬请业界专家大佬不吝指教。
- 本文所述内容仅通过实战环境验证测试，读者可学习、借鉴，但严禁直接用于生产环境。由此引发的任何问题，作者概不负责！
Get 本文实战视频（请注意，文档视频异步发行，请先关注）
如果你喜欢本文，请分享、收藏、点赞、评论！ 请持续关注 @ 运维有术，及时收看更多好文！
欢迎加入 「知识星球｜运维有术」 ，获取更多的 KubeSphere、Kubernetes、云原生运维、自动化运维、AI 大模型等实战技能。未来运维生涯始终有我坐在你的副驾。
版权声明
- 所有内容均属于原创，感谢阅读、收藏，转载请联系授权，未经授权不得转载。
