Harbor私有容器仓库搭建与高可用部署实战

1. 项目概述

作为一名长期奋战在运维一线的老兵，我深知私有容器仓库对于企业DevOps流程的重要性。今天想和大家分享一个实战经验——如何从零开始搭建Harbor私有仓库。不同于官方文档的平铺直叙，我会结合自己踩过的坑，带大家走通整个部署流程。

Harbor作为CNCF毕业项目，是目前最成熟的企业级容器Registry解决方案。它提供了镜像管理、漏洞扫描、RBAC权限控制等企业级功能。在我的生产环境中，Harbor已经稳定运行了3年多，日均处理上千次镜像拉取请求。下面就以v2.14.2版本为例，演示如何构建一个高可用的私有仓库。

提示：本文操作基于CentOS 7.9系统，所有步骤都经过生产验证。如果你使用的是其他Linux发行版，部分命令可能需要调整。

2. 环境准备

2.1 基础环境配置

首先需要准备一台干净的虚拟机（建议4C8G配置）。我这里直接克隆了已有的Docker环境虚拟机，省去了安装Docker的步骤。关键配置如下：

bash复制# 修改主机名
hostnamectl set-hostname harbor
# 配置静态IP（根据你的网络环境调整）
nmcli con mod eth0 ipv4.addresses 192.168.64.134/24
nmcli con mod eth0 ipv4.gateway 192.168.64.1
nmcli con mod eth0 ipv4.dns "8.8.8.8"
nmcli con mod eth0 ipv4.method manual
nmcli con up eth0

# 关闭防火墙和SELinux（生产环境建议配置规则而非直接关闭）
systemctl stop firewalld && systemctl disable firewalld
setenforce 0
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config

2.2 Docker环境检查

确认Docker版本和配置：

bash复制[root@harbor ~]# docker -v
Docker version 29.1.5, build 0e6fee6

# 检查加速器配置
cat /etc/docker/daemon.json
{
    "default-ipc-mode": "shareable",
    "data-root": "/data/docker",
    "exec-opts": ["native.cgroupdriver=systemd"],
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "100m",
        "max-file": "50"
    },
    "registry-mirrors": [
        "https://docker.1ms.run",
        "https://func.ink"
    ]
}

注意：生产环境建议配置合理的日志轮转策略，避免日志爆盘。我的配置是单个日志文件最大100MB，保留50个历史文件。

3. Harbor安装部署

3.1 安装docker-compose

Harbor依赖docker-compose进行服务编排。由于官方源下载较慢，建议提前下载好二进制包：

bash复制wget https://github.com/docker/compose/releases/download/v5.0.2/docker-compose-linux-x86_64
mv docker-compose-linux-x86_64 /usr/bin/docker-compose
chmod +x /usr/bin/docker-compose
docker-compose -v  # 验证版本

3.2 下载Harbor离线包

从GitHub下载离线安装包（约600MB）：

bash复制wget https://github.com/goharbor/harbor/releases/download/v2.14.2/harbor-offline-installer-v2.14.2.tgz
tar -zxf harbor-offline-installer-v2.14.2.tgz -C /data/

3.3 生成SSL证书

为了安全考虑，强烈建议配置HTTPS访问。以下是自签名证书生成过程：

bash复制# 创建证书目录
mkdir -p /data/harbor/ssl && cd /data/harbor/ssl

# 生成CA证书
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
 -subj "/C=CN/ST=Beijing/L=Beijing/O=Example/OU=IT/CN=harbor.example.com" \
 -key ca.key \
 -out ca.crt

# 生成服务器证书
openssl genrsa -out harbor.example.com.key 4096
openssl req -sha512 -new \
    -subj "/C=CN/ST=Beijing/L=Beijing/O=Example/OU=IT/CN=harbor.example.com" \
    -key harbor.example.com.key \
    -out harbor.example.com.csr

# 创建证书扩展文件
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.example.com
DNS.2=harbor
EOF

# 生成最终证书
openssl x509 -req -sha512 -days 3650 \
    -extfile v3.ext \
    -CA ca.crt -CAkey ca.key -CAcreateserial \
    -in harbor.example.com.csr \
    -out harbor.example.com.crt

3.4 配置Harbor

复制配置文件模板并修改关键参数：

bash复制cd /data/harbor
cp harbor.yml.tmpl harbor.yml
vim harbor.yml

主要修改以下参数：

yaml复制hostname: harbor.example.com
https:
  port: 443
  certificate: /data/harbor/ssl/harbor.example.com.crt
  private_key: /data/harbor/ssl/harbor.example.com.key
data_volume: /data/harbor/data

3.5 安装Harbor

执行安装脚本：

bash复制./install.sh

安装完成后，检查容器状态：

bash复制docker-compose ps

4. 访问配置

4.1 本地DNS配置

在客户端机器上配置hosts解析：

bash复制# Linux/Mac
echo "192.168.64.134 harbor.example.com" >> /etc/hosts

# Windows
# 编辑 C:\Windows\System32\drivers\etc\hosts 添加相同记录

4.2 信任自签名证书

将CA证书导入系统信任库：

bash复制# CentOS/RHEL
cp /data/harbor/ssl/ca.crt /etc/pki/ca-trust/source/anchors/
update-ca-trust

# Ubuntu/Debian
cp /data/harbor/ssl/ca.crt /usr/local/share/ca-certificates/
update-ca-certificates

4.3 登录Harbor

浏览器访问 https://harbor.example.com，使用默认账号：

• 用户名：admin
• 密码：Harbor12345

首次登录后请立即修改密码。

5. 镜像管理实战

5.1 配置Docker客户端

在需要推送镜像的机器上配置：

bash复制mkdir -p /etc/docker/certs.d/harbor.example.com
scp root@harbor:/data/harbor/ssl/ca.crt /etc/docker/certs.d/harbor.example.com/
systemctl restart docker

5.2 推送镜像示例

bash复制# 登录仓库
docker login harbor.example.com -u admin -p yourpassword

# 拉取测试镜像
docker pull nginx:alpine

# 打标签
docker tag nginx:alpine harbor.example.com/library/nginx:alpine

# 推送镜像
docker push harbor.example.com/library/nginx:alpine

5.3 镜像同步策略

Harbor支持多种同步策略：

1. 手动同步：通过UI手动触发
2. 定时同步：配置cron表达式
3. 事件驱动：通过webhook自动同步

配置示例：

yaml复制# 在harbor.yml中添加
jobservice:
  replication: 
    workers: 3
    max_jobs: 10

6. 高可用方案

6.1 数据库高可用

建议使用外部数据库：

yaml复制external_database:
  harbor:
    host: harbor-db.example.com
    port: 5432
    db_name: registry
    username: postgres
    password: yourpassword
  clair:
    host: clair-db.example.com
    port: 5432
    db_name: clair
    username: postgres
    password: yourpassword

6.2 存储后端配置

推荐使用S3兼容存储：

yaml复制storage_service:
  s3:
    accesskey: your_access_key
    secretkey: your_secret_key
    region: us-west-1
    bucket: your-bucket-name
    endpoint: https://s3.example.com

6.3 多节点部署

通过配置多个Harbor实例共享后端存储和数据库实现横向扩展：

bash复制# 在所有节点上执行
./install.sh --with-clair --with-chartmuseum

7. 运维管理

7.1 日常维护命令

bash复制# 停止Harbor
docker-compose down

# 启动Harbor
docker-compose up -d

# 查看日志
docker-compose logs -f

# 备份数据
tar czvf harbor-backup-$(date +%Y%m%d).tar.gz /data/harbor

7.2 监控配置

Harbor内置了Prometheus指标端点，可以配置Grafana监控面板。关键指标包括：

• 镜像推送/拉取次数
• 存储空间使用量
• API请求延迟
• 数据库连接数

7.3 常见问题排查

1. 推送镜像失败

   • 检查docker daemon日志：journalctl -u docker -f
   • 确认证书配置正确
   • 检查仓库配额是否已满

2. Web界面无法访问

   • 检查nginx容器是否正常运行
   • 确认防火墙放行了443端口
   • 查看nginx日志：docker logs nginx

3. 数据库连接问题

   • 检查PostgreSQL容器状态
   • 验证数据库连接参数
   • 查看数据库日志：docker logs harbor-db

8. 安全加固建议

1. 定期轮换证书

   bash复制# 重新生成证书后执行
   docker-compose down
   docker-compose up -d
   

2. 启用内容信任

   yaml复制# harbor.yml
   content_trust:
     enabled: true
   

3. 配置漏洞扫描

   bash复制./install.sh --with-clair
   

4. 审计日志配置

   yaml复制audit_log:
     enabled: true
     path: /var/log/harbor/audit.log
   

经过以上步骤，你应该已经成功部署了一个功能完善的Harbor私有仓库。在实际生产环境中，建议结合CI/CD流水线使用，实现镜像的自动化构建和部署。如果在实施过程中遇到任何问题，欢迎在评论区交流讨论。