Harbor私有镜像仓库无坑搭建指南

一、引言：为何选择Harbor？

在容器化部署成为主流的今天，私有镜像仓库成为企业保障镜像安全、提升交付效率的核心基础设施。Harbor作为CNCF（云原生计算基金会）毕业项目，凭借其多租户管理、镜像复制、漏洞扫描、RBAC权限控制等企业级功能，成为开发者构建私有镜像仓库的首选方案。然而，实际搭建过程中常因环境配置不当、证书问题或参数错误导致”踩坑”。本文将从环境准备、安装部署、配置优化、故障排查四个维度，提供一套”无坑”的完整指南。

二、环境准备：前置条件与兼容性验证

1. 硬件与系统要求

硬件配置：建议4核CPU、8GB内存、50GB磁盘空间（基础配置，生产环境需按镜像量扩容）。
操作系统：支持CentOS 7/8、Ubuntu 18.04/20.04、RHEL 7/8等主流Linux发行版，需关闭SELinux或配置为Permissive模式。
依赖组件：Docker（建议19.03+）、Docker Compose（建议1.25+）、Python 3.6+（用于Harbor脚本）。

2. 网络与域名配置

域名解析：Harbor必须通过域名访问（如harbor.example.com），需在/etc/hosts或DNS服务器中配置解析。
端口开放：默认使用80（HTTP）、443（HTTPS）、4443（Notary服务，可选），需在防火墙中放行。
负载均衡：生产环境建议通过Nginx或HAProxy配置SSL终止和负载均衡。

3. 证书生成（关键步骤）

Harbor强制使用HTTPS，需生成自签名证书或CA签发的证书：

# 生成CA私钥和证书
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -subj "/CN=harbor-ca" -days 3650 -out ca.crt
# 生成服务器私钥和证书签名请求(CSR)
openssl genrsa -out server.key 4096
openssl req -new -key server.key -subj "/CN=harbor.example.com" -out server.csr
# 使用CA签发服务器证书
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650 -sha256

将server.crt和server.key复制到Harbor的/common/config/shared/trust-certificates/目录（Harbor 2.0+）。

三、安装部署：从离线包到在线安装

1. 离线安装（推荐生产环境）

下载离线包：从GitHub Release页面下载对应版本的harbor-offline-installer-xxx.tgz。

解压并修改配置：

tar xvf harbor-offline-installer-xxx.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml

编辑harbor.yml，重点配置以下参数：

hostname: harbor.example.com
https:
  certificate: /path/to/server.crt
  private_key: /path/to/server.key
harbor_admin_password: Harbor12345  # 初始管理员密码
database:
  password: root123  # PostgreSQL密码
data_volume: /data/harbor  # 数据存储路径

执行安装脚本：

./install.sh --with-trivy  # 启用漏洞扫描（可选）

2. 在线安装（快速测试）

通过Docker Compose直接拉取镜像安装：

curl -L https://github.com/goharbor/harbor/releases/download/v2.5.0/harbor-online-installer-v2.5.0.tgz | tar xz
cd harbor
cp harbor.yml.tmpl harbor.yml
# 修改hostname、https等配置后执行
./prepare
docker-compose up -d

四、配置优化：企业级实践

1. 存储后端配置

Harbor支持多种存储驱动，生产环境推荐使用对象存储（如MinIO、AWS S3）或分布式文件系统（如CephFS）：

# 在harbor.yml中配置存储驱动
storage_driver:
  name: s3
  s3:
    accesskey: minioadmin
    secretkey: minioadmin
    region: us-east-1
    regionendpoint: http://minio.example.com
    bucket: harbor-artifacts
    encrypt: false

2. 复制策略与多集群同步

通过系统管理→复制管理创建跨集群镜像同步规则，示例配置：

源项目：library/nginx
目标端点：另一Harbor实例的API地址
触发模式：手动/定时/事件触发

3. 漏洞扫描集成（Trivy）

Harbor 2.0+内置Trivy扫描器，需在harbor.yml中启用：

trivy:
  ignore_unfixed: false
  skip_update: false
  insecure: false

扫描结果可通过项目→镜像→漏洞标签页查看，支持按严重等级过滤。

五、故障排查：常见问题解决方案

1. 502 Bad Gateway错误

原因：Nginx代理无法连接Harbor核心服务。
解决：
1. 检查docker-compose logs -f nginx日志。
2. 确认Harbor核心服务（docker-compose ps）是否运行。
3. 重启服务：docker-compose down && docker-compose up -d。

2. 镜像推送失败（x509证书错误）

原因：客户端未信任Harbor的自签名证书。
解决：
1. 将ca.crt分发到客户端的/etc/docker/certs.d/harbor.example.com/目录。
2. 重启Docker服务：systemctl restart docker。

3. 管理员密码重置

若忘记管理员密码，可通过以下步骤重置：

# 进入Harbor的PostgreSQL容器
docker exec -it harbor-db psql -U postgres -d registry
# 执行SQL更新密码（明文密码需先通过Harbor的加密工具处理）
UPDATE harbor_user SET password='...' WHERE username='admin';

或使用Harbor提供的reset-password.sh脚本（需停止服务后执行）。

六、总结：无坑搭建的核心原则

环境一致性：确保开发、测试、生产环境配置相同。
证书管理：优先使用CA签发的证书，避免自签名证书的信任链问题。
备份策略：定期备份/data/harbor目录和数据库。
监控告警：集成Prometheus+Grafana监控Harbor的API响应时间、存储使用率等指标。

通过遵循本文的步骤，开发者可高效完成Harbor私有镜像仓库的搭建，避免常见陷阱，为企业的容器化部署提供稳定可靠的镜像管理基础。