一、Harbor核心价值与单机部署场景

Harbor作为开源的企业级Docker镜像仓库，提供镜像存储、权限控制、漏洞扫描等核心功能。单机部署模式适用于开发测试环境、中小型企业私有云或边缘计算场景，具有资源占用低、维护简单的优势。相较于集群模式，单机版无需处理分布式协调问题，但需关注存储容量与高可用性设计。

1.1 典型应用场景

开发环境：为CI/CD流水线提供私有镜像存储
离线部署：在内网或无公网访问的环境中构建镜像仓库
边缘计算：在资源受限的边缘节点部署轻量级仓库
成本敏感型项目：避免集群模式带来的硬件与运维成本

1.2 单机部署架构

单机Harbor采用单节点架构，包含Core服务、数据库（PostgreSQL/MySQL）、Redis缓存、存储驱动（文件系统/S3/OSS）等组件。所有服务运行在同一主机，通过端口区分不同功能模块。

二、环境准备与前置条件

2.1 硬件配置要求

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

2.2 软件依赖检查

# 检查Docker版本（需19.03+）
docker --version
# 检查Docker Compose版本（需1.25+）
docker-compose --version
# 检查系统内核参数（需支持overlay2存储驱动）
grep overlay /proc/filesystems

2.3 操作系统优化

# 修改系统参数（以CentOS 7为例）
cat >> /etc/sysctl.conf <<EOF
vm.max_map_count=262144
net.core.somaxconn=65535
EOF
sysctl -p
# 调整文件描述符限制
cat >> /etc/security/limits.conf <<EOF
* soft nofile 65535
* hard nofile 65535
EOF

三、标准化部署流程

3.1 下载安装包

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

3.2 配置文件详解

修改harbor.yml.tmpl（或复制为harbor.yml）重点参数：

hostname: registry.example.com  # 需配置DNS或hosts解析
http:
  port: 80  # 或使用443启用HTTPS
  # tls:
  #   certificate: /path/to/cert.pem
  #   private_key: /path/to/key.pem
# 存储配置（文件系统示例）
storage:
  filesystem:
    rootdirectory: /data/harbor
  # S3配置示例：
  # s3:
  #   accesskey: xxx
  #   secretkey: xxx
  #   region: us-west-1
  #   bucket: harbor-bucket
database:
  password: root123  # 生产环境需修改
  max_open_conns: 100
  max_idle_conns: 50
# 配置管理员密码
harbor_admin_password: Harbor12345

3.3 安装执行

# 生成自签名证书（可选）
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/pki/tls/private/harbor.key \
  -out /etc/pki/tls/certs/harbor.crt \
  -subj "/CN=registry.example.com"
# 安装Harbor
./install.sh --with-clair  # 可选添加漏洞扫描组件

四、运维优化实践

4.1 存储管理策略

镜像清理：配置gc.cron定期执行垃圾回收

# 手动执行GC（需进入Harbor容器）
docker exec -it harbor-core /harbor/gc.sh

存储扩容：使用LVM管理磁盘空间，支持在线扩容

pvcreate /dev/sdb
vgextend vg_harbor /dev/sdb
lvextend -l +100%FREE /dev/vg_harbor/lv_harbor
resize2fs /dev/vg_harbor/lv_harbor

4.2 性能调优参数

参数	默认值	推荐值	说明
`max_job_workers`	3	CPU核数×2	异步任务并发数
`token_expiration`	30min	24h	令牌有效期
`project_quota`	无限制	500GB	单项目存储配额

4.3 备份恢复方案

# 完整备份脚本示例
#!/bin/bash
BACKUP_DIR="/backup/harbor_$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR
# 备份数据库
docker exec -it harbor-db pg_dump -U postgres -h 127.0.0.1 registry > $BACKUP_DIR/registry.sql
# 备份配置文件
cp -r /data/harbor/config $BACKUP_DIR/
cp harbor.yml $BACKUP_DIR/
# 备份镜像数据（rsync增量备份）
rsync -avz --delete /data/harbor/ $BACKUP_DIR/data/

五、安全加固建议

5.1 访问控制策略

启用RBAC权限模型
配置项目级访问控制

限制匿名访问：

# 在harbor.yml中设置
auth_mode: db_auth  # 或ldap_auth
anonymous_access: false

5.2 传输安全

强制HTTPS访问

启用HSTS头：

# 在nginx配置中添加
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

5.3 审计日志

配置日志轮转：

# /etc/logrotate.d/harbor
/var/log/harbor/*.log {
  daily
  missingok
  rotate 14
  compress
  delaycompress
  notifempty
  copytruncate
}

六、故障排查指南

6.1 常见问题处理

现象	解决方案
502 Bad Gateway	检查nginx容器日志，重启服务
数据库连接失败	验证数据库密码，检查磁盘空间
镜像推送超时	调整`upload_chunk_size`参数
漏洞扫描失败	检查Clair数据库连接，重启clair服务

6.2 日志分析技巧

# 查看核心服务日志
docker-compose logs -f core
# 搜索错误关键词
journalctl -u docker --no-pager | grep "error"
# 分析访问日志（需配置）
tail -f /var/log/harbor/core.log | grep "500"

七、升级与扩展建议

7.1 版本升级流程

# 1. 备份当前环境
./prepare.sh --backup backup_dir
# 2. 下载新版本并解压
wget new_version.tgz
tar xvf new_version.tgz
# 3. 执行升级
cd new_version
./install.sh --upgrade

7.2 横向扩展方案

当单机性能不足时，可考虑：

添加Notary服务实现镜像签名
部署Trivy作为独立漏洞扫描器
使用NFS/Ceph作为共享存储
配置前端负载均衡器（如Nginx）实现高可用

八、最佳实践总结

资源隔离：使用独立磁盘分区存储镜像数据
监控告警：集成Prometheus+Grafana监控关键指标
定期维护：每月执行健康检查与性能基准测试
文档管理：维护完整的部署文档与变更记录

通过遵循本指南，开发者可在30分钟内完成单机Harbor的标准化部署，并获得一个稳定、安全、高效的私有镜像仓库。实际生产环境中，建议结合企业具体需求进行定制化配置，并建立完善的运维管理体系。

单机Harbor部署全攻略：从环境准备到运维实践