部署单机Harbor：从环境准备到运维实践的全流程指南

一、为什么选择单机Harbor部署？

在中小型团队或边缘计算场景中，单机Harbor通过轻量化架构满足私有镜像仓库的核心需求。相较于集群方案，单机部署具有资源占用低（CPU/内存需求减少40%）、运维复杂度低（无需处理节点间通信）、成本可控（单台服务器即可）等优势。典型适用场景包括：开发测试环境镜像管理、物联网设备固件分发、分支机构私有仓库等。

二、环境准备：硬件与软件要求

2.1 硬件配置建议

• 基础配置：4核CPU/8GB内存/100GB存储（支持50人以下团队）
• 生产配置：8核CPU/16GB内存/500GB存储（建议NVMe SSD）
• 网络要求：千兆网卡，开放443（HTTPS）、80（HTTP可选）、22（SSH维护）

2.2 软件依赖清单

# CentOS/RHEL 7+ 依赖安装
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker
# Ubuntu 20.04+ 依赖安装
sudo apt install -y docker.io docker-compose
sudo usermod -aG docker $USER  # 避免每次使用sudo

2.3 存储规划要点

• 数据目录：建议使用独立分区（如/var/lib/harbor）
• 存储类型选择：
  • 开发环境：本地磁盘（ext4/xfs）
  • 生产环境：LVM逻辑卷或云盘（支持快照）
• 备份策略：每日增量备份+每周全量备份

三、安装部署：分步详解

3.1 下载安装包

# 获取最新稳定版（示例为v2.9.0）
wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-offline-installer-v2.9.0.tgz
tar xvf harbor-offline-installer-v2.9.0.tgz
cd harbor

3.2 配置文件关键参数

修改harbor.yml.tmpl生成harbor.yml：

hostname: harbor.example.com  # 需解析至本机IP
http:
  port: 80  # 或使用443启用HTTPS
https:
  certificate: /data/cert/server.crt
  private_key: /data/cert/server.key
harbor_admin_password: Harbor12345  # 生产环境需修改
database:
  password: root123  # 数据库密码
storage_service:
  redis:
    password: redis123  # Redis密码

3.3 执行安装命令

# 生成自签名证书（生产环境替换为CA证书）
sudo mkdir -p /data/cert
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /data/cert/server.key -out /data/cert/server.crt \
  -subj "/CN=harbor.example.com"
# 启动安装
sudo ./install.sh --with-trivy  # 包含漏洞扫描组件

四、核心功能配置

4.1 用户与权限管理

# 使用Harbor API创建项目
curl -u "admin:Harbor12345" -X POST \
  -H "Content-Type: application/json" \
  -d '{"project_name": "devops", "public": false}' \
  http://harbor.example.com/api/v2.0/projects
# 添加项目成员
curl -u "admin:Harbor12345" -X POST \
  -H "Content-Type: application/json" \
  -d '{"role_id": 2, "username": "dev1"}' \  # 2=开发者角色
  http://harbor.example.com/api/v2.0/projects/1/members

4.2 镜像复制策略

配置示例（将镜像复制至阿里云CR）：

# 在harbor.yml中添加
replication:
  - name: aliyun-cr
    disabled: false
    src_registry:
      url: http://harbor.example.com
      insecure: true
    dest_registry:
      url: https://cr.aliyuncs.com
      username: "aliyun_account"
      password: "aliyun_password"
    dest_namespace: "my-project"
    trigger:
      type: manual
    filters:
      tag_filter:
        pattern: "^v.*"

4.3 漏洞扫描配置

# 启用Trivy扫描（需在install.sh时添加--with-trivy）
sudo docker exec -it harbor-trivy trivy image --severity CRITICAL nginx:latest
# 配置扫描策略（通过Web界面）
# 路径：系统管理 > 漏洞扫描 > 配置
# 建议设置：
# - 扫描级别：CRITICAL+HIGH
# - 扫描频率：每日凌晨3点
# - 自动阻止高危镜像：启用

五、运维与故障排除

5.1 日常维护命令

# 查看服务状态
sudo docker-compose ps
# 日志查看
sudo docker-compose logs -f harbor-core
# 数据备份
sudo tar czf /backup/harbor_$(date +%Y%m%d).tar.gz /var/lib/harbor

5.2 常见问题解决方案

问题1：502 Bad Gateway

• 检查Nginx容器日志：sudo docker logs harbor-nginx
• 常见原因：后端服务未启动、证书配置错误

问题2：镜像推送失败

• 验证认证信息：docker login harbor.example.com
• 检查存储空间：df -h /var/lib/harbor

问题3：漏洞扫描卡住

• 检查Trivy容器资源：sudo docker stats harbor-trivy
• 解决方案：增加内存限制（在docker-compose.yml中修改mem_limit: 2g）

六、性能优化建议

6.1 缓存配置

# 在harbor.yml中添加
cache:
  enabled: true
  expire_hours: 24  # 缓存有效期
  redis:
    host: harbor-redis
    port: 6379

6.2 数据库调优

修改PostgreSQL配置（/var/lib/harbor/pgsql/data/postgresql.conf）：

shared_buffers = 256MB  # 内存的25%
work_mem = 4MB
maintenance_work_mem = 64MB

6.3 网络优化

• 启用HTTP/2：修改Nginx配置

  server {
    listen 443 ssl http2;
    # ...其他配置
  }

• 启用Gzip压缩：

  gzip on;
  gzip_types application/json text/css application/javascript;

七、升级与扩展

7.1 版本升级流程

# 1. 备份数据
sudo ./prepare.sh backup
# 2. 下载新版本
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
# 3. 修改配置文件兼容性
vi harbor.yml  # 检查新增参数
# 4. 执行升级
sudo ./install.sh --with-chartmuseum --with-trivy

7.2 横向扩展方案

当存储或计算资源不足时，可考虑：

1. 存储扩展：

   • 添加NFS存储后端
   • 配置对象存储（如MinIO）

2. 计算扩展：

   • 部署多个JobService实例
   • 增加Redis节点数量

八、安全最佳实践

8.1 网络安全

• 启用IP白名单：

  # 在harbor.yml中添加
  ip_filter:
  enabled: true
  allow_list:
    - 192.168.1.0/24
    - 10.0.0.0/16

8.2 审计日志

配置日志轮转与远程收集：

# 修改日志配置
sudo vi /etc/logrotate.d/harbor
/var/log/harbor/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    copytruncate
}

8.3 密码策略

强制密码复杂度：

# 在harbor.yml中添加
auth_mode: db_auth
password_policy:
  min_length: 12
  require_uppercase: true
  require_lowercase: true
  require_number: true
  require_special: true

九、总结与展望

单机Harbor部署通过合理的资源配置和功能裁剪，为中小规模团队提供了高性价比的私有镜像仓库解决方案。实际部署中需重点关注存储规划、证书管理和备份策略三个核心环节。随着容器技术的演进，未来可考虑向Harbor集群方案迁移，或集成CI/CD流水线实现镜像自动构建与部署。

注：本文配置示例基于Harbor v2.9.0，不同版本可能存在参数差异，建议参考官方文档获取最新信息。生产环境部署前务必进行压力测试，建议使用locust模拟并发推送场景验证系统稳定性。