Harbor离线部署实战：从零搭建私有镜像仓库

最新推荐文章于 2026-05-13 05:28:44 发布

原创最新推荐文章于 2026-05-13 05:28:44 发布 · 923 阅读

8 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#Harbor #离线安装 #私有镜像仓库

1. 为什么需要私有镜像仓库

在企业级开发环境中，使用公共镜像仓库存在诸多限制。首先是安全性问题，公共仓库的镜像来源不可控，可能存在恶意代码或漏洞风险。其次是稳定性问题，依赖外网访问会导致构建流程不可控。最后是性能问题，每次拉取镜像都需要从外网下载，严重影响CI/CD效率。

私有镜像仓库就像是你家里的专属冰箱，所有食材（镜像）都经过严格检查，随时取用不受外界干扰。Harbor作为企业级Registry解决方案，提供了镜像同步、漏洞扫描、权限控制等高级功能，特别适合金融、政务等对安全要求高的场景。

我在某金融机构的项目中就遇到过这样的痛点：每次Jenkins构建都要从外网拉取基础镜像，不仅耗时还经常因网络问题失败。后来部署Harbor后，构建时间从原来的15分钟缩短到3分钟，稳定性也大幅提升。

2. 环境准备与离线包获取

2.1 基础环境检查

在开始之前，请确保你的服务器满足以下条件：

操作系统：CentOS 7.6+ 或 Ubuntu 18.04+
内存：至少8GB（4GB可能启动失败）
磁盘空间：100GB以上（镜像很占空间）
Docker版本：20.10.5+
Docker Compose：v2.2.2+

可以用这些命令检查环境：

# 检查内核版本
uname -r
# 检查Docker状态
docker version
docker-compose version

2.2 离线包获取技巧

Harbor提供两种安装包：

在线包（10MB左右）：安装时下载镜像
离线包（1GB左右）：包含所有依赖镜像

在内网环境我们当然选择离线包。获取最新版离线包的三种方式：

通过有外网的机器下载：

wget https://github.com/goharbor/harbor/releases/download/v2.6.1/harbor-offline-installer-v2.6.1.tgz

使用CDN加速链接（国内访问更快）
从其他环境导出现有Harbor的镜像包

建议下载后校验SHA256值，避免文件损坏：

sha256sum harbor-offline-installer-v2.6.1.tgz

3. 证书配置实战

3.1 自签名证书生成

生产环境建议使用正规CA证书，测试环境可以用OpenSSL自签证书。这里有个坑要注意：证书必须包含Subject Alternative Name (SAN)，否则Docker会报错。

完整生成流程：

# 创建证书目录
mkdir -p /usr/local/harbor/certs && cd $_

# 生成CA私钥
openssl genrsa -out ca.key 4096

# 生成CA证书（有效期10年）
openssl req -x509 -new -nodes -sha512 -days 3650 \
 -subj "/C=CN/ST=Shanghai/L=Shanghai/O=YourCompany/OU=IT/CN=harbor.yourdomain.com" \
 -key ca.key \
 -out ca.crt

# 生成服务器私钥
openssl genrsa -out harbor.yourdomain.com.key 4096

# 生成CSR
openssl req -sha512 -new \
 -subj "/C=CN/ST=Shanghai/L=Shanghai/O=YourCompany/OU=IT/CN=harbor.yourdomain.com" \
 -key harbor.yourdomain.com.key \
 -out harbor.yourdomain.com.csr

# 创建v3.ext文件
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.yourdomain.com
DNS.2=harbor
DNS.3=*.yourdomain.com
EOF

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

3.2 证书转换与配置

Docker对证书格式有特殊要求，需要进行转换：

openssl x509 -inform PEM -in harbor.yourdomain.com.crt -out harbor.yourdomain.com.cert

然后在harbor.yml中配置：

https:
  port: 443
  certificate: /usr/local/harbor/certs/harbor.yourdomain.com.crt
  private_key: /usr/local/harbor/certs/harbor.yourdomain.com.key

4. Harbor安装与初始化

4.1 配置文件详解

解压安装包后，重点修改harbor.yml：

hostname: harbor.yourdomain.com  # 必须与证书CN一致

# 数据持久化目录（建议挂载大容量磁盘）
data_volume: /data/harbor

# 数据库配置（生产环境建议外接数据库）
database:
  password: StrongPassword123
  max_idle_conns: 50
  max_open_conns: 100

# 开启漏洞扫描（需要额外存储空间）
trivy:
  skip_update: true  # 离线环境必须设为true

4.2 安装过程

执行安装脚本时建议记录日志，方便排查问题：

tar -zxvf harbor-offline-installer-v2.6.1.tgz
cd harbor
./install.sh --with-trivy --with-chartmuseum | tee install.log

安装成功后你会看到：

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

可以用docker-compose检查服务状态：

docker-compose ps

5. Docker客户端配置

5.1 证书分发

每台需要访问Harbor的Docker主机都需要CA证书：

mkdir -p /etc/docker/certs.d/harbor.yourdomain.com
cp ca.crt /etc/docker/certs.d/harbor.yourdomain.com/

5.2 登录验证

测试登录（首次登录需修改admin密码）：

docker login harbor.yourdomain.com -u admin -p Harbor12345

如果使用HTTP而非HTTPS，需要修改daemon.json：

{
  "insecure-registries": ["harbor.yourdomain.com"]
}

6. 日常维护技巧

6.1 数据备份

Harbor的数据主要包括：

配置文件：/path/to/harbor.yml
数据卷：/data/harbor
数据库：默认在PostgreSQL容器内

建议的备份方案：

# 备份配置和数据
tar -czvf harbor-backup-$(date +%Y%m%d).tar.gz /path/to/harbor.yml /data/harbor

# 备份数据库
docker exec -it harbor-db pg_dump -U postgres registry > registry.sql

6.2 常见问题解决

问题1：docker login报错x509证书错误

检查证书CN与hostname是否一致
确认客户端已正确安装CA证书
检查系统时间是否准确

问题2：磁盘空间不足

定期清理无用镜像：harbor.yml中设置storage_quota
启用垃圾回收：docker-compose stop -> registry garbage-collect

问题3：容器频繁重启

检查日志：docker-compose logs -f
常见内存不足导致OOM，建议增加swap空间

7. 进阶配置建议

7.1 高可用部署

生产环境建议采用：

后端存储：使用S3或分布式文件系统
数据库：外接PostgreSQL集群
多节点部署：通过负载均衡接入

7.2 与CI/CD集成

在Jenkins中配置：

pipeline {
  environment {
    HARBOR_CREDS = credentials('harbor-credential')
  }
  stages {
    stage('Push Image') {
      steps {
        sh '''
          docker login -u $HARBOR_CREDS_USR -p $HARBOR_CREDS_PSW harbor.yourdomain.com
          docker push harbor.yourdomain.com/myproject/app:${BUILD_NUMBER}
        '''
      }
    }
  }
}

记得在Harbor中创建机器人账户专门用于CI/CD，不要直接使用admin账户。