Docker镜像仓库Harbor安装部署全流程指南

2025年10月31日 互联网

Docker镜像仓库Harbor安装部署详细教程

一、Harbor简介与核心价值

Harbor是由VMware公司开源的企业级Docker镜像仓库，提供基于角色的访问控制、镜像复制、漏洞扫描、审计日志等企业级功能。相较于原生Docker Registry，Harbor通过Web界面管理、权限控制和数据备份能力，解决了企业私有镜像仓库的安全性和可管理性痛点。

核心功能亮点

  1. RBAC权限模型：支持项目级权限划分，可定义管理员、开发者、访客等角色
  2. 镜像复制：支持多实例间的镜像同步，构建分布式镜像仓库网络
  3. 漏洞扫描：集成Clair引擎自动检测镜像中的CVE漏洞
  4. 审计日志：完整记录用户操作行为，满足合规性要求
  5. AD/LDAP集成：支持与企业身份认证系统对接

二、安装环境准备

硬件配置要求

组件 最低配置 推荐配置
CPU 2核 4核及以上
内存 4GB 8GB及以上
磁盘空间 40GB 100GB+（根据镜像量调整）
网络带宽 100Mbps 千兆网络

软件依赖清单

  1. 操作系统：CentOS 7/8、Ubuntu 18.04/20.04等主流Linux发行版
  2. Docker引擎：19.03+版本（需开启TCP监听） 
    1. # 安装Docker CE示例（Ubuntu）
    2. curl -fsSL https://get.docker.com | sh
    3. sudo systemctl enable --now docker
  3. Docker Compose：1.25+版本 
    1. sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
    2. sudo chmod +x /usr/local/bin/docker-compose
  4. 依赖包： 
    1. # CentOS示例
    2. sudo yum install -y wget curl git

网络配置要点

  1. 开放80（HTTP）、443（HTTPS）、4443（控制台）端口
  2. 配置防火墙规则： 
    1. sudo firewall-cmd --permanent --add-port={80,443,4443}/tcp
    2. sudo firewall-cmd --reload
  3. 建议配置域名解析（如harbor.example.com）

三、Harbor安装部署流程

1. 下载安装包

  1. wget https://github.com/goharbor/harbor/releases/download/v2.5.3/harbor-offline-installer-v2.5.3.tgz
  2. tar xvf harbor-offline-installer-v2.5.3.tgz
  3. cd harbor

2. 配置文件修改

编辑harbor.yml核心配置文件：

  1. # 修改主机名（必须配置）
  2. hostname: harbor.example.com
  4. # HTTPS配置（生产环境必须）
  5. https:
  6.   certificate: /data/cert/harbor.crt
  7.   private_key: /data/cert/harbor.key
  9. # 存储驱动配置（支持filesystem/s3/swift等）
  10. storage_driver:
  11.   name: filesystem
  12.   settings:
  13.     rootdirectory: /data/registry
  15. # 数据库配置（内置PostgreSQL）
  16. database:
  17.   password: root123
  18.   max_idle_conns: 50
  19.   max_open_conns: 100
  21. # 管理员密码
  22. harbor_admin_password: Harbor12345

3. 证书生成（HTTPS场景）

  1. # 创建证书目录
  2. sudo mkdir -p /data/cert
  3. cd /data/cert
  5. # 生成自签名证书（生产环境应使用CA签发证书）
  6. openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  7.   -keyout harbor.key -out harbor.crt \
  8.   -subj "/C=CN/ST=Beijing/L=Beijing/O=example/CN=harbor.example.com"

4. 执行安装脚本

  1. # 确保Docker Compose在PATH中
  2. export PATH=$PATH:/usr/local/bin
  4. # 执行安装（自动拉取镜像并启动服务）
  5. sudo ./install.sh --with-clair --with-trivy  # 可选组件

5. 服务状态验证

  1. # 查看容器状态
  2. sudo docker-compose -f /path/to/harbor/docker-compose.yml ps
  4. # 检查日志
  5. sudo docker-compose -f /path/to/harbor/docker-compose.yml logs -f

四、Harbor基础使用指南

1. 客户端配置

  1. # 配置Docker信任Harbor
  2. echo "{\"insecure-registries\":[\"harbor.example.com\"]}" > /etc/docker/daemon.json
  3. # 或（HTTPS场景）
  4. echo "{\"registry-mirrors\":[],\"insecure-registries\":[]}" > /etc/docker/daemon.json
  5. sudo systemctl restart docker
  7. # 登录Harbor
  8. docker login harbor.example.com

2. 镜像操作示例

  1. # 推送镜像
  2. docker tag nginx:latest harbor.example.com/library/nginx:v1
  3. docker push harbor.example.com/library/nginx:v1
  5. # 拉取镜像
  6. docker pull harbor.example.com/library/nginx:v1

3. Web控制台功能

  1. 项目管理：创建项目并设置访问权限
  2. 仓库管理：查看镜像列表、标签、漏洞扫描结果
  3. 系统管理：配置复制规则、垃圾回收、邮件通知
  4. 用户管理：添加用户、分配角色

五、高级运维管理

1. 数据备份与恢复

  1. # 备份配置（需停止服务）
  2. sudo docker-compose -f docker-compose.yml down
  3. tar czvf harbor_backup_$(date +%Y%m%d).tar.gz \
  4.   /data/database \
  5.   /data/registry \
  6.   /path/to/harbor/common/config
  8. # 恢复流程（反向操作）

2. 性能优化建议

  1. 存储优化：

    • 使用SSD存储镜像数据
    • 配置存储类（如NFS）实现共享存储

  2. 数据库调优：

    1. # 在harbor.yml中修改
    2. database:
    3.   max_idle_conns: 100
    4.   max_open_conns: 200
    5.   pool_timeout: 30

  3. 缓存配置：

    • 配置镜像层缓存
    • 启用Redis作为会话存储

3. 监控方案

  1. Prometheus集成： 
    1. # 启用metrics接口
    2. metrics:
    3.   enabled: true
    4.   port: 9090
  2. Grafana仪表盘：导入Harbor官方Dashboard模板
  3. 日志收集：配置Filebeat收集容器日志

六、常见问题解决方案

1. 登录失败排查

  1. 检查/etc/docker/daemon.json配置
  2. 验证证书有效性： 
    1. openssl s_client -connect harbor.example.com:443 -showcerts
  3. 查看Harbor核心日志： 
    1. sudo docker logs harbor-core

2. 镜像推送超时

  1. 调整Docker客户端超时设置： 
    1. echo '{"max-concurrent-uploads": 10}' > /etc/docker/daemon.json
  2. 检查网络带宽和存储性能

3. 数据库连接问题

  1. 验证PostgreSQL容器状态： 
    1. sudo docker ps | grep postgresql
  2. 检查数据库配置： 
    1. # 确认harbor.yml中的配置
    2. database:
    3.   password: root123
    4.   host: postgresql
    5.   port: 5432

七、升级与维护

1. 版本升级流程

  1. # 1. 备份数据
  2. # 2. 下载新版本安装包
  3. # 3. 修改harbor.yml（保持原有配置）
  4. # 4. 执行升级命令
  5. sudo ./prepare --with-clair --with-trivy
  6. sudo docker-compose -f docker-compose.yml up -d

2. 垃圾回收操作

  1. # 进入harbor-core容器
  2. sudo docker exec -it harbor-core bash
  4. # 执行垃圾回收
  5. python /harbor/upgrade_entries.py gc --force

3. 证书更新流程

  1. # 1. 生成新证书
  2. # 2. 更新harbor.yml配置
  3. # 3. 重新运行prepare脚本
  4. sudo ./prepare
  6. # 4. 重启服务
  7. sudo docker-compose -f docker-compose.yml down
  8. sudo docker-compose -f docker-compose.yml up -d

八、最佳实践建议

  1. 高可用架构：

    • 部署多个Harbor实例组成集群
    • 配置双向复制策略实现数据同步

  2. 安全加固：

    • 启用双因素认证
    • 定期轮换管理员密码
    • 限制项目创建权限

  3. 镜像管理：

    • 实施镜像保留策略（自动清理旧版本）
    • 启用镜像签名验证
    • 建立基础镜像白名单

  4. 运维自动化：

    • 使用Ansible/Terraform实现自动化部署
    • 集成CI/CD流水线实现镜像自动推送
    • 配置告警规则监控关键指标

通过本文的详细指导，开发者可以完成从环境准备到生产级Harbor仓库的完整部署。实际部署过程中，建议先在测试环境验证配置，再逐步迁移到生产环境。Harbor的强大功能组合能够有效解决企业级Docker镜像管理的安全性和效率问题，为容器化应用提供可靠的镜像存储基础。

最新文章