1. Harbor 简介与核心特性
Harbor 是一个开源的云原生制品仓库，主要用于存储和管理容器镜像、Helm Charts 等云原生制品。
作为 CNCF（云原生计算基金会）的毕业项目，Harbor 已成为企业级容器镜像管理的标准解决方案。
🔐 基于角色的访问控制 (RBAC)
支持细粒度的权限管理，用户通过角色获得对项目资源的访问权限，包括管理员、开发者、访客等多种角色。
🔄 镜像复制
支持跨多个 Registry 实例的镜像同步复制，适用于负载均衡、高可用、混合云和多云场景。
🖥️ 图形化用户界面
提供直观的 Web 管理界面，支持镜像浏览、检索、项目管理和用户管理等操作。
🔍 漏洞扫描
集成 Clair、Trivy 等扫描器，自动检测镜像中的安全漏洞，保障镜像安全性。
📊 审计日志
所有针对镜像仓库的操作都会被记录追溯，满足企业审计合规要求。
🌐 AD/LDAP 集成
支持与企业现有的 AD/LDAP 目录服务集成，实现统一身份认证管理。
💡 提示：Harbor 是首个源自中国并成为 CNCF 毕业项目的开源软件，由 VMware 中国研发团队主导开发。
2. 系统要求与环境准备
2.1 硬件要求
| 组件 |
最低配置 |
推荐配置 |
生产环境配置 |
| CPU |
2 核 |
4 核 |
8 核+ |
| 内存 |
4 GB |
8 GB |
16 GB+ |
| 磁盘 |
50 GB SSD |
100 GB SSD |
500 GB+ SSD/SAN |
| 网络 |
1 Gbps |
1 Gbps |
10 Gbps |
2.2 软件要求
| 软件 |
版本要求 |
说明 |
| Docker |
v20.10.0+ |
容器运行时环境 |
| Docker Compose |
v2.0.0+ |
容器编排工具 |
| OpenSSL |
v1.1.1+ |
证书生成工具 |
| 操作系统 |
CentOS 7.6+ / Ubuntu 18.04+ |
Linux 发行版 |
2.3 环境初始化脚本
systemctl stop firewalld
systemctl disable firewalld
setenforce 0
sed -i 's/enforcing/disabled/' /etc/selinux/config
hostnamectl set-hostname harbor-server
yum install -y wget net-tools nfs-utils lrzsz gcc gcc-c++ make \
cmake libxml2-devel openssl-devel curl curl-devel unzip sudo \
ntp libaio-devel vim ncurses-devel autoconf automake zlib-devel \
python3-devel epel-release openssh-server socat ipvsadm conntrack
yum-config-manager --add-repo http://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
yum install -y docker-ce docker-ce-cli containerd.io
systemctl enable --now docker
mkdir -p /etc/docker
cat > /etc/docker/daemon.json << EOF
{
"registry-mirrors": [
"https://hub.rat.dev",
"https://docker.1panel.live",
"https://docker.rainbond.cc"
],
"insecure-registries": ["harbor.yourdomain.com"]
}
EOF
systemctl restart docker
curl -L "https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
docker --version
docker-compose --version
⚠️ 警告：生产环境中不建议完全关闭防火墙和 SELinux，应该配置适当的安全策略和访问规则。
3. Harbor 架构设计
3.1 核心组件说明
| 组件名称 |
功能描述 |
端口 |
| Proxy (Nginx) |
反向代理，处理所有外部请求，提供 HTTPS 终止 |
443/80 |
| Harbor Core |
核心服务，提供 API 接口和 Web 界面，处理认证授权 |
8080 |
| Registry |
Docker Registry v2，负责镜像的存储和分发 |
5000 |
| ChartMuseum |
Helm Chart 仓库服务 |
6060 |
| PostgreSQL |
存储用户信息、项目元数据、镜像元数据等 |
5432 |
| Redis |
缓存会话、令牌、任务队列等 |
6379 |
| Trivy |
镜像漏洞扫描器 |
- |
| Job Service |
后台任务调度，处理复制、扫描等异步任务 |
- |
4. 自动化部署流程
-
下载 Harbor 安装包
从 GitHub Releases 页面下载最新版本的 Harbor 离线安装包：
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 -C /opt/
cd /opt/harbor
-
配置 harbor.yml 文件
编辑 Harbor 主配置文件，设置 hostname、HTTPS 证书路径等关键参数：
cp harbor.yml.tmpl harbor.yml
vim harbor.yml
hostname: harbor.yourdomain.com
http:
port: 8080
https:
port: 443
certificate: /opt/harbor/certs/server.crt
private_key: /opt/harbor/certs/server.key
harbor_admin_password: Harbor12345
database:
password: root123
max_idle_conns: 50
max_open_conns: 1000
data_volume: /data/harbor
trivy:
ignore_unfixed: false
skip_update: false
offline_scan: false
skip_java_db_update: false
jobservice:
max_job_workers: 10
notification:
webhook_job_max_retry: 10
log:
level: info
local:
rotate_count: 50
rotate_size: 200M
location: /var/log/harbor
_version: 2.9.0
-
执行安装脚本
./install.sh
./install.sh --with-trivy --with-chartmuseum
-
验证安装
docker-compose ps
docker-compose logs -f
curl -k https://harbor.yourdomain.com
✅ 成功标志：所有容器状态为 Up，Web 界面可正常访问，默认管理员账号 admin 可登录。
5. SSL/TLS 证书配置
5.1 使用 OpenSSL 生成自签名证书
mkdir -p /opt/harbor/certs
cd /opt/harbor/certs
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
-subj "/C=CN/ST=Beijing/L=Beijing/O=YourCompany/OU=IT/CN=harbor.yourdomain.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=YourCompany/OU=IT/CN=harbor.yourdomain.com" \
-key server.key \
-out server.csr
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.yourdomain.com
DNS.2=harbor
IP.1=192.168.1.100
EOF
openssl x509 -req -sha512 -days 3650 \
-extfile v3.ext \
-CA ca.crt -CAkey ca.key -CAcreateserial \
-in server.csr \
-out server.crt
cp ca.crt /etc/pki/ca-trust/source/anchors/harbor-ca.crt
update-ca-trust
mkdir -p /etc/docker/certs.d/harbor.yourdomain.com
cp ca.crt /etc/docker/certs.d/harbor.yourdomain.com/ca.crt
systemctl restart docker
5.2 使用 Let's Encrypt 获取免费证书
yum install -y certbot
certbot certonly --standalone -d harbor.yourdomain.com
ln -s /etc/letsencrypt/live/harbor.yourdomain.com/fullchain.pem /opt/harbor/certs/server.crt
ln -s /etc/letsencrypt/live/harbor.yourdomain.com/privkey.pem /opt/harbor/certs/server.key
💡 提示：生产环境强烈建议使用受信任的 CA 颁发的证书或 Let's Encrypt 免费证书，避免使用自签名证书。
6. RBAC 权限管理体系
Harbor 实现了基于角色的访问控制（RBAC）模型，通过用户 - 角色 - 权限三层结构实现细粒度的权限管理。
权限控制主要在项目（Project）级别进行，用户可以属于多个项目，并在不同项目中拥有不同的角色。
6.1 预定义角色
| 角色名称 |
角色代码 |
权限描述 |
| 超级管理员 |
admin |
系统最高权限，可管理所有项目、用户、系统配置、查看审计日志等 |
| 项目管理员 |
projectadmin |
管理特定项目，包括成员管理、镜像管理、扫描策略配置等 |
| 开发者 |
developer |
推送和拉取镜像、查看项目信息、触发扫描等 |
| 访客 |
guest |
仅可拉取公开项目的镜像，查看基本信息 |
| 受限访客 |
limited_guest |
仅可拉取镜像，无法查看其他信息 |
6.2 权限矩阵
| 权限项 |
Admin |
ProjectAdmin |
Developer |
Guest |
| 创建项目 |
✅ |
❌ |
❌ |
❌ |
| 删除项目 |
✅ |
✅ (本项目) |
❌ |
❌ |
| 添加成员 |
✅ |
✅ (本项目) |
❌ |
❌ |
| 推送镜像 |
✅ |
✅ |
✅ |
❌ |
| 拉取镜像 |
✅ |
✅ |
✅ |
✅ (公开) |
| 删除镜像 |
✅ |
✅ |
❌ |
❌ |
| 触发扫描 |
✅ |
✅ |
✅ |
❌ |
| 查看日志 |
✅ |
✅ |
✅ |
❌ |
| 配置复制 |
✅ |
✅ |
❌ |
❌ |
6.3 自定义角色（Harbor v2.4+）
curl -X POST "https://harbor.yourdomain.com/api/v2.0/roles" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "custom_developer",
"description": "自定义开发者角色",
"permissions": [
{"resource": "project", "action": "read"},
{"resource": "repository", "action": "pull"},
{"resource": "repository", "action": "push"},
{"resource": "scan", "action": "create"}
]
}'
7. 项目与用户管理
7.1 项目管理
项目是 Harbor 中资源组织的基本单位，分为公开项目和私有项目：
- 公开项目（Public）：任何用户都可以拉取镜像
- 私有项目（Private）：只有项目成员才能访问
curl -X POST "https://harbor.yourdomain.com/api/v2.0/projects" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{
"project_name": "library",
"public": true,
"metadata": {
"auto_scan": "true"
}
}'
curl -X POST "https://harbor.yourdomain.com/api/v2.0/projects" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{
"project_name": "backend-services",
"public": false,
"storage_limit": 10737418240,
"metadata": {
"auto_scan": "true",
"prevent_vul": "true",
"severity": "high"
}
}'
curl -X GET "https://harbor.yourdomain.com/api/v2.0/projects" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)"
curl -X DELETE "https://harbor.yourdomain.com/api/v2.0/projects/1" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)"
7.2 用户管理
curl -X POST "https://harbor.yourdomain.com/api/v2.0/users" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{
"username": "developer1",
"email": "developer1@company.com",
"realname": "张开发者",
"password": "DevPass123!",
"comment": "后端开发工程师",
"role_id": 0
}'
curl -X GET "https://harbor.yourdomain.com/api/v2.0/users?username=developer1" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)"
curl -X PUT "https://harbor.yourdomain.com/api/v2.0/users/2" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{
"realname": "张高级开发者",
"email": "senior.developer1@company.com"
}'
curl -X DELETE "https://harbor.yourdomain.com/api/v2.0/users/2" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)"
curl -X PUT "https://harbor.yourdomain.com/api/v2.0/users/2/sysadmin" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{"sysadmin_flag": true}'
7.3 项目成员管理
curl -X POST "https://harbor.yourdomain.com/api/v2.0/projects/1/members" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{
"role_id": 2,
"member_user": {
"user_id": 2,
"username": "developer1"
}
}'
curl -X GET "https://harbor.yourdomain.com/api/v2.0/projects/1/members" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)"
curl -X PUT "https://harbor.yourdomain.com/api/v2.0/projects/1/members/2" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{"role_id": 4}'
curl -X DELETE "https://harbor.yourdomain.com/api/v2.0/projects/1/members/2" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)"
7.4 LDAP/AD 集成配置
curl -X PUT "https://harbor.yourdomain.com/api/v2.0/configurations" \
-H "Authorization: Basic $(echo -n 'admin:Harbor12345' | base64)" \
-H "Content-Type: application/json" \
-d '{
"auth_mode": "ldap_auth",
"ldap_url": "ldap://ldap.company.com:389",
"ldap_base_dn": "dc=company,dc=com",
"ldap_uid": "uid",
"ldap_scope": 2,
"ldap_filter": "(objectClass=person)",
"ldap_search_dn": "cn=admin,dc=company,dc=com",
"ldap_search_password": "LdapAdminPass",
"ldap_group_base_dn": "ou=groups,dc=company,dc=com",
"ldap_group_filter": "(objectClass=groupOfNames)",
"ldap_group_gid": "cn",
"ldap_group_scope": 2
}'
8. 镜像推送与拉取
8.1 Docker CLI 操作
docker login harbor.yourdomain.com
docker tag myapp:latest harbor.yourdomain.com/library/myapp:v1.0.0
docker push harbor.yourdomain.com/library/myapp:v1.0.0
docker pull harbor.yourdomain.com/library/myapp:v1.0.0
docker logout harbor.yourdomain.com
8.2 CI/CD 集成示例
pipeline {
agent any
environment {
HARBOR_URL = 'harbor.yourdomain.com'
HARBOR_PROJECT = 'backend-services'
HARBOR_USER = credentials('harbor-user')
HARBOR_PASS = credentials('harbor-pass')
}
stages {
stage('Build Image') {
steps {
script {
docker.build("${env.HARBOR_URL}/${env.HARBOR_PROJECT}/myapp:${env.BUILD_NUMBER}")
}
}
}
stage('Push to Harbor') {
steps {
script {
docker.withRegistry("https://${env.HARBOR_URL}",
[usernamePassword(credentialsId: 'harbor-creds',
usernameVariable: 'USER',
passwordVariable: 'PASS')]) {
docker.image("${env.HARBOR_URL}/${env.HARBOR_PROJECT}/myapp:${env.BUILD_NUMBER}").push()
}
}
}
}
stage('Scan Image') {
steps {
script {
sh """
curl -X POST "https://${env.HARBOR_URL}/api/v2.0/projects/${env.HARBOR_PROJECT}/repositories/myapp/artifacts/latest/scan" \\
-u "${env.HARBOR_USER}:${env.HARBOR_PASS}"
"""
}
}
}
}
}
8.3 Kubernetes 集成
kubectl create secret docker-registry harbor-secret \
--docker-server=harbor.yourdomain.com \
--docker-username=developer1 \
--docker-password=DevPass123! \
--docker-email=developer1@company.com \
-n default
apiVersion: v1
kind: Pod
metadata:
name: myapp-pod
spec:
containers:
- name: myapp
image: harbor.yourdomain.com/backend-services/myapp:v1.0.0
imagePullSecrets:
- name: harbor-secret
9. 高可用配置方案
9.1 外部数据库配置
database:
type: external
external:
host: pg-cluster.company.com
port: 5432
username: harbor
password: SecureDbPass123
core_database: registry
notary_server_database: notary_server
notary_signer_database: notary_signer
sslmode: require
max_idle_conns: 100
max_open_conns: 2000
9.2 外部 Redis 配置
redis:
type: external
external:
host: redis-cluster.company.com
port: 6379
password: SecureRedisPass123
namespace: harbor
idle_timeout_seconds: 30
9.3 对象存储配置（S3/OSS）
storage:
filesystem:
rootdirectory: /storage
s3:
accesskey: AKIAIOSFODNN7EXAMPLE
secretkey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region: us-east-1
bucket: harbor-images
encrypt: true
secure: true
9.4 多节点部署架构
10. 监控与维护
10.1 健康检查
HARBOR_URL="harbor.yourdomain.com"
ADMIN_USER="admin"
ADMIN_PASS="Harbor12345"
echo "=== 检查容器状态 ==="
docker-compose ps
echo -e "\n=== 检查 API 健康 ==="
curl -k -s -o /dev/null -w "%{http_code}" \
https://${HARBOR_URL}/api/v2.0/ping
echo -e "\n\n=== 系统信息 ==="
curl -k -s -u ${ADMIN_USER}:${ADMIN_PASS} \
https://${HARBOR_URL}/api/v2.0/systeminfo | jq .
echo -e "\n=== 存储使用情况 ==="
df -h /data
echo -e "\n=== 数据库连接数 ==="
docker exec harbor-db psql -U postgres -d registry \
-c "SELECT count(*) FROM pg_stat_activity;"
10.2 日志管理
/var/log/harbor/
├── core.log # Core 服务日志
├── jobservice.log # Job Service 日志
├── nginx.log # Nginx 访问日志
├── proxy.log # 代理日志
├── registry.log # Registry 日志
└── trivy.log # Trivy 扫描日志
docker-compose logs -f core
docker-compose logs -f registry
tail -f /var/log/harbor/core.log
log:
level: info
local:
rotate_count: 50
rotate_size: 200M
location: /var/log/harbor
10.3 备份与恢复
BACKUP_DIR="/backup/harbor/$(date +%Y%m%d_%H%M%S)"
mkdir -p ${BACKUP_DIR}
docker exec harbor-db pg_dump -U postgres registry > ${BACKUP_DIR}/registry.sql
docker exec harbor-db pg_dump -U postgres notaryserver > ${BACKUP_DIR}/notary_server.sql
docker exec harbor-db pg_dump -U postgres notarysigner > ${BACKUP_DIR}/notary_signer.sql
cp /opt/harbor/harbor.yml ${BACKUP_DIR}/
cp -r /opt/harbor/certs ${BACKUP_DIR}/
rsync -av /data/harbor/ ${BACKUP_DIR}/harbor_data/
tar -czf ${BACKUP_DIR}.tar.gz ${BACKUP_DIR}
rm -rf ${BACKUP_DIR}
echo "Backup completed: ${BACKUP_DIR}.tar.gz"
10.4 Prometheus 监控配置
scrape_configs:
- job_name: 'harbor'
static_configs:
- targets: ['harbor.yourdomain.com']
metrics_path: '/api/v2.0/metrics'
basic_auth:
username: 'admin'
password: 'Harbor12345'
- 镜像总数
- 项目总数
- 用户总数
- 存储使用量
- 漏洞扫描统计
- API 请求延迟
- 容器健康状态