Docker 搭建本地Harbor私有镜像仓库

一、Harbor 核心价值与企业级特性解析

在容器化技术普及的背景下，镜像仓库作为容器生命周期的核心组件，其可靠性直接影响开发效率与生产稳定性。Docker 官方的 Registry 虽能实现基础镜像存储，但存在明显短板：无可视化界面、缺乏权限管控、无安全扫描等企业级功能，无法满足企业对镜像管理的精细化需求。

从企业实际需求出发，私有镜像仓库的部署具有不可替代的价值：

• 安全隔离：企业核心业务镜像无需暴露在公共仓库，降低源码泄露与恶意篡改风险；
• 效率提升：内部网络环境下镜像传输速度远高于公共仓库，减少部署等待时间；
• 合规可控：支持操作审计、权限细化管理，满足金融、政务等行业的监管要求。

Harbor 作为 VMware 推出的开源企业级镜像仓库，针对性解决了这些问题，其核心企业级特性包括：

• 权限管理体系：基于 RBAC（角色基础访问控制）实现多用户、多项目的权限隔离，支持 LDAP 集成实现统一身份认证；
• 安全防护能力：集成 Clair、Trivy 等漏洞扫描工具，可自动检测镜像中的安全风险，同时支持镜像签名与验真，确保镜像完整性；
• 可视化与易用性：提供直观的 Web 管理界面，支持中文显示，降低运维门槛；
• 高可用支撑：内置镜像复制功能，为跨节点数据同步提供基础，支持多节点部署；
• 本地化适配：针对国内用户设计镜像跨仓库复制功能，满足多地域镜像同步需求。

二、高可用方案选型与架构设计

2.1 高可用方案核心目标

容器镜像仓库的高可用本质是减少服务中断时间，确保开发人员能稳定推送镜像、业务集群能正常拉取镜像。对于中小型企业，通常可接受 “分钟级” 故障恢复（即故障发生后，通过手动操作在几分钟内恢复服务），无需追求金融级 “秒级” 高可用（需复杂集群架构支撑）。

2.2 方案选型：双主复制 + Nginx 代理

本次采用 “双主复制 + Nginx 代理” 的高可用方案，架构示意图如下：

外部访问 → Nginx代理节点 → Harbor A节点/Harbor B节点（双向复制）

该方案的核心逻辑是：通过两个 Harbor 节点的双向复制实现数据冗余，通过 Nginx 代理提供统一访问入口，节点故障时手动切换 Nginx 代理目标。

方案选型理由：

• 架构简单易维护：无需复杂的集群编排工具，中小型企业运维人员可快速上手；
• 适配云环境限制：云服务商通常不支持自定义外网虚拟 IP（keepalived 依赖虚拟 IP 实现自动切换），而手动切换 Nginx 配置可规避此问题；
• 平衡成本与可用性：双节点部署成本低，且 “分钟级恢复” 可满足内部开发场景的可用性需求。

不选择 keepalived 的原因：

• 云环境限制：主流云厂商（如阿里云、腾讯云）不允许自定义外网可访问的虚拟 IP，keepalived 的 “虚拟 IP 漂移” 功能无法生效；
• 操作复杂度：内网环境虽可使用 keepalived，但需额外配置 VRRP 协议、健康检查脚本，增加运维成本。

三、环境准备与前置依赖配置

3.1 服务器硬件与系统配置

本次部署使用 3 台 CentOS-7.9 虚拟机，具体配置如下表所示，各节点角色与资源要求均经过实践验证：

系统版本	IP 地址	节点角色	CPU 要求	内存要求	Hostname	核心作用
CentOS-7.9	192.168.10.101	Nginx 代理节点	≥2 核	≥2G	Nginx	提供统一访问入口，转发请求到 Harbor 节点
CentOS-7.9	192.168.10.102	Harbor1 节点	≥2 核	≥2G	Docker01	主镜像仓库节点，存储与管理镜像
CentOS-7.9	192.168.10.103	Harbor2 节点	≥2 核	≥2G	Docker02	备用镜像仓库节点，与 Harbor1 双向同步数据

资源要求说明：

• CPU≥2 核：Harbor 运行时需启动多个核心组件（API 服务、数据库、缓存、日志等），单核 CPU 会导致组件竞争资源，出现响应缓慢问题；
• 内存≥2G：Docker 容器、Harbor 核心服务（如 API Server、Registry）均需占用内存，内存不足会导致服务频繁崩溃。

3.2 前置依赖安装：Docker

所有节点必须提前安装 Docker，因为 Harbor 的所有组件均以 Docker 容器形式运行。安装步骤参考 Docker 官方文档（https://docs.docker.com/engine/install/centos/），核心验证命令：

# 检查Docker是否安装成功
docker --version  
# 确保Docker服务正常运行
systemctl status docker  

四、Harbor 节点部署全流程（以 Harbor1 为例）

4.1 下载与解压 Harbor 安装包

Harbor 提供离线安装包（包含所有依赖镜像），适合内网环境部署。本次选择 v2.4.3 版本，下载地址：
https://github.com/goharbor/harbor/releases/tag/v2.4.3，具体步骤：

# 上传离线安装包到服务器
[root@localhost ~]# ls  
harbor-offline-installer-v2.4.3.tgz  # 解压安装包
[root@localhost ~]# tar -zxvf harbor-offline-installer-v2.4.3.tgz  
[root@localhost ~]# cd harbor  
[root@localhost harbor]# ls  
common.sh  harbor.v2.4.3.tar.gz  harbor.yml.tmpl  install.sh  LICENSE  prepare  

4.2 核心配置文件修改（harbor.yml）

Harbor 的配置依赖harbor.yml文件，需从模板拷贝并修改关键参数：

# 拷贝配置模板
[root@localhost harbor]# cp harbor.yml.tmpl harbor.yml  # 编辑配置文件
[root@localhost harbor]# vim harbor.yml  

关键配置项说明：

# 节点唯一标识（必须为当前节点IP，用于镜像访问与复制）
hostname: 192.168.10.102  # 管理员初始密码（生产环境需设置强密码，如包含大小写、数字、特殊字符）
harbor_admin_password: pwd123  # 临时关闭HTTPS（后续由Nginx统一处理，生产环境需启用HTTPS）
#https:# https port for harbor, default is 443
#  port: 443# The path of cert and key files for nginx
#  certificate: /your/certificate/path
#  private_key: /your/private/key/path

配置注意事项：

• hostname必须正确配置为节点 IP 或域名，否则镜像 tag 会包含错误地址，导致拉取失败；
• HTTPS 配置暂时注释的原因：简化初期部署，后续可通过 Nginx 统一配置 HTTPS，避免每个 Harbor 节点单独配置证书的麻烦。

4.3 安装 docker-compose 依赖

Harbor 由多个关联容器（如 API 服务、数据库、Registry、日志服务等）组成，需通过docker-compose实现容器编排与生命周期管理。安装步骤：

# 下载docker-compose二进制文件
[root@localhost ~]# curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose  # 赋予执行权限
[root@localhost ~]# chmod 755 /usr/local/bin/docker-compose  # 验证安装
[root@localhost ~]# docker-compose --version  
docker-compose version 1.26.2, build eefe0d31  

4.4 启动 Harbor 服务

通过官方安装脚本启动 Harbor，脚本会自动完成镜像加载、配置生成、容器启动等流程：

[root@localhost harbor]# ./install.sh  

启动流程解析：

1. 环境检查：验证 Docker 与 docker-compose 是否安装成功；
2. 镜像加载：将离线包中的harbor.v2.4.3.tar.gz镜像导入本地 Docker；
3. 配置生成：根据harbor.yml生成各组件（Nginx、Core、DB 等）的配置文件；
4. 容器启动：通过docker-compose创建并启动所有服务容器。

启动成功验证：

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

此时通过浏览器访问http://192.168.10.102，可看到 Harbor 登录界面，使用默认用户名admin和配置的密码pwd123即可登录。

五、Nginx 代理节点部署与配置

Nginx 节点的核心作用是提供统一访问入口，并在 Harbor 节点故障时通过修改配置实现手动切换。

5.1 拉取 Nginx 镜像与创建配置文件

# 拉取指定版本的Nginx镜像（版本稳定性经过生产验证）
[root@m1 ~]# docker pull nginx:1.13.12  # 创建配置文件目录并编写配置
[root@m1 ~]# mkdir nginx  
[root@m1 ~]# cd nginx  
[root@m1 nginx]# vim nginx.conf  

5.2 Nginx 核心配置解析

user nginx;
worker_processes 1;  # 单进程足够支撑中小型企业内部访问需求error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;events {worker_connections 1024;  # 最大并发连接数，可根据实际访问量调整
}# 使用stream模块实现四层TCP代理（适配Docker镜像的TCP协议传输）
stream {# 定义上游服务组（初始代理到Harbor1节点）upstream hub{server 192.168.10.102:80;  }# 代理服务配置server {listen 80;  # 监听80端口，与Harbor节点端口保持一致proxy_pass hub;  # 转发请求到上游服务组proxy_timeout 300s;  # 长连接超时时间（适配大镜像传输）proxy_connect_timeout 5s;  # 连接超时时间}
}

配置关键点说明：

• 使用 stream 模块：Docker 镜像拉取 /push 基于 TCP 协议，需用 stream 模块而非 http 模块；
• 仅代理单节点的原因：Harbor 节点间镜像同步存在延迟（尤其是大型镜像），若代理两个节点会出现 “推送至 A 节点后，Nginx 转发请求到 B 节点导致拉取失败” 的问题；
• 手动切换逻辑：当192.168.10.102故障时，修改upstream hub为server 192.168.10.103:80;，重启 Nginx 即可切换到备用节点。

5.3 启动 Nginx 容器

通过脚本快速启动 Nginx 容器，确保配置文件正确挂载：

# 创建启动脚本
[root@m1 nginx]# vim restart.sh  
#!/bin/bash
# 停止并删除旧容器（若存在）
docker stop harbor-nginx  
docker rm harbor-nginx  # 启动新容器：使用宿主机网络，挂载本地配置文件
docker run -itd --net=host --name harbor-nginx -v /root/nginx/nginx.conf:/etc/nginx/nginx.conf nginx:1.13.12  # 执行脚本启动Nginx
[root@m1 ~/nginx]# sh restart.sh  

启动参数说明：

• --net=host：让 Nginx 直接使用宿主机网络，避免端口映射导致的协议适配问题；
• -v /root/nginx/nginx.conf:/etc/nginx/nginx.conf：将本地配置文件挂载到容器内，修改配置后无需重建镜像，重启容器即可生效。

六、Harbor 节点双向复制配置（核心高可用保障）

双向复制是实现数据冗余的关键，确保任一节点的镜像变更能同步到另一节点，避免单节点故障导致数据丢失。

6.1 配置 Harbor1 到 Harbor2 的复制规则

步骤 1：添加目标仓库（Harbor2 节点）

登录 Harbor1 的 Web 界面（http://192.168.10.102），进入 “仓库管理”→“新建目标”，配置如下：

• 提供者：选择 “Harbor”（目标为另一 Harbor 节点）；
• 目标名：192.168.10.103（清晰标识目标节点 IP）；
• 目标 URL：http://192.168.10.103（Harbor2 节点的访问地址）；
• 访问 ID：admin（Harbor2 的管理员用户名）；
• 访问密码：pwd123（Harbor2 的管理员密码）；
• 点击 “测试连接”，提示 “连接成功” 后保存。

步骤 2：创建复制规则

进入 “复制管理”→“新建规则”，配置如下：

• 名称：to192.168.10.103（标识复制方向）；
• 复制模式：Push-based（本地镜像新增 / 删除时主动推送到目标）；
• 源资源过滤器：默认复制全部镜像（可按名称、Tag 过滤，如仅复制prod-*标签镜像）；
• 目标仓库：选择步骤 1 创建的目标（192.168.10.103）；
• 目标名称空间：选择 “替换 1 级”（保持与源仓库一致的项目结构）；
• 触发模式：事件驱动（镜像推送 / 删除时自动触发复制）；
• 点击 “保存” 完成配置。

6.2 配置 Harbor2 到 Harbor1 的复制规则

重复 6.1 的步骤，在 Harbor2 节点（http://192.168.10.103）中添加目标仓库（Harbor1 节点http://192.168.10.102），并创建复制规则to192.168.10.102，实现 “双向复制”。

6.3 复制规则核心参数说明

• 复制模式：Push-based（主动推送）适合镜像源节点，确保本地变更及时同步；若需从目标节点拉取镜像，可选择Pull-based（被动拉取）；
• 触发模式：事件驱动可实时同步，适合频繁更新场景；若镜像更新频率低，也可选择 “定时触发”（如每天凌晨同步）；
• 资源过滤器：通过名称、Tag 过滤可减少无效同步（如仅同步生产环境镜像，忽略测试镜像）。

6.4 复制效果验证

步骤 1：在 Harbor1 创建项目并推送镜像

• 登录 Harbor1，进入 “项目”→“新建项目”，名称为kubernetes（公开项目）；

• 在客户端配置 Docker 信任私有仓库（需在所有访问 Harbor 的 Docker 主机上操作）：

  [root@localhost ~]# vim /etc/docker/daemon.json  
  {"insecure-registries": ["192.168.10.101"]  # Nginx代理节点IP
  }  
  [root@localhost ~]# systemctl daemon-reload  
  [root@localhost ~]# systemctl restart docker  
  

• 登录仓库并推送镜像：

  [root@localhost ~]# docker login 192.168.10.101  # 登录Nginx代理地址
  Username: admin  
  Password: pwd123  
  Login Succeeded  # 标记并推送镜像
  [root@localhost ~]# docker pull cirros  
  [root@localhost ~]# docker tag cirros 192.168.10.101/kubernetes/cirros:v1  
  [root@localhost ~]# docker push 192.168.10.101/kubernetes/cirros:v1  
  

步骤 2：检查 Harbor2 的同步结果

登录 Harbor2 的 Web 界面（http://192.168.10.103），进入 “项目”，可看到自动同步的kubernetes项目及项目下的cirros:v1镜像，表明复制成功。

七、全流程功能验证与故障切换演练

7.1 基础功能验证

• 登录验证：通过 Nginx 代理地址（http://192.168.10.101）登录 Harbor，确认可正常访问；
• 推送验证：客户端推送镜像到192.168.10.101/kubernetes，确认 Harbor1 节点可接收；
• 拉取验证：另一客户端从192.168.10.101/kubernetes拉取镜像，确认成功下载；
• 复制验证：检查 Harbor2 节点是否同步到推送的镜像。

7.2 故障切换演练（模拟 Harbor1 节点故障）

• 步骤 1

  ：手动停止 Harbor1 节点的服务（模拟故障）：

  [root@localhost harbor]# docker-compose down  
  

• 步骤 2

  ：修改 Nginx 配置，切换代理目标到 Harbor2：

  [root@m1 nginx]# vim nginx.conf  
  stream {upstream hub{server 192.168.10.103:80;  # 改为Harbor2节点IP}# 其他配置不变
  }  
  

• 步骤 3

  ：重启 Nginx 生效配置：

  [root@m1 ~/nginx]# sh restart.sh  
  

• 步骤 4：验证切换效果：客户端从192.168.10.101拉取kubernetes/cirros:v1镜像，确认可正常拉取（数据来自 Harbor2 节点）。

八、方案总结与生产环境优化建议

8.1 方案优势与适用场景

• 优势：架构简单、部署成本低、数据冗余可靠，适合中小型企业内部镜像管理；
• 适用场景：内部开发 / 测试环境、非核心生产环境，可接受分钟级故障恢复的场景。

8.2 生产环境优化建议

• 启用 HTTPS：在 Nginx 层配置 SSL 证书，将stream模块改为http模块并启用 HTTPS，避免镜像传输过程中被窃听；
• 增加监控告警：通过 Prometheus 监控 Harbor 节点状态与磁盘使用率，配置告警避免磁盘满导致服务异常；
• 定期备份：定期备份 Harbor 的数据库与镜像存储目录，防止复制失效导致的数据丢失；
• 权限细化：通过 “用户管理” 与 “项目成员” 配置，实现开发、测试、运维人员的权限隔离，避免误操作；
• 镜像清理策略：配置定时 GC（垃圾回收）任务，删除过期镜像释放存储空间。