单机Harbor部署全指南：从环境准备到安全运维

2025年11月1日 互联网

单机Harbor部署全指南：从环境准备到安全运维

一、引言：为何选择单机Harbor？

在容器化技术普及的今天，私有镜像仓库已成为企业DevOps流程的核心组件。Harbor作为CNCF（云原生计算基金会）毕业项目，凭借其权限控制、镜像签名、漏洞扫描等企业级功能，成为开发者构建私有Registry的首选。单机部署模式因其资源占用低、配置简单、维护成本低的特点，尤其适合中小团队或测试环境使用。

本文将围绕单机Harbor的部署展开，从环境准备、安装配置到安全加固，提供一套可复用、可扩展的部署方案，帮助开发者在1小时内完成从零到一的搭建。

二、环境准备：基础要求与前置条件

1. 硬件与软件要求

  • 硬件：建议至少2核CPU、4GB内存、20GB磁盘空间（生产环境需根据镜像存储量扩容）。
  • 操作系统：支持Linux（CentOS 7+/Ubuntu 18.04+），本文以CentOS 8为例。
  • 依赖组件：
    • Docker 19.03+（用于运行Harbor容器）
    • Docker Compose 1.25+（Harbor 2.0+默认使用Compose部署）
    • Nginx（可选，用于反向代理）

2. 网络与域名配置

单机Harbor默认使用80/443端口，需确保：

  • 防火墙开放80（HTTP）、443（HTTPS）、22（SSH，可选）端口。
  • 若需HTTPS，需准备域名及SSL证书（自签名或CA签发）。
  • 主机名解析：在/etc/hosts中添加<IP> <hostname>（如192.168.1.100 harbor.example.com）。

3. 安装Docker与Docker Compose

  1. # 安装Docker
  2. sudo yum install -y yum-utils
  3. sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
  4. sudo yum install -y docker-ce docker-ce-cli containerd.io
  5. sudo systemctl enable --now docker
  7. # 安装Docker Compose
  8. sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  9. sudo chmod +x /usr/local/bin/docker-compose

三、Harbor安装与配置

1. 下载Harbor安装包

访问Harbor官方Release页面，选择最新稳定版（如v2.9.0），下载压缩包并解压：

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

2. 配置Harbor

编辑harbor.yml文件，重点修改以下参数：

  1. hostname: harbor.example.com  # 必须与域名一致
  2. http:
  3.   port: 80
  4. https:
  5.   port: 443
  6.   certificate: /data/cert/harbor.crt  # SSL证书路径
  7.   private_key: /data/cert/harbor.key
  8. harbor_admin_password: Harbor12345  # 初始管理员密码
  9. database:
  10.   password: root123  # 数据库密码
  11. data_volume: /data  # 数据存储目录

关键配置说明：

  • hostname：必须与访问域名一致，否则会导致Cookie或API调用失败。
  • 数据存储：建议使用独立磁盘或分布式存储（如NFS），避免与系统盘混用。
  • 密码安全：生产环境需使用强密码，并通过./prepare脚本加密存储。

3. 安装与启动

执行安装脚本，Harbor会自动拉取镜像并启动服务：

  1. sudo mkdir -p /data/cert  # 创建证书目录（若使用HTTPS）
  2. sudo ./install.sh

安装完成后，通过docker-compose ps验证服务状态：

  1. $ docker-compose ps
  2. Name                     Command               State           Ports
  3. ----------------------------------------------------------------------------------
  4. harbor-core         /harbor/harbor_core          Up
  5. harbor-db           /docker-entrypoint.sh mysqld  Up
  6. harbor-jobservice   /harbor/harbor_jobservice   Up
  7. harbor-log          /bin/sh -c /usr/local/bin/ ... Up
  8. harbor-portal       nginx -g daemon off;         Up
  9. nginx               nginx -g daemon off;         Up
  10. redis               redis-server /etc/redis.conf  Up
  11. registry            /home/harbor/entrypoint.sh   Up

四、安全加固与最佳实践

1. HTTPS配置

若未配置HTTPS，浏览器访问时会提示“不安全”。推荐使用Let’s Encrypt免费证书：

  1. # 安装Certbot
  2. sudo yum install -y certbot python3-certbot-nginx
  4. # 获取证书（需提前解析域名）
  5. sudo certbot certonly --nginx -d harbor.example.com
  7. # 修改harbor.yml中的证书路径
  8. certificate: /etc/letsencrypt/live/harbor.example.com/fullchain.pem
  9. private_key: /etc/letsencrypt/live/harbor.example.com/privkey.pem

2. 权限管理与用户认证

Harbor支持数据库认证、LDAP集成、OAuth2等多种方式。以LDAP为例：

  1. # 在harbor.yml中启用LDAP
  2. auth_mode: ldap
  3. ldap:
  4.   url: ldap://ldap.example.com
  5.   search_dn: uid=admin,ou=users,dc=example,dc=com
  6.   search_password: admin123
  7.   base_dn: ou=users,dc=example,dc=com
  8.   uid: uid
  9.   filter: (objectClass=person)
  10.   scope: 2

3. 镜像签名与漏洞扫描

Harbor内置Notary（镜像签名）和Clair（漏洞扫描）服务。启用步骤：

  1. 镜像签名：

    • 在harbor.yml中设置notary.enabled: true。
    • 客户端推送镜像时需添加--disable-content-trust=false。

  2. 漏洞扫描：

    • 确保scan.policy配置为daily或realtime。
    • 扫描结果可通过Web界面或API查看。

五、运维管理与故障排查

1. 日常维护命令

  1. # 重启Harbor
  2. cd /path/to/harbor
  3. docker-compose down
  4. docker-compose up -d
  6. # 查看日志
  7. docker-compose logs -f
  9. # 备份数据
  10. sudo tar czf harbor_backup_$(date +%Y%m%d).tar.gz /data

2. 常见问题解决

  • 问题1：502 Bad Gateway

    • 原因：Nginx与后端服务通信失败。
    • 解决：检查docker-compose logs nginx，确认harbor-core是否运行。

  • 问题2：镜像推送失败（401 Unauthorized）

    • 原因：密码错误或权限不足。
    • 解决：通过curl -u admin:Harbor12345 -X GET https://harbor.example.com/api/v2.0/projects测试API访问。

  • 问题3：磁盘空间不足

    • 解决：清理无用镜像（docker system prune），或扩展/data分区。

六、总结与扩展建议

单机Harbor部署虽简单，但需注意以下关键点：

  1. 数据备份：定期备份/data目录，避免镜像丢失。
  2. 高可用：生产环境建议使用Harbor集群（需共享存储和数据库）。
  3. 监控：集成Prometheus+Grafana监控Harbor指标（如请求延迟、存储使用率）。

通过本文的步骤，开发者可快速完成单机Harbor的部署，并基于其扩展CI/CD流水线（如Jenkins集成）、多集群镜像分发等场景。Harbor的模块化设计（如可插拔的认证、扫描模块）也为其在复杂环境中的适配提供了灵活性。

最新文章