Harbor 私有镜像仓库完整部署文档(Ubuntu 24.04)


1. 环境要求

项目

要求

操作系统

Ubuntu 24.04

CPU

2 核+

内存

4 GB+

磁盘

40 GB+

Docker

17.06.0+

Docker Compose

1.18.0+


2. 安装 Docker 和 Docker Compose

### 2.1 安装 Docker

 # 安装依赖包
 sudo apt update
 sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
 ​
 # 使用阿里云镜像源安装 Docker
 curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
 ​
 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 ​
 sudo apt update
 sudo apt install -y docker-ce docker-ce-cli containerd.io
 ​
 # 将当前用户加入 docker 组
 sudo usermod -aG docker $USER
 ​
 # 安装 Docker Compose 插件
 sudo apt install -y docker-compose-plugin
 ​
 # 验证安装
 docker --version
 docker compose version

2.2 配置 Docker 镜像加速器

 sudo mkdir -p /etc/docker
 ​
 sudo tee /etc/docker/daemon.json <<-'EOF'
 {
   "registry-mirrors": [
     "https://docker.m.daocloud.io",
     "https://dockerproxy.com",
     "https://docker.nju.edu.cn"
   ]
 }
 EOF
 ​
 sudo systemctl daemon-reload
 sudo systemctl restart docker


3. 下载 Harbor 离线包

 cd /opt
 ​
 # 下载 Harbor v2.10.0 离线包
 wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
 ​
 # 如果下载太慢,按 Ctrl+C 取消,使用国内镜像:
 # wget https://mirrors.aliyun.com/docker-ce/harbor/harbor-offline-installer-v2.10.0.tgz
 ​
 # 解压
 tar xzf harbor-offline-installer-v2.10.0.tgz
 cd harbor


4. 生成 SSL 证书

⚠️ 注意:将以下命令中的 192.168.7.7 替换为你的服务器实际 IP

 # 创建证书目录
 mkdir -p /opt/harbor-certs
 cd /opt/harbor-certs
 ​
 # 生成 CA 私钥
 openssl genrsa -out ca.key 4096
 ​
 # 生成 CA 证书
 openssl req -x509 -new -nodes -sha512 -days 3650 \
   -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=192.168.7.7" \
   -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=192.168.7.7" \
   -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]
 IP.1=192.168.7.7
 DNS.1=harbor.example.com
 EOF
 ​
 # 使用 CA 签署证书
 openssl x509 -req -sha512 -days 3650 \
   -extfile v3.ext \
   -CA ca.crt -CAkey ca.key -CAcreateserial \
   -in server.csr \
   -out server.crt
 ​
 # 验证证书文件
 ls -la
 # 应该看到: ca.crt, ca.key, server.crt, server.key, server.csr, v3.ext


5. 配置 Harbor

⚠️ 重要:max_job_workers 必须在 jobservice 层级下,否则安装会失败!

 cd /opt/harbor
 ​
 # 删除旧配置(如果有)
 rm -f harbor.yml
 ​
 # 创建完整配置文件
 cat > harbor.yml << 'EOF'
 # Harbor 配置文件
 hostname: 192.168.7.7
 ​
 # HTTPS 配置
 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: 100
   max_open_conns: 900
   conn_max_lifetime: 5m
   conn_max_idle_time: 0
 ​
 # 数据存储路径
 data_volume: /data/harbor
 ​
 # Trivy 漏洞扫描配置
 trivy:
   ignore_unfixed: false
   skip_update: false
   offline_scan: false
   security_check: vuln
   insecure: false
 ​
 # Job 服务配置(⚠️ 必须放在 jobservice 下!)
 jobservice:
   max_job_workers: 10
   job_loggers:
     - STD_OUTPUT
     - FILE
   logger_sweeper_duration: 1
 ​
 # 通知配置
 notification:
   webhook_job_max_retry: 3
   webhook_job_http_client_timeout: 3
 ​
 # 日志配置
 log:
   level: info
   local:
     rotate_count: 50
     rotate_size: 200M
     location: /var/log/harbor
 ​
 # 版本信息(⚠️ 必须是 _version,不是 version!)
 _version: 2.10.0
 ​
 # 代理配置
 proxy:
   http_proxy:
   https_proxy:
   no_proxy:
   components:
     - core
     - jobservice
     - trivy
 ​
 # 上传清理配置
 upload_purging:
   enabled: true
   age: 168h
   interval: 24h
   dryrun: false
 ​
 # 缓存配置
 cache:
   enabled: false
   expire_hours: 24
 EOF
 ​
 # 验证配置
 cat harbor.yml | grep -v "^#" | grep -v "^$"


6. 安装 Harbor

 cd /opt/harbor
 ​
 # 清理之前的缓存(如果有)
 rm -rf /opt/harbor/common
 ​
 # 执行安装
 ./install.sh

预期输出(成功标志):

 [+] up 10/10
  ✔ Network harbor_harbor       Created
  ✔ Container harbor-log        Started
  ✔ Container registryctl       Started
  ✔ Container redis             Started
  ✔ Container harbor-portal     Started
  ✔ Container registry          Started
  ✔ Container harbor-db         Started
  ✔ Container harbor-core       Started
  ✔ Container nginx             Started
  ✔ Container harbor-jobservice Started
 ✔ ----Harbor has been installed and started successfully.----

6.1 验证安装

 # 查看所有容器状态
 docker compose ps
 ​
 # 预期:9 个容器全部运行,状态为 Up
 # harbor-core, harbor-db, harbor-jobservice, harbor-log,
 # harbor-portal, nginx, redis, registry, registryctl
 ​
 # 测试 HTTPS 访问
 curl -k https://192.168.7.7
 ​
 # 检查端口监听
 sudo ss -tlnp | grep 443


7. 配置 Docker 客户端

7.1 配置证书信任

# 创建证书目录
sudo mkdir -p /etc/docker/certs.d/192.168.7.7

# 复制证书
sudo cp /opt/harbor-certs/server.crt /etc/docker/certs.d/192.168.7.7/ca.crt
sudo chmod 644 /etc/docker/certs.d/192.168.7.7/ca.crt

# 重启 Docker
sudo systemctl restart docker

# 启动 Harbor
cd /opt/harbor
docker compose up -d

7.2 登录 Harbor

docker login 192.168.7.7 -u admin -p Harbor12345

预期输出:
Login Succeeded


8. 测试验证

8.1 推送镜像测试

# 拉取测试镜像
docker pull hello-world

# 打标签
docker tag hello-world 192.168.7.7/library/hello-world:test

# 推送到 Harbor
docker push 192.168.7.7/library/hello-world:test

# 拉取验证
docker pull 192.168.7.7/library/hello-world:test

8.2 浏览器访问

打开浏览器访问:https://192.168.7.7

  • 用户名:admin

  • 密码:Harbor12345

登录后,在 library 项目中应该能看到 hello-world:test 镜像。


9. 常用运维命令

cd /opt/harbor

# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f              # 所有日志
docker compose logs proxy --tail=50 # nginx 日志
docker compose logs core --tail=50  # 核心服务日志

# 停止 Harbor
docker compose down

# 启动 Harbor
docker compose up -d

# 重启 Harbor
docker compose restart

# 完全重建(清理后重新安装)
docker compose down -v
rm -rf /opt/harbor/common
./install.sh

# 垃圾回收(释放磁盘空间)
# 方式1:Web UI → 系统管理 → 垃圾回收 → 立即回收
# 方式2:API 触发
curl -X POST -u "admin:Harbor12345" \
  "https://192.168.7.7/api/v2.0/system/gc/schedule" \
  -H "Content-Type: application/json" \
  -d '{"schedule":{"type":"Manual"}}' -k

# 备份数据
tar czf /root/harbor-backup-$(date +%Y%m%d).tar.gz /data/harbor

# 升级 Harbor(下载新版后)
docker compose down
./upgrade.sh


📋 部署信息汇总

项目

信息

Harbor 地址

https://192.168.7.7

管理员账号

admin

管理员密码

Harbor12345

安装目录

/opt/harbor

数据目录

/data/harbor

证书目录

/opt/harbor-certs

镜像推送格式

docker push 192.168.7.7/项目名/镜像名:标签