企业级 Docker 镜像仓库搭建：Harbor 超详细实战指南（附全流程步骤解析）

Harbor 是 VMware 开源的企业级 Docker 镜像仓库，基于 Docker Registry 二次开发，提供可视化管理、权限控制、镜像复制、漏洞扫描等企业级功能。相比原生 Registry，Harbor 解决了镜像管理不便、安全性不足、运维效率低等问题，是容器化部署的核心基础设施。

2. 核心组件架构

Proxy：Nginx 反向代理，分发 Web 界面与镜像传输流量，支持 HTTP/HTTPS 端口映射（如 80→8080，443→8443）。
UI 服务：Web 管理界面，基于 MySQL 存储元数据，提供镜像浏览、项目管理、用户认证等功能。
Registry：镜像存储引擎，通过 Webhook 通知 UI 创建 Repository，支持本地存储或分布式存储（如 S3、NFS）。
Admin Server：系统配置中心，管理存储配额、复制策略等全局参数，供 UI 和 Job Server 加载初始化配置。
Job Server：异步处理镜像复制任务，支持跨 Registry 的 Pull/Push，并记录任务日志。
Log 服务：集中收集各组件日志，通过 Docker 日志驱动实现统一管理。

二、环境准备：打造 Harbor 运行基石

2.1 基础环境配置

2.1.1 修改主机名

[root@localhost ~]# hostnamectl set-hostname harbor

作用：设置主机名为harbor，便于后续通过主机名访问本地服务，避免 IP 依赖。

2.1.2 配置仅主机模式 IP

[root@harbor ~]# nmcli connection modify ens160 ipv4.method manual \
  ipv4.addresses 192.168.128.20/24 \
  ipv4.gateway 192.168.128.2 \
  ipv4.dns "223.5.5.5 8.8.8.8" \
  connection.autoconnect yes
[root@harbor ~]# nmcli connection up ens160

网络规划：

分配固定 IP192.168.128.20给仅主机网卡（ens160），用于内部通信
设置 DNS 服务器（阿里云 + Google）确保域名解析
autoconnect yes保证开机自动激活网络

2.1.3 开启 IP 转发

[root@harbor ~]# echo 'net.ipv4.ip_forward=1' >> /etc/sysctl.conf
[root@harbor ~]# sysctl -p
net.ipv4.ip_forward = 1

必要性：允许容器网络与宿主网络通信，支持 Docker 容器跨主机通信（如 Kubernetes 节点间通信）。

2.1.4 配置主机映射

[root@harbor ~]# cat >> /etc/hosts <<EOF
192.168.10.20  harbor.registry.com harbor
EOF

[root@harbor ~]# systemctl is-active docker
active

作用：将 IP 与自定义域名harbor.registry.com绑定，方便通过域名访问 Harbor 服务，避免硬编码 IP。

三、Docker 与 Docker Compose 安装：构建运行基础

3.1 安装 Docker 引擎

3.1.1 添加阿里云 Docker 源

[root@harbor ~]# dnf install yum-utils -y
[root@harbor ~]# yum-config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/rhel/docker-ce.repo

优势：阿里云源下载速度快，提供稳定的 Docker CE 版本，避免官方源网络波动。

3.1.2 安装 Docker 及插件

[root@harbor ~]# dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

包含组件：

docker-ce：Docker 引擎
docker-compose-plugin：Docker Compose 插件（替代传统独立安装方式）

3.1.3 深度配置 Docker

[root@harbor ~]# cat > /etc/docker/daemon.json <<EOF
{
  "default-ipc-mode": "shareable",       # 容器间共享IPC命名空间
  "data-root": "/data/docker",           # 镜像数据存储目录（非系统盘）
  "exec-opts": ["native.cgroupdriver=systemd"],  # 使用systemd cgroup驱动
  "log-driver": "json-file",             # 日志驱动（默认）
  "log-opts": { "max-size": "100m", "max-file": "50" },  # 日志切割策略
  "insecure-registries": ["https://harbor.registry.com"],  # 信任自签名证书
  "registry-mirrors": [                  # 镜像加速地址（多源备份）
    "https://docker.m.daocloud.io",
    "https://docker.imgdb.de"
  ]
}
EOF

关键配置解析：

data-root：避免镜像存储占用根分区，建议挂载独立磁盘
insecure-registries：允许访问未经验证的 HTTPS 仓库（用于自签名证书场景）
registry-mirrors：加速 Docker Hub 镜像拉取，提升部署效率

3.1.4 启动与验证

[root@harbor ~]# systemctl enable --now docker
[root@harbor ~]# docker info  # 验证cgroup驱动、存储路径等配置

3.2 安装 Docker Compose

3.2.1 下载二进制文件

[root@harbor ~]# wget https://github.com/docker/compose/releases/download/v2.35.1/docker-compose-linux-x86_64

3.2.2 安装与赋权

[root@harbor ~]# mv docker-compose-linux-x86_64 /usr/bin/docker-compose
[root@harbor ~]# chmod +x /usr/bin/docker-compose

3.2.3 验证版本

[root@harbor ~]# docker-compose --version  # 应输出v2.35.1

注意：Docker Compose 用于编排 Harbor 多容器组件，需与 Docker 引擎版本兼容。

四、Harbor 安装准备：离线包与证书配置

4.1 下载与解压 Harbor

[root@harbor ~]# mkdir -p /data/harbor && cd /data/harbor
[root@harbor data]# wget https://github.com/goharbor/harbor/releases/download/v2.13.0/harbor-offline-installer-v2.13.0.tgz
[root@harbor data]# tar -xzf harbor-offline-installer-v2.13.0.tgz 
[root@harbor data]# rm -f harbor-offline-installer-v2.13.0.tgz 
[root@harbor data]# ls
docker  harbor


#查看
[root@harbor data]# cd harbor/
[root@docker harbor]# ls
common.sh  harbor.v2.13.0.tar.gz  harbor.yml.tmpl  install.sh  LICENSE  prepare

#解压
[root@docker harbor]# docker load -i harbor.v2.13.0.tar.gz 
874b37071853: Loading layer  40.92MB/40.92MB
7824f74aeb34: Loading layer  16.73MB/16.73MB
6409b9df8a24: Loading layer  175.4MB/175.4MB
be0b74c61638: Loading layer  26.55MB/26.55MB
fa43dc6ea88a: Loading layer   18.8MB/18.8MB
129629e46413: Loading layer   5.12kB/5.12kB
......

优势：离线安装包适合网络隔离环境，包含所有依赖镜像（如 MySQL、Redis、Nginx 等）。

4.2 生成 HTTPS 证书（生产级配置）

这里我们可以查看官网中证书生成的代码

官网：Harbor docs | Configure HTTPS Access to Harbor

4.2.1 生成 CA 根证书

创建ssl并进入该目录中进行操作：

[root@harbor harbor]# mkdir ssl && cd ssl
[root@harbor ssl]# openssl genrsa -out ca.key 4096  # 4096位强加密私钥
[root@harbor ssl]# 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  # 生成自签名CA证书（有效期10年）

4.2.2 生成服务器证书

官网中创建CA证书的页面往下翻动：

# 生成服务器私钥
[root@harbor ssl]# openssl genrsa -out harbor.registry.com.key 4096

# 生成证书签名请求（CSR）
[root@harbor ssl]# openssl req -sha512 -new \
  -subj "/C=CN/ST=Chongqing/L=Banan/O=example/OU=Personal/CN=harbor.registry.com" \
  -key harbor.registry.com.key -out harbor.registry.com.csr

# 配置证书扩展（支持多域名）
[root@harbor ssl]# 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.registry.com  # 主域名
DNS.2 = harbor  # 别名
EOF

# 生成最终服务器证书
[root@harbor ssl]# openssl x509 -req -sha512 -days 3650 \
  -extfile v3.ext -CA ca.crt -CAkey ca.key -CAcreateserial \
  -in harbor.registry.com.csr -out harbor.registry.com.crt

关键参数：

subjectAltName：允许通过多个域名访问（如harbor.registry.com和harbor）
serverAuth：标识证书用于服务器认证

4.2.3 证书部署

# 1. 复制到Harbor证书目录
[root@harbor ssl]# mkdir /data/cert
[root@harbor ssl]# cp harbor.registry.com.crt harbor.registry.com.key /data/cert/

# 2. 转换格式供Docker使用
[root@harbor ssl]# openssl x509 -inform PEM -in harbor.registry.com.crt -out harbor.registry.com.cert

# 3. 配置Docker信任证书
[root@harbor ssl]# mkdir -p /etc/docker/certs.d/harbor.registry.com:443
[root@harbor ssl]# cp harbor.registry.com.cert harbor.registry.com.key ca.crt /etc/docker/certs.d/harbor.registry.com:443/

# 4. 重启Docker使证书生效
[root@harbor ssl]# systemctl restart docker

# 查看状态
[root@harbor ssl]# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: disabled)
     Active: active (running) since Sun 2025-05-11 11:01:05 CST; 4s ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 3266 (dockerd)
      Tasks: 10
     Memory: 78.1M
        CPU: 412ms
     CGroup: /system.slice/docker.service
             └─3266 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

五、Harbor 核心部署：从配置到启动

5.1 配置 Harbor 核心参数

5.1.1 复制配置模板

[root@harbor harbor]# cp harbor.yml.tmpl harbor.yml
[root@harbor harbor]# vim harbor.yml  # 关键配置如下

5.1.2 核心配置解析

hostname: harbor.registry.com  # 必须与证书CN一致，否则HTTPS验证失败
http:
  port: 80  # HTTP端口，自动重定向到HTTPS（443）
https:
  port: 443  # HTTPS端口
  certificate: /data/cert/harbor.registry.com.crt  # 证书路径（与实际存储一致）
  private_key: /data/cert/harbor.registry.com.key  # 私钥路径
harbor_admin_password: Harbor12345  # 管理员初始密码（建议生产环境修改）
database:
  password: Harbor12345  # MySQL数据库密码（保持默认即可）

5.2 加载镜像与启动服务

5.2.1 加载离线镜像

[root@harbor harbor]# docker load -i harbor.v2.13.0.tar.gz

过程解析：解压并加载 Harbor 所需的 12 个镜像（如 harbor-db、nginx-photon 等），约 1.2GB。

5.2.2 环境检查与配置生成

[root@harbor harbor]# ./prepare  # 关键输出：生成/docker-compose.yml

作用：

验证 Docker 和 Docker Compose 版本
生成各组件配置文件（如 nginx.conf、core/env 等）
创建数据存储目录（/config、/data、/log）

5.2.3 启动 Harbor 服务

[root@harbor harbor]# ./install.sh  # 执行5步安装流程

输出解析：

检查 Docker 和 Compose 版本
加载镜像（已完成，跳过）
准备环境（创建网络、数据卷）
生成配置（覆盖 prepare 生成的文件）
启动容器（10 个服务容器，状态需全部为Up (healthy)）

5.2.4 查看容器状态

[root@harbor harbor]# docker-compose ps  # 确保所有容器健康运行

六、服务管理优化：systemd 实现便捷启停

6.1 编写 systemd 服务文件

[root@harbor harbor]# vim /usr/lib/systemd/system/harbor.service

[Unit]
Description=Harbor Docker Registry
After=docker.service systemd-networkd.service systemd-resolved.service  # 依赖Docker和网络服务
Requires=docker.service  # 确保Docker先启动

[Service]
Type=simple
Restart=on-failure  # 失败自动重启
RestartSec=5  # 重启间隔
ExecStart=/usr/bin/docker-compose -f /data/harbor/docker-compose.yml up  # 启动命令
ExecStop=/usr/bin/docker-compose -f /data/harbor/docker-compose.yml down  # 停止命令

[Install]
WantedBy=multi-user.target  # 加入多用户启动目标

6.2 激活服务

[root@harbor ~]# systemctl daemon-reload  # 重新加载配置
[root@harbor ~]# systemctl start harbor.service  # 启动服务
[root@harbor ~]# systemctl enable harbor.service  # 开启开机自启
[root@harbor ~]# systemctl status harbor  # 验证状态（active/running）

七、功能验证：从镜像操作到 API 调用

7.1 定制本地仓库

7.1.1 Windows 端配置域名解析

修改C:\Windows\System32\drivers\etc\hosts，添加：
plaintext
```
192.168.10.20  harbor.registry.com
```

7.1.2 浏览器访问

地址：https://harbor.registry.com
登录：admin/Harbor12345（首次登录强制修改密码可选）

第一次登录会提醒不安全，继续访问登录即可。

7.2 镜像操作全流程

7.2.1 拉取与打标签

# 拉取Nginx镜像
[root@harbor ~]# docker pull nginx:1.28.0

# 打标签（格式：仓库地址/项目名/镜像名:版本）
[root@harbor ~]# docker tag nginx:1.28.0 harbor.registry.com/library/nginx:1.28.0

7.2.2 登录与推送

# 登录（忽略证书警告需加--insecure-registry，此处已配置信任）
[root@harbor ~]# docker login harbor.registry.com -u admin -p Harbor12345

# 推送镜像
[root@harbor ~]# docker push harbor.registry.com/library/nginx:1.28.0

7.2.3 拉取验证

# 删除本地镜像
[root@harbor ~]# docker rmi -f nginx:1.28.0 harbor.registry.com/library/nginx:1.28.0

# 从Harbor拉取
[root@harbor ~]# docker pull harbor.registry.com/library/nginx:1.28.0

7.4 API 查看镜像列表

[root@docker ~]# curl -k -u 'admin:Harbor12345' https://harbor.registry.com/api/v2.0/projects/library/repositories

输出解析：返回 JSON 数组，包含镜像名称、创建时间、拉取次数等元数据。

八、生产环境注意事项

1. 证书管理

定期更换证书（建议每年更新）
生产环境使用 CA 签发的正规证书（非自签名）

2. 存储扩展

# harbor.yml添加分布式存储配置
storage:
  filesystem:
    root: /data/harbor  # 本地存储
  # 或使用S3存储（需安装s3fs）
  # s3:
  #   accesskey: AKIAXXXXXXXX
  #   secretkey: XXXXXXXXXXXXXXX