Harbor 私有镜像仓库部署与运维

一、概述

Harbor 是一个开源的容器镜像仓库，提供镜像存储、复制、安全扫描、用户管理等功能。适用于企业内部搭建私有 Docker 镜像仓库，满足镜像安全、合规、分发等需求。

1.1 核心功能

  • 镜像存储与管理：支持 Docker、Helm Chart 存储
  • 多租户支持：基于角色的访问控制（RBAC）
  • 安全扫描：集成 Clair/Trivy 进行漏洞扫描
  • 镜像复制：支持多实例间镜像同步
  • 镜像签名：支持 Notary 签名验证
  • 审计日志：记录所有操作行为

1.2 架构组件

1
2
3
4
5
6
7
8
9
┌─────────────────────────────────────────────────────────┐
│                      Harbor                              │
├─────────────┬─────────────┬─────────────┬──────────────┤
│   Nginx     │   Core      │  Registry   │   Database   │
│  (Proxy)    │  (Service)  │  (Storage)  │  (PostgreSQL)│
├─────────────┼─────────────┼─────────────┼──────────────┤
│   Redis     │   Trivy     │   Notary    │   ChartMuseum│
│  (Cache)    │  (Scanner)  │  (Signer)   │  (Helm Repo) │
└─────────────┴─────────────┴─────────────┴──────────────┘

二、部署准备

2.1 系统要求

组件 最低配置 推荐配置
CPU 2 核 4 核+
内存 4GB 8GB+
磁盘 50GB 200GB+（SSD）
系统 CentOS 7+/Ubuntu 18.04+ 64 位 Linux

2.2 依赖软件

1
2
3
4
5
6
7
8
# Docker（20.10+）
docker --version

# Docker Compose（2.0+）
docker compose version

# OpenSSL（证书生成）
openssl version

2.3 网络规划

端口 协议 用途
80/443 TCP HTTP/HTTPS 访问
5000 TCP Registry API（内部）
5432 TCP PostgreSQL（内部）
6379 TCP Redis（内部）

三、安装部署

3.1 下载 Harbor

1
2
3
4
5
6
# 下载离线安装包（以 v2.9.0 为例）
wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-offline-installer-v2.9.0.tgz

# 解压
tar -zxvf harbor-offline-installer-v2.9.0.tgz
cd harbor

3.2 配置 Harbor

编辑 harbor.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# 主机名（必须是 FQDN 或 IP）
hostname: harbor.example.com

# HTTP 端口
http:
  port: 80

# HTTPS 配置（生产环境建议启用）
https:
  port: 443
  certificate: /data/cert/server.crt
  private_key: /data/cert/server.key

# 管理员密码
harbor_admin_password: Harbor12345

# 数据库配置
database:
  password: root123
  max_idle_conns: 50
  max_open_conns: 1000

# 数据卷路径
data_volume: /data

# Trivy 配置
trivy:
  ignore_unfixed: false
  skip_update: false
  offline_scan: false
  insecure: false

# 作业日志
log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M
    location: /var/log/harbor

3.3 生成自签名证书（测试环境）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# 创建证书目录
mkdir -p /data/cert

# 生成 CA 证书
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=harbor.example.com" \
  -key ca.key -out ca.crt

# 生成服务器证书
openssl genrsa -out server.key 4096
openssl req -sha512 -new \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=harbor.example.com" \
  -key server.key -out server.csr

# 生成 x509 v3 扩展文件
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.example.com
DNS.2=harbor
IP.1=192.168.1.10
EOF

# 生成服务器证书
openssl x509 -req -sha512 -days 3650 \
  -extfile v3.ext \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -in server.csr \
  -out server.crt

3.4 安装 Harbor

1
2
3
4
5
# 运行安装脚本
./install.sh

# 或使用 Docker Compose 手动启动
docker compose up -d

3.5 验证安装

1
2
3
4
5
6
7
8
9
# 检查容器状态
docker compose ps

# 查看日志
docker compose logs -f core

# 访问 Web 界面
# http://harbor.example.com
# 默认账号：admin / Harbor12345

四、配置与管理

4.1 Docker 客户端配置

1
2
3
4
5
6
7
8
9
# 信任自签名证书（测试环境）
sudo cp /data/cert/ca.crt /etc/docker/certs.d/harbor.example.com/ca.crt
sudo systemctl restart docker

# 或配置 insecure registry（不推荐生产环境）
# /etc/docker/daemon.json
{
  "insecure-registries": ["harbor.example.com"]
}

4.2 创建项目

1
2
3
4
5
# Web 界面创建，或使用 API
curl -u "admin:Harbor12345" -X POST \
  -H "Content-Type: application/json" \
  -d '{"project_name": "myproject", "public": false}' \
  http://harbor.example.com/api/v2.0/projects

4.3 推送镜像

1
2
3
4
5
6
7
8
9
10
11
12
# 登录 Harbor
docker login harbor.example.com
# 输入用户名和密码

# 标记镜像
docker tag nginx:latest harbor.example.com/myproject/nginx:latest

# 推送镜像
docker push harbor.example.com/myproject/nginx:latest

# 拉取镜像
docker pull harbor.example.com/myproject/nginx:latest

4.4 用户管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 创建用户（Web 界面或 API）
curl -u "admin:Harbor12345" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer",
    "email": "dev@example.com",
    "realname": "Developer",
    "password": "Dev123456",
    "comment": "开发团队"
  }' \
  http://harbor.example.com/api/v2.0/users

# 添加项目成员
curl -u "admin:Harbor12345" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": 2,
    "member_user": {"username": "developer"}
  }' \
  http://harbor.example.com/api/v2.0/projects/1/members

4.5 角色权限

角色 权限
项目管理员 项目管理、成员管理、镜像管理
开发人员 推送/拉取镜像、查看扫描结果
访客 仅拉取公开镜像

五、安全配置

5.1 漏洞扫描

1
2
3
4
5
6
7
8
9
10
# 启用 Trivy 扫描
# Web 界面：项目 → 选项 → 自动扫描

# 手动触发扫描
curl -u "admin:Harbor12345" -X POST \
  http://harbor.example.com/api/v2.0/projects/myproject/repositories/nginx%2Flatest/scan

# 查看扫描结果
curl -u "admin:Harbor12345" \
  http://harbor.example.com/api/v2.0/projects/myproject/repositories/nginx%2Flatest/vulnerabilities

5.2 镜像签名

1
2
3
4
5
6
7
8
9
10
11
# 启用内容信任
export DOCKER_CONTENT_TRUST=1

# 生成签名密钥
docker trust key generate

# 签名镜像
docker trust sign harbor.example.com/myproject/nginx:latest

# 验证签名
docker trust inspect harbor.example.com/myproject/nginx:latest

5.3 访问控制

1
2
3
4
5
6
7
8
9
# harbor.yml 中配置
# 启用机器人账户
robot_enabled: true

# 设置会话超时
session_timeout: 60

# 启用双因素认证
uaa_client_secret: ""

六、高可用部署

6.1 外部数据库

1
2
3
4
5
6
7
8
9
10
11
# harbor.yml
external_database:
  type: postgresql
  host: pg-cluster.example.com
  port: 5432
  username: harbor
  password: Harbor_DB_Pass
  core_database: registry
  registry_database: registry
  notary_server_database: notary_server
  notary_signer_database: notary_signer

6.2 外部 Redis

1
2
3
4
5
# harbor.yml
external_redis:
  host: redis-cluster.example.com
  port: 6379
  password: Redis_Pass

6.3 共享存储

1
2
3
4
5
6
7
8
9
10
# 使用共享存储（NFS/Ceph/S3）
storage_service:
  filesystem:
    rootdirectory: /data/registry
  # 或使用 S3
  # s3:
  #   accesskey: xxx
  #   secretkey: xxx
  #   region: cn-north-1
  #   bucket: harbor-registry

6.4 多实例部署

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 使用负载均衡分发请求
# Nginx 配置示例
upstream harbor {
  server harbor1.example.com weight=1;
  server harbor2.example.com weight=1;
}

server {
  listen 443 ssl;
  server_name harbor.example.com;
  
  location / {
    proxy_pass http://harbor;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

七、镜像复制

7.1 配置复制端点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 创建复制目标
curl -u "admin:Harbor12345" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backup-harbor",
    "type": "harbor",
    "url": "https://backup.example.com",
    "credential": {
      "type": "basic",
      "access_key": "admin",
      "access_secret": "Harbor12345"
    }
  }' \
  http://harbor.example.com/api/v2.0/registries

7.2 创建复制规则

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 基于项目复制
curl -u "admin:Harbor12345" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backup-rule",
    "description": "备份到灾备中心",
    "src_registry": null,
    "dest_registry": {"id": 1},
    "dest_namespace": "backup",
    "filters": [{"type": "project", "value": "myproject"}],
    "trigger": {"type": "manual"},
    "speed": -1
  }' \
  http://harbor.example.com/api/v2.0/replication/policies

八、运维管理

8.1 日志管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 查看组件日志
docker compose logs -f core
docker compose logs -f registry
docker compose logs -f trivy

# 日志位置
/var/log/harbor/

# 日志轮转配置（harbor.yml）
log:
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M

8.2 备份与恢复

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 备份数据库
pg_dump -h localhost -U harbor -d registry > registry_backup.sql

# 备份数据卷
tar -czvf harbor_data_backup.tar.gz /data

# 恢复数据
# 1. 停止 Harbor
docker compose down

# 2. 恢复数据卷
tar -xzvf harbor_data_backup.tar.gz -C /

# 3. 恢复数据库
psql -h localhost -U harbor -d registry < registry_backup.sql

# 4. 启动 Harbor
docker compose up -d

8.3 升级 Harbor

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 备份当前配置和数据
# 2. 下载新版本
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
tar -zxvf harbor-offline-installer-v2.10.0.tgz

# 3. 迁移配置
cp harbor.yml /tmp/harbor.yml.bak
# 编辑新版本 harbor.yml

# 4. 执行升级脚本
cd harbor
./install.sh --upgrade

# 5. 验证升级
docker compose ps

8.4 监控指标

1
2
3
4
5
6
7
8
# Harbor 暴露 Prometheus 指标
# http://harbor.example.com/metrics

# 关键指标：
# - harbor_project_quota_usage_bytes
# - harbor_artifact_count
# - harbor_scan_queue_length
# - harbor_replication_jobs_total

九、常见问题排查

9.1 无法登录

1
2
3
4
5
6
7
8
# 检查 Nginx 配置
docker compose logs nginx

# 检查 Core 服务
docker compose logs core

# 验证证书
openssl s_client -connect harbor.example.com:443 -showcerts

9.2 推送失败

1
2
3
4
5
6
7
8
# 检查 Registry 状态
docker compose logs registry

# 检查存储空间
df -h /data

# 检查权限
ls -la /data/registry

9.3 扫描失败

1
2
3
4
5
6
7
8
# 检查 Trivy 状态
docker compose logs trivy

# 更新漏洞数据库
docker compose exec trivy trivy image --download-db-only

# 检查网络连接
docker compose exec trivy ping github.com

9.4 数据库连接失败

1
2
3
4
5
# 检查 PostgreSQL 状态
docker compose logs database

# 验证连接
docker compose exec database psql -U harbor -d registry -c "SELECT 1"

十、最佳实践

10.1 命名规范

1
2
3
4
5
6
7
# 项目命名
{部门}/{应用}
例如：backend/api-gateway

# 镜像标签
{应用}:{版本}-{环境}
例如：api-gateway:1.2.3-prod

10.2 清理策略

1
2
3
4
5
6
7
8
# 设置镜像保留策略
# Web 界面：项目 → 标签保留规则

# 或使用 API
curl -u "admin:Harbor12345" -X PUT \
  -H "Content-Type: application/json" \
  -d '{"retention_id": 1, "scope": {"level": "project", "ref": 1}}' \
  http://harbor.example.com/api/v2.0/retentions

10.3 安全建议

  1. 启用 HTTPS：生产环境必须使用 HTTPS
  2. 定期更新：及时升级 Harbor 和 Trivy 漏洞库
  3. 最小权限：按角色分配最小必要权限
  4. 审计日志：定期检查操作日志
  5. 网络隔离：Harbor 部署在内网，通过反向代理对外

10.4 性能优化

1
2
3
4
5
6
7
8
9
10
11
12
# 调整数据库连接池
database:
  max_idle_conns: 100
  max_open_conns: 2000

# 调整 Redis 配置
redis:
  max_idle: 100
  max_active: 500

# 使用高速存储
# SSD 或分布式存储（Ceph/NFS）

十一、总结

Harbor 是企业级容器镜像仓库的优秀选择，具备以下优势：

  • ✅ 功能完整：存储、扫描、签名、复制一站式
  • ✅ 易于部署：Docker Compose 一键安装
  • ✅ 安全可靠：RBAC、漏洞扫描、镜像签名
  • ✅ 扩展性强：支持外部存储、数据库、多实例

合理规划和配置 Harbor，可以为企业容器化转型提供坚实的基础设施支撑。