DevOps全链路实战 | 第 1 天：从零搭建 Harbor 私有镜像仓库

第 1/20 天

引言

在 DevOps 实践中，容器镜像是软件交付的核心载体。无论是 CI/CD 流水线构建的产物，还是手动部署的应用镜像，都需要一个可靠的私有镜像仓库来统一管理、分发和版本控制。Docker Hub 虽然方便，但在生产环境中存在带宽限制、安全风险和合规问题。

本系列「DevOps全链路实战」将带你从零搭建一条完整的 DevOps 管线：Harbor 私有镜像仓库 → GitLab CI 流水线 → Argo CD GitOps 部署 → Prometheus/Grafana 可观测性 → Argo Rollouts 渐进式交付。

今天第 1 天，我们聚焦 Harbor —— 业界最流行的开源容器镜像管理平台，为后续所有环节的镜像存储做好基础设施准备。

一、Harbor 是什么？

Harbor 由 VMware 开源（现属于云原生计算基金会 CNCF），是一个支持企业级特性的容器镜像管理平台。相比 Docker Hub 和 AWS ECR，Harbor 在企业场景下具有明显优势：

特性	Docker Hub	AWS ECR	Harbor
私有部署	❌	❌（云厂商）	✅
镜像签名	❌	✅	✅
漏洞扫描	❌	✅	✅（Trivy）
复制同步	❌	❌	✅
访问控制	基础	IAM	RBAC + LDAP/AD
镜像代理	❌	❌	✅
许可证	开源	商业	Apache 2.0

核心功能一览

1. 镜像管理：多架构镜像、版本标签、GC 垃圾回收
2. 安全能力：Trivy 漏洞扫描、镜像签名（cosign）、内容信任
3. 复制与同步：多仓库级联、跨地域复制
4. 权限控制：项目级 RBAC、OIDC/LDAP 集成
5. 通知集成：Webhook、邮件、Slack、企业微信
6. 镜像代理：透明缓存上游镜像，加速拉取

二、环境准备

硬件要求

Harbor 官方推荐最低配置：

CPU: 2 核
内存: 4 GB
磁盘: 10 GB（SSD 推荐）

生产环境建议 4 核 8G 起步。

系统要求

# 操作系统：Ubuntu 22.04 / 24.04 或 CentOS 7.9+
cat /etc/os-release

# 确认 Docker 已安装
docker version

# 确认 Docker Compose 已安装（v2 推荐）
docker compose version

注意： Harbor 1.10+ 依赖 Docker Compose v2（docker compose 命令，无连字符）。如果系统只有 v1（docker-compose），需升级。

安装 Docker 和 Docker Compose v2

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | 
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加 Docker 软件源
echo 
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] 
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" 
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine + Compose 插件
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

# 启动并设置开机自启
sudo systemctl enable docker
sudo systemctl start docker

# 添加当前用户到 docker 组（免 sudo）
sudo usermod -aG docker $USER
newgrp docker

准备 Harbor 安装主机

推荐在干净的 Ubuntu 22.04/24.04 服务器上进行：

# 关闭 swap（Harbor 官方要求）
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

# 配置防火墙（开放 HTTP/HTTPS）
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# 配置域名解析（可选但推荐）
# 在 /etc/hosts 中添加
echo "192.168.1.100 harbor.example.com" >> /etc/hosts

三、安装 Harbor

方式一：在线自动安装（推荐）

下载 Harbor 官方安装脚本并执行：

# 下载最新版本的安装脚本
curl -fsSL https://raw.githubusercontent.com/goharbor/harbor/main/install/harbor-online-installer.sh 
  -o harbor-online-installer.sh

chmod +x harbor-online-installer.sh

# 执行安装（交互式，需要输入配置）
sudo ./harbor-online-installer.sh

安装过程中需要配置的关键参数：

1. 配置路径（config path）: ./harbor.yml
2. Harbor 安装路径: /opt/harbor
3. Harbor 安装域名: harbor.example.com
4. 是否启用 HTTPS: y（推荐）
5. 证书路径: 使用自签名或接入 Let's Encrypt
6. Harbor 管理员密码: 设置一个强密码

方式二：使用 Docker Compose 手动部署

如果对配置有更精细的控制需求，可以手动准备配置文件：

# 下载 Harbor 二进制包
wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-2.9.0-linux-amd64.tar.gz

# 解压
sudo tar -xzf harbor-2.9.0-linux-amd64.tar.gz -C /opt

# 进入安装目录
cd /opt/harbor

# 复制模板配置
cp harbor.yml.tmpl harbor.yml

Harbor 核心配置文件详解

编辑 /opt/harbor/harbor.yml，以下是关键配置项：

# Harbor.yml 关键配置
hostname: harbor.example.com

http:
  port: 80

https:
  port: 443
  certificate: /etc/letsencrypt/live/harbor.example.com/fullchain.pem
  private_key: /etc/letsencrypt/live/harbor.example.com/privkey.pem

# 管理员密码（首次安装，后续在 Web UI 修改）
harbor_admin_password: Harbor12345

# 数据存储后端（默认本地文件系统）
# 生产环境建议接入 NFS 或 MinIO
storage_service:
  filesystem:
    max_job_workers: 3
    controller:
      persist_interval: 10
  registry_storage:
    filesystem:
      max_mount_retries: 5
      root_per_project: true
      disable_s3_delete: false

# 数据库（默认使用内置 PostgreSQL）
database:
  max_old_conns: 1
  idle_timeout: 30
  max_connections: 200
  port: 5432
  max_replica_num: 1
  session_timeout: 0
  ssl_mode: disable
  connect_timeout: 1
  host: postgresql
  schema: public
  search_path: public
  port: 5432
  extension_schema: aurora
  migration_schema: golang_migrate
  extension_connection_lifetime: 0

# 对象存储（默认本地文件系统，生产建议 MinIO/S3）
# 本地存储配置示例
# production:
#   components:
#     registry:
#       storage_provider:
#         name: filesystem
#         options:
#           rootpath: /storage/registry

# 漏洞扫描配置（默认启用 Trivy）
scan_all: false
use_trivy: true

# 镜像复制（同步到其他 Harbor 或 ACR/ECR）
# harbor_job_service:
#   max_job_workers: 10
#   max_job_history_kept: 200

启动 Harbor

# 进入安装目录
cd /opt/harbor

# 执行安装脚本
sudo ./install.sh

# 查看容器状态
sudo docker ps

正常情况下应该看到以下容器运行：

harbor-portal      # 前端 Web UI
harbor-nginx       # 反向代理
harbor-core        # API 服务
harbor-db          # PostgreSQL 数据库
harbor-jobservice  # 后台任务
harbor-registry    # 镜像存储
harbor-redis       # 缓存
harbor-log         # 日志收集
harbor-db-migrator # 数据库迁移

四、验证安装

访问 Harbor 管理界面

打开浏览器访问 http://harbor.example.com（未配置 SSL 时）：

用户名: admin
密码: 你在 harbor.yml 中设置的 harbor_admin_password

首次登录后系统会提示修改密码，强烈建议修改为强密码。

使用 Docker CLI 验证推拉镜像

# 登录 Harbor
docker login harbor.example.com
# Username: admin
# Password: 你的密码

# 拉取一个测试镜像
docker pull alpine:latest

# 重新打标签
docker tag alpine:latest harbor.example.com/library/alpine:latest

# 推送到 Harbor
docker push harbor.example.com/library/alpine:latest

输出类似：

The push refers to repository [harbor.example.com/library/alpine]
b3e9b0f70113: Pushed
626a908a39c6: Pushed
latest: digest: sha256:abc123... size: 1362

查看镜像是否已存储

登录 Web UI → 点击「Library」→ 选择 library 项目 → 可以看到刚推送的 alpine 镜像及其 latest 标签。

五、Harbor 日常运维

查看服务状态

# 查看所有容器状态
docker ps --format "table {{.Names}}t{{.Status}}"

# 查看某个容器的日志
docker logs -f harbor-core

# 重启某个服务
docker restart harbor-core

数据备份

Harbor 数据主要存储在三处：

# 1. 配置文件
cp /opt/harbor/harbor.yml /backup/harbor.yml.bak

# 2. 镜像仓库数据（默认路径）
tar czf /backup/registry-data.tar.gz /storage/registry

# 3. 数据库（PostgreSQL 内置）
docker exec harbor-db pg_dump -U postgres -d harbor_db -f /backup/harbor_db.sql
docker cp harbor-db:/backup/harbor_db.sql /backup/

升级到最新版本

# 1. 备份当前数据和配置
# 2. 下载新版本安装包
wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-2.9.0-linux-amd64.tar.gz
sudo tar -xzf harbor-2.9.0-linux-amd64.tar.gz -C /opt

# 3. 合并配置（保留自定义项）
cd /opt/harbor
cp harbor.yml harbor.yml.bak
cp harbor.yml.tmpl harbor.yml
# 将 harbor.yml.bak 中的自定义配置合并回 harbor.yml

# 4. 停止旧版本
sudo ./stop.sh

# 5. 执行升级安装
sudo ./install.sh

清理垃圾镜像

# 方式一：Web UI
# 项目设置 → 配额 → 启用 GC
# 系统设置 → 仓库管理 → 运行 GC

# 方式二：CLI
docker exec harbor-jobservice harbor jobs gc

六、常见问题排查

问题 1：docker push 返回 unauthorized: authentication required

原因： 未登录或凭据过期。

# 重新登录
docker login harbor.example.com

问题 2：Harbor 页面返回 502 Bad Gateway

原因： 通常是 Nginx 容器未正常启动。

# 检查 Nginx 容器状态
docker logs harbor-nginx

# 查看 Nginx 配置
docker exec harbor-nginx cat /etc/nginx/nginx.conf

# 重启所有容器
docker compose down
docker compose up -d

问题 3：镜像推送失败 no space left on device

原因： 本地存储满了。

# 检查磁盘使用
df -h /storage

# 启用垃圾回收清理旧镜像
# 或更换为远程存储（MinIO/S3）

问题 4：HTTPS 证书错误

# 使用自签名证书快速测试（生产环境请使用 Let's Encrypt）
openssl req -newkey rsa:4096 -nodes -keyout harbor.key -out harbor.csr 
  -subj "/CN=harbor.example.com"
openssl x509 -req -days 365 -in harbor.csr -signkey harbor.key -out harbor.crt

# 在 harbor.yml 中指定证书路径

问题 5：数据库连接失败

# 检查 PostgreSQL 容器状态
docker ps | grep harbor-db

# 查看数据库日志
docker logs harbor-db

# 重启数据库容器
docker restart harbor-db

# 确认 harbor.yml 中数据库配置与容器名一致

七、安全加固最佳实践

1. 启用 HTTPS

生产环境必须使用 HTTPS：

# harbor.yml
https:
  port: 443
  certificate: /etc/letsencrypt/live/harbor.example.com/fullchain.pem
  private_key: /etc/letsencrypt/live/harbor.example.com/privkey.pem

2. 启用漏洞扫描

Harbor 内置 Trivy 漏洞扫描器，可以自动检测镜像中的已知 CVE：

# harbor.yml
scan_all: true  # 推送镜像时自动扫描

在 Web UI 中查看镜像的扫描结果，包含 CVE 编号、严重程度、修复建议。

3. 配置访问控制

# 创建服务账号用于 CI/CD 推送
# 用户 → 创建用户 → 设置为「机器人」账号
# 项目名称: robot$ci-bot
# 权限: 项目级 Push + Pull

# 使用服务账号登录
docker login harbor.example.com
# Username: robot$ci-bot
# Password: 服务账号密码

4. 限制外部访问

# 通过 Nginx 反向代理添加 IP 白名单
# 在 /etc/nginx/conf.d/harbor.conf 中：
location / {
    # 限制为公司内网 IP
    allow 192.168.0.0/16;
    deny all;
    proxy_pass http://harbor-nginx:80;
}

八、总结

今天我们完成了 DevOps 全链路实战的第一站——Harbor 私有镜像仓库的搭建。回顾一下关键步骤：

1. 环境准备：安装 Docker Engine + Docker Compose v2，关闭 swap，配置域名
2. 安装部署：通过安装脚本或手动 Docker Compose 部署
3. 配置管理：理解 harbor.yml 中的关键配置项（存储、数据库、扫描、安全）
4. 验证推拉：使用 docker push/pull 验证镜像仓库可用性
5. 运维监控：容器状态检查、日志查看、数据备份、版本升级
6. 安全加固：HTTPS、漏洞扫描、服务账号、访问控制

明天第 2 天，我们将基于 Harbor 搭建 GitLab CI 流水线，实现代码提交后自动构建镜像并推送到 Harbor，打通 DevOps 管线的第一环。

---

📋 本系列大纲
1. Harbor 私有镜像仓库（今天）
2. GitLab CI 流水线搭建
3. GitLab Runner 注册与配置
4. CI 流水线：构建 + 测试 + 镜像推送
5. Kubernetes 集群搭建（K3s）
6. Argo CD 安装与配置
7. GitOps 工作流：声明式部署
8. 应用镜像部署到 K8s
9. Prometheus 监控安装
10. Grafana 仪表盘搭建
11. 自定义监控指标
12. Alertmanager 告警配置
13. Argo Rollouts 安装
14. 蓝绿部署实战
15. 金丝雀发布实战
16. 渐进式交付自动化
17. 全链路监控告警集成
18. 安全加固与合规
19. 灾备与高可用
20. 全链路回顾与最佳实践

⚡ 本文为「DevOps全链路实战」系列第 1 天，每天更新一篇文章，从零搭建完整的 DevOps 管线。