前言

Harbor是企业级Docker私有镜像仓库，其底层基于Docker容器引擎与Docker Compose多容器编排，在官方原生Registry的基础上，补充了UI管理、权限控制、安全加密等企业级增强功能，是企业容器化部署中镜像存储、管理的核心工具。

一、核心定位

Harbor 本质 是 企业级 Docker 私有镜像仓库，底层是：Docker Registry（官方原生仓库）+ 一堆增强组件 + Docker Compose 编排 ，官方原生 registry 只有存镜像、拉推镜像裸功能，没界面、没权限、没日志、没漏洞扫描，Harbor 就是给原生 Registry 套了一层企业级管理壳

二、Harbor 底层架构核心组件

整个 Harbor 全部跑在 Docker 容器里，用 docker compose 统一管理启停。

1. Registry（底层存储核心）真正存镜像层文件的组件，就是官方原版 registry。所有你 push /pull 的镜像，最终都存在它这里，磁盘落地到服务器 data_volume 目录。

2. UI Portal（前端页面）网页控制台，你登录、建项目、管理镜像、看日志，都是访问这个前端。

3. Core（核心服务）Harbor 大脑，负责权限校验、项目管理、角色控制、转发请求。你网页操作、docker 登录鉴权，全由它调度。

4. Database（数据库）默认用 PostgreSQL，存：账号密码、项目权限、镜像元数据、日志、配置信息 （不存镜像二进制，只存信息）。

5. Redis做缓存、会话存储、任务队列，提速页面和接口响应。

6. Nginx（反向代理入口）统一入口，承接 80/443 端口，把请求转发给 UI、Core、Registry；同时承载 HTTPS 证书、路由分发。

7. Notary、Trivy（可选）镜像签名、漏洞扫描，安全增强组件，底层也是独立容器。

三，搭建 Harbor 底层逻辑

1. 先打底：装 Docker + Docker Compose

Harbor 不裸装系统，全部容器化运行，必须依赖 Docker 做容器引擎，Compose 做多容器编排（一次性启动所有组件容器）

相当于先租场地、配齐基础水电 + 请大管家，Harbor 不单独裸装在系统上，所有组件必须住 Docker 的房间里；Compose 就是总管家，能一次性把所有岗位人员全部安排上岗

2. 离线包本质是什么？

下载的 harbor-offline.tgz：

• 里面打包了所有 Harbor 组件的镜像压缩包

• 解压后是配置文件、安装脚本、模板配置

就是一整套快递园装修材料 + 所有工作人员打包压缩包：里面预装了所有组件的程序安装包、配置模板、一键开工脚本，不用现场再到处找人找材料

3. 配置 harbor.yml 底层逻辑

你改的几个关键配置，背后作用：

• hostname：整个仓库访问域名 / IP，Nginx、证书、Docker 客户端都要跟它对齐

类似给快递园定唯一门牌地址，大门、通行证、访客都必须认这个地址

• https 证书：Nginx 挂载证书，实现 HTTPS 加密访问

相当于给大门办合法安全通行证，保证来往通信不被偷看、不被篡改

• harbor_admin_password：写入数据库的默认管理员密码

给最高管理员设门卫钥匙，记进花名册

• data_volume：指定镜像持久化存储目录，容器删了镜像文件还在宿主机磁盘

划定专属库房固定区域，就算拆了临时办公室，库房里的包裹还在，不会丢

4. 执行 install.sh 干了什么底层事？

1. 导入离线包里所有 Harbor 镜像到本地 Docker

2. 根据 harbor.yml 自动生成 docker-compose.yml 编排文件

3. 自动创建网络、挂载目录、启动所有组件容器

4. 初始化数据库、创建 admin 账号、初始化项目

就比如一键开工装修 + 全员到岗：导入所有工作人员程序、根据你定的规矩自动生成管理制度、建好内部通道、分配好办公库房场地、一次性全员上岗，同时建好花名册、创建超级管理员、预留公共储物区。

5. 开机自启 systemd 底层逻辑

只是封装了：开机自动执行 docker compose up -d依赖 docker 服务先启动，再拉起 Harbor 所有容器。

四、Docker 拉 / 推镜像 底层流程

1. 你执行 docker login 仓库IP

2. Docker 先连 Harbor Nginx 443 端口

3. Nginx 转发给 Core 服务做账号密码鉴权

4. 鉴权通过后，push 镜像 → 最终落到 Registry 存储

5. 元数据（镜像名、版本）写入 PostgreSQL

五、学习重点

1. 首先我们要知道Harbor是容器化部署，所有组件如 Registry、UI、数据库等，都跑在Docker容器中，对CPU、内存要求高于普通服务，如镜像拉推、存储需消耗资源。

2. 像80（HTTP）、443（HTTPS）是Harbor的核心访问端口：Nginx作为反向代理，统一承接这两个端口的请求，必须确保端口放行，就比如防火墙需开放，云服务器需配置安全组

3. 磁盘建议用SSD：镜像由多个层组成，拉推时需要频繁读写磁盘，SSD能大幅提升速度，避免卡顿

六、搭建步骤

第一步：安装Docker + Docker Compose

这一步我们需要安装Docker、Docker compose 以及设置开机启自起

首先，我们要明白Harbor的所有组件（Registry、UI、Core等）都以Docker容器形式运行，Docker是 容器引擎 ，负责创建、运行、管理容器，是搭建Harbor的基础，没有Docker，Harbor无法启动

其次Harbor包含多个独立组件（10+容器），单独启动每个容器繁琐且易出错，Compose（v2插件版）用于 多容器编排，可以通过一个配置文件，一次性启动、停止所有Harbor组件，简化部署

至于开机自启的意义是Docker服务必须先于Harbor启动，设置Docker开机自启，避免后续Harbor开机自启时因Docker未启动而失败

• 执行命令

# 1. 更新系统软件源，确保获取最新的软件包列表（避免安装旧版本）
sudo apt update
# 安装依赖包，用于后续添加Docker官方源（ca-certificates保证证书验证，curl用于下载文件）
sudo apt install -y ca-certificates curl gnupg lsb-release

# 2. 导入Docker官方GPG密钥（验证Docker软件包的合法性，防止恶意软件）
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 3. 添加Docker官方软件源（告诉系统从哪里下载Docker，避免用Ubuntu默认的旧版本）
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 安装Docker核心组件和Compose插件（核心操作）
sudo apt update  # 再次更新源，确保加载Docker官方源
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 5. 启动Docker服务，并设置开机自启（确保系统重启后Docker能自动运行，为Harbor提供容器引擎）
sudo systemctl start docker
sudo systemctl enable docker

# 6. 验证安装是否成功（检查版本，确认服务正常）
docker --version
docker compose version

• 执行结果

• 在执行 sudo apt update 时，若出现以下错误

这是典型的 Docker APT 源公钥缺失 问题：APT 无法验证 Docker 软件源的签名，因为系统缺少对应的公钥，为了安全默认禁用了该源，使用的版本本身兼容 Docker 源，问题根源是公钥未正确导入。

我们只需要把2.重新导入Docker官方GPG密钥 和 3. Docker 软件源，然后再次更新就好了

• 如果出现docker-compose-plugin 与 docker-compose-v2冲突

是因为系统里已经安装了 docker-compose-v2 包，它已经占用了/usr/libexec/docker/cli-plugins/docker-compose这个路径，而 docker-compose-plugin 安装时会尝试覆盖同一个文件，导致冲突

 # 1.卸载冲突旧包
sudo apt remove -y docker-compose-v2
sudo apt autoremove -y

# 2. 清理缓存
sudo apt clean
sudo apt update

# 3. 重新安装
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

第二步：下载 Harbor 离线包

这一步是为了获取Harbor的组件

首先离线包 vs 在线包：离线包（offline）已打包所有 Harbor 组件的镜像文件，无需在线拉取（适合内网、网络差的环境）；在线包（online）仅含配置和脚本，需在线下载所有镜像，速度慢且依赖网络。

其次解压目录选择：/opt 目录是 Linux 标准的 可选软件目录，权限统一，后续配置 Harbor 时，挂载目录、权限管理更方便，不建议解压到其他目录（如 /home）。

而且离线包的内容：解压后包含 harbor.yml.tmpl（配置模板）、install.sh（安装脚本）、LICENSE（许可证）等，核心是 离线镜像压缩包 ，后续安装脚本会自动导入这些镜像到本地 Docker

• 执行命令

# 1. 访问Harbor官网 Releases 页面，查看最新稳定版（推荐选择offline离线包，无需在线拉取镜像）
# 官网地址：https://github.com/goharbor/harbor/releases
# 本文以 v2.12.2 离线包为例，下载命令（约1.2G，根据网络速度调整）
sudo wget https://github.com/goharbor/harbor/releases/download/v2.14.3/harbor-offline-installer-v2.14.3.tgz

# 2. 解压离线包到 /opt 目录（/opt是Linux系统常用的第三方软件安装目录，便于管理）
sudo tar zxf harbor-offline-installer-v2.14.3.tgz -C /opt

# 3. 进入Harbor安装目录（后续所有配置、安装操作都在此目录执行）
cd /opt/harbor

• 执行结果

第三步：配置 HTTPS自签名证书

我们需要知道为什么要做HTTPS，其次需要去了解自签名证书的逻辑、关键禁忌以及证书文件作用

首先Docker 客户端（拉 / 推镜像）默认要求仓库使用 HTTPS（HTTP 需额外配置信任），HTTPS 通过证书加密通信，防止镜像被篡改、请求被拦截，是企业级仓库的必备配置。

其次没有第三方 CA 如阿里云、Let's Encrypt 颁发的证书时，自己生成 CA 证书，再用 CA 证书给 Harbor 服务器证书签名，本质是 自己信任自己 ，适合测试、内网环境也就是自产环境建议用第三方 CA 证书，这就是自签的逻辑

在这个期间的关键逻辑CA 证书、Harbor 证书的 CN（Common Name）必须和后续配置的 harbor.yml 中的 hostname 完全一致（比如 hostname 是 192.168.1.100，CN 就填 192.168.1.100），否则证书无效，Docker 客户端无法信任

证书文件作用就ca.key（CA 私钥）、ca.crt（CA 证书，用于客户端信任）、harbor.key（Harbor 私钥）、harbor.crt（Harbor 服务器证书，用于 HTTPS 通信）

证书这一块具体可看

• 此次执行命令

# 1. 创建证书存储目录
sudo mkdir -p /opt/harbor/key
cd /opt/harbor/key

# 2. 生成CA私钥（加sudo避免Permission denied）
sudo openssl genrsa -out ca.key 4096

# 3. 生成CA证书（有效期10年，按提示填写信息，Common Name填服务器IP/域名）
sudo openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.crt
# 交互填写时：
# Country Name: CN
# State or Province Name: 直接回车留空
# Locality Name: chongqing（或自定义）
# Organization Name: yxwa（或自定义）
# Organizational Unit Name: 直接回车留空
# Common Name:  你的服务器IP，必须填对！
# Email Address: 直接回车留空

# 4. 生成服务器私钥
sudo openssl genrsa -out server.key 4096

# 5. 生成服务器证书签名请求（CSR）
sudo openssl req -new -key server.key -out server.csr

# 6. 生成服务器证书（需先创建extfile配置文件，替换为你的服务器IP/域名）
cat > server.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1=harbor.yourdomain.com
IP.1=192.168.1.100  # 替换为你的服务器IP
EOF

sudo openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650 -sha256 -extfile server.ext

# 7. 验证证书文件
ls /opt/harbor/key

• 执行结果

第四步：修改 Harbor 配置文件

此步骤重点

hostname 必须与证书地址一致，否则 Harbor 启动后无法正常访问。

data_volume 是镜像存储目录，必须在 SSD 磁盘上，保障拉推速度。

管理员密码需自定义，避免弱密码带来的安全风险。

• 执行命令

cd /opt/harbor

# 拷贝
sudo cp harbor.yml.tmpl harbor.yml

# 编辑
sudo vim harbor.yml

修改以下关键配置：

# 1. 服务器IP（必须与证书Common Name和subjectAltName一致）
hostname: 172.16.11.50  # 替换为你的服务器IP

# 2. HTTPS配置（开启并指定证书路径）
https:
  port: 443
  certificate: /opt/harbor/key/server.crt
  private_key: /opt/harbor/key/server.key

# 3. 管理员初始密码（自定义，避免使用默认密码）
harbor_admin_password: Harbor123456  # 建议改成自定义强密码

# 4. 数据存储路径（保持默认/opt/harbor/data，确保在SSD磁盘上）
data_volume: /opt/harbor/data

第五步：安装并启动 Harbor

学习重点

install.sh 会自动拉取 Harbor 镜像、创建容器、配置网络，启动所有服务， 安装完成后，可通过 docker compose ps 查看所有容器状态，确保均为 Up 状态

• 执行命令

cd /opt/harbor

# 启动
sudo ./install.sh

• 结果图

  

第六步：配置开机自启

• 执行命令

sudo nano /etc/systemd/system/harbor.service

写入以下内容：

[Unit]
Description=Harbor Container Registry
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/harbor
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

执行以下命令生效：

sudo systemctl daemon-reload
sudo systemctl enable harbor
sudo systemctl start harbor

systemd 服务可确保服务器重启后 Harbor 自动启动，无需手动执行命令。 WorkingDirectory 必须指定为 /opt/harbor，否则 docker compose 无法找到配置文件

第七步：对Habor进行验证

• 浏览器访问ip进行验证

一般Harbor默认用户名是admin

如果忘记密码，在终端执行命令

# 进入Harbor所在文件目录下
cd /opt/harbor

# 过滤密码
grep harbor_admin_password harbor.yml

登录后界面是这样

第七步：日常维护

底层基座：Docker + Docker Compose 是 Harbor 的运行基础，所有组件均以容器形式部署，在性能关键：必须使用 SSD 磁盘存储镜像，避免拉推卡顿；证书配置必须与访问 IP（172.16.11.50）一致，否则客户端无法连接， 安全要点：修改默认管理员密码、配置 HTTPS 加密通信、信任自签证书，维护要点：通过 docker compose 命令管理服务，查看日志排查问题，配置开机自启保障服务持续可用。

# 查看Harbor容器状态
cd /opt/harbor
docker compose ps

# 查看Harbor日志
docker compose logs -f harbor-core

# 重启Harbor服务
docker compose restart

# 停止Harbor服务
docker compose down

# 启动Harbor服务
docker compose up -d