1. 项目概述为什么我们需要一个私有的镜像仓库在容器化与云原生技术成为主流的今天无论是个人开发者还是企业团队都绕不开一个核心组件容器镜像仓库。Docker Hub 作为公共仓库方便快捷但它在生产环境中存在诸多限制拉取速率限制、网络延迟、镜像安全审计缺失以及最重要的——企业核心资产业务镜像的私有化管控需求。这时搭建一个私有、安全、高性能的镜像仓库就从一个“可选项”变成了“必选项”。Harbor这个由 VMware 公司开源后捐赠给 CNCF 并最终毕业的项目正是为此而生。它不仅仅是一个 Docker Registry 的简单封装更是一个企业级的私有镜像仓库解决方案。它提供了镜像的漏洞扫描、签名与内容信任、基于角色的访问控制、镜像复制、图形化管理界面等一系列生产级功能。简单来说Harbor 让你能像管理代码一样安全、可控、高效地管理你的容器镜像资产。这次我们不谈空洞的理论直接上手。我将带你从零开始在一个典型的 Linux 服务器上完成 Harbor 私有仓库的完整安装与基础配置。整个过程我会穿插我踩过的坑和总结的最佳实践目标是让你部署完毕后能立刻用于实际的 CI/CD 流水线中。2. 环境准备与规划兵马未动粮草先行在敲下第一条安装命令之前充分的准备工作能避免 80% 的后续问题。安装 Harbor 不是简单地跑个 Docker 命令它涉及到系统资源、网络、存储和依赖组件的协同。2.1 硬件与系统要求首先你需要一台服务器。对于测试和小型团队一台拥有 2 核 CPU、4GB 内存、50GB 磁盘的虚拟机或云主机就足够了。但对于生产环境我建议至少 4 核 8GB 内存磁盘空间根据镜像存储量预估并强烈建议使用 SSD 以提升 IO 性能。操作系统方面我推荐Ubuntu 20.04/22.04 LTS或CentOS/Rocky Linux 7.9/8.x。它们拥有长期支持社区资源丰富能减少兼容性问题。本文将以Ubuntu 22.04为例进行演示。注意确保服务器可以访问互联网以下载必要的安装包和 Docker 镜像。如果处于内网环境你需要提前准备好所有离线安装包。2.2 核心依赖安装Docker 与 Docker ComposeHarbor 本身是以容器化方式运行的因此 Docker 和 Docker Compose 是必须的前置条件。1. 安装 Docker Engine在 Ubuntu 上我习惯使用 Docker 官方提供的安装脚本稳定且版本新。# 更新 apt 包索引 sudo apt-get update # 安装必要的依赖包以便 apt 可以通过 HTTPS 使用仓库 sudo apt-get install -y \ ca-certificates \ curl \ gnupg \ lsb-release # 添加 Docker 的官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /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 \ $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 再次更新 apt 包索引 sudo apt-get update # 安装 Docker Engine、CLI、Containerd 等 sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后启动 Docker 服务并设置开机自启sudo systemctl start docker sudo systemctl enable docker2. 安装 Docker Compose (独立版本)虽然 Docker 现在内置了docker compose插件但 Harbor 的安装脚本目前仍主要兼容独立的docker-composev1 版本。为了兼容性我们安装它。# 下载 Docker Compose 的稳定版本例如 1.29.2 sudo curl -L https://github.com/docker/compose/releases/download/v1.29.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 赋予可执行权限 sudo chmod x /usr/local/bin/docker-compose # 验证安装 docker-compose --version # 应输出类似docker-compose version 1.29.2, build xxxxxxx3. 配置非 root 用户运行 Docker可选但推荐为了避免每次都要用sudo可以将当前用户加入docker组。sudo usermod -aG docker $USER执行此命令后你需要退出当前终端并重新登录或者执行newgrp docker使组权限生效。2.3 系统参数优化为了让 Harbor 运行得更顺畅需要对 Linux 系统内核参数进行一些调整。# 编辑 sysctl 配置文件 sudo vim /etc/sysctl.conf在文件末尾添加或修改以下参数# 增加系统最大文件描述符数量 fs.file-max 1000000 # 增加网络连接相关参数应对高并发 net.core.somaxconn 65535 net.ipv4.tcp_max_syn_backlog 262144 net.core.netdev_max_backlog 262144 # 减少 TCP 连接超时时间加快资源回收 net.ipv4.tcp_fin_timeout 30 net.ipv4.tcp_max_tw_buckets 6000 # 允许端口快速重用 net.ipv4.tcp_tw_reuse 1 net.ipv4.tcp_tw_recycle 0 # 在较新内核中此参数已被废弃或建议设为0 # 增加系统最大进程数 kernel.pid_max 65535保存后使配置生效sudo sysctl -p实操心得net.ipv4.tcp_tw_recycle这个参数在 NAT 网络环境下比如大多数云服务器容易引起连接问题导致 Harbor 的某些组件如 Core、Jobservice之间通信异常。我曾在生产环境踩过这个坑现象是 Web 界面能打开但推送镜像一直失败。将其设置为0是最稳妥的做法。3. Harbor 安装包获取与配置Harbor 提供了在线和离线两种安装包。离线包包含了所有必需的 Docker 镜像适合内网或无外网环境我们选择它。3.1 下载 Harbor 离线安装包访问 Harbor 的 GitHub Releases 页面 选择最新的稳定版本。本文以v2.7.2为例。# 创建一个工作目录 mkdir -p ~/harbor cd ~/harbor # 下载离线安装包 wget https://github.com/goharbor/harbor/releases/download/v2.7.2/harbor-offline-installer-v2.7.2.tgz # 解压 tar xzvf harbor-offline-installer-v2.7.2.tgz cd harbor解压后你会看到几个关键文件harbor.yml.tmpl 主配置文件模板。install.sh 安装脚本。prepare 配置准备脚本。common.sh 公共函数脚本。docker-compose.yml Harbor 服务的编排定义。3.2 深度解析与定制 harbor.yml 配置文件这是安装 Harbor 最核心的一步配置文件决定了 Harbor 的访问方式、数据存储、认证模式等。直接复制模板并开始编辑cp harbor.yml.tmpl harbor.yml vim harbor.yml下面我们逐部分拆解这个配置文件并说明每个关键参数的意义和配置建议。1. 主机名与协议 (hostname和protocol)# 主机名或IP地址用于访问Harbor UI和注册服务 hostname: reg.yourdomain.com # 通信协议http 或 https protocol: httpshostname 这是最重要的配置之一。它必须是客户端Docker 守护进程、kubectl 等能够解析的域名或 IP 地址。如果你有域名并配置了 DNS就填域名如harbor.company.com。如果只是内网测试可以填服务器内网 IP如192.168.1.100。不推荐在生产环境使用 IP因为证书和后续配置会很麻烦。绝对不要填写localhost或127.0.0.1因为其他机器上的 Docker 客户端无法通过这个地址访问。protocol 生产环境必须使用https。Docker 客户端默认要求与私有仓库进行安全连接localhost 除外。我们将使用自签名证书进行配置。2. HTTPS 证书配置 (certificate和private_key)# https 相关配置 https: # https 端口默认为 443 port: 443 # 你的 SSL 证书路径 certificate: /your/certificate/path # 你的 SSL 私钥路径 private_key: /your/private/key/path如果你没有购买商业 SSL 证书可以使用 OpenSSL 生成自签名证书。在 Harbor 目录下操作# 创建证书目录 mkdir -p /data/cert cd /data/cert # 生成私钥 openssl genrsa -out ca.key 4096 # 生成证书签名请求 (CSR) # 注意Common Name (CN) 必须与上面 harbor.yml 中的 hostname 完全一致 openssl req -x509 -new -nodes -sha512 -days 3650 \ -subj /CCN/STBeijing/LBeijing/Oexample/OUPersonal/CNreg.yourdomain.com \ -key ca.key \ -out ca.crt然后在harbor.yml中配置证书路径certificate: /data/cert/ca.crt private_key: /data/cert/ca.key注意事项使用自签名证书后所有要连接 Harbor 的客户端服务器、CI/CD 机器、开发机都需要信任这个 CA 证书否则会报x509: certificate signed by unknown authority错误。对于 Docker 客户端需要将ca.crt文件放到/etc/docker/certs.d/your-harbor-hostname/目录下。3. 管理员密码与数据持久化 (harbor_admin_password和data_volume)# Harbor 管理员初始密码 harbor_admin_password: Harbor12345 # 数据存储路径 data_volume: /dataharbor_admin_password 安装后 Web 界面管理员 (admin) 的密码。务必在安装后第一时间修改data_volume Harbor 所有持久化数据的存储根目录包括数据库、镜像存储、日志等。确保该目录所在磁盘有充足空间。我通常将其挂载到一块独立的大容量数据盘上。4. 数据库与 Redis 配置 (database和redis)这部分通常保持默认即可除非你有外部的高可用 PostgreSQL/Redis 集群需要对接。# 数据库配置 database: password: root123 max_idle_conns: 50 max_open_conns: 100 # Redis 配置用于作业服务和缓存 redis: password: redis1235. 外部存储配置可选但重要默认情况下Harbor 将镜像存储在本地文件系统 (data_volume下的registry目录)。对于生产环境强烈建议配置外部存储如 AWS S3、Google Cloud Storage、Azure Blob Storage 或兼容 S3 的存储如 MinIO。以配置 S3 兼容存储为例storage_service: s3: accesskey: YOUR_ACCESS_KEY secretkey: YOUR_SECRET_KEY region: us-east-1 bucket: your-harbor-bucket endpoint: https://s3.amazonaws.com # 或者你的 MinIO 地址 chunksize: 5242880 # 分片大小 rootdirectory: /harbor # 在 bucket 中的根目录 encrypt: false secure: true v4auth: true配置外部存储后data_volume下将只存储元数据镜像 Blob 数据会存储在对象存储中便于扩展和备份。6. 其他关键功能开关在配置文件中部你可以看到一系列功能开关根据需求启用# 启用 Clair 镜像漏洞扫描需要额外资源 clair: enabled: false # 改为 true 启用 # 启用 Trivy 镜像漏洞扫描更轻量推荐 trivy: enabled: true # 默认已启用 # 启用 Notary 镜像内容信任 notary: enabled: false # 镜像复制策略用于多 Harbor 实例同步 jobservice: max_job_workers: 10 notification: enabled: false对于初次安装我建议先保持trivy启用用于安全扫描其他如clair、notary可以后续按需开启。4. 执行安装与初始化配置完成后就可以运行安装脚本了。安装脚本会做几件事根据harbor.yml生成最终的docker-compose.yml、拉取必要的镜像离线包已包含、创建网络和卷、并启动所有容器。# 在 harbor 目录下执行 sudo ./install.sh如果一切顺利你将看到类似下面的输出最后提示Harbor has been installed and started successfully.。安装完成后使用docker-compose ps命令查看所有服务状态确保所有容器都是Up (healthy)状态。cd /your/harbor-path docker-compose ps输出应显示corejobserviceportalregistryredisdatabase等核心服务均为健康运行状态。此时打开浏览器访问https://your-harbor-hostname如https://reg.yourdomain.com。由于是自签名证书浏览器会提示不安全需要手动接受风险并继续。使用用户名admin和你在配置文件中设置的密码默认Harbor12345登录。5. 安装后的关键配置与集成安装成功只是第一步要让 Harbor 真正融入你的 CI/CD 流程还需要进行一些关键配置。5.1 配置 Docker 客户端信任自签名证书这是让其他机器能够向 Harbor 推送/拉取镜像的关键一步。假设你的 Harbor 主机名为reg.yourdomain.com。在 Harbor 服务器上将之前生成的ca.crt证书文件分发到客户端机器。在客户端机器上创建 Docker 证书目录目录名必须与 Harbor 的hostname完全一致sudo mkdir -p /etc/docker/certs.d/reg.yourdomain.com将ca.crt证书复制到该目录sudo cp ca.crt /etc/docker/certs.d/reg.yourdomain.com/重启 Docker 服务使配置生效sudo systemctl restart docker现在你可以在客户端使用docker login reg.yourdomain.com登录并使用docker push/pull命令了。5.2 创建项目与配置用户权限Harbor 采用“项目”来组织镜像类似于 Docker Hub 的命名空间。创建项目 登录 Harbor Web 界面点击“新建项目”。例如为你的微服务团队创建一个名为backend-services的项目。可以设置为“公开”所有人可拉取或“私有”需授权。创建机器人账户 在 CI/CD 流水线中不应使用个人账号密码。Harbor 提供了“机器人账户”功能。进入项目 -机器人账户-新建机器人账户。为其赋予推送和拉取权限并保存生成的 Token用户名和密码。这个 Token 就是 CI 脚本中用于docker login的凭证。配置 Webhook 如果你想在镜像推送成功后触发后续操作如通知 Kubernetes 更新部署可以配置 Webhook。进入项目 -Webhook-新建 Webhook填写接收事件的 URL例如你的 CI 服务器或 Kubernetes 操作器的端点。5.3 与 CI/CD 工具集成以 Jenkins 为例在 Jenkins Pipeline 中集成 Harbor 推送镜像的典型步骤pipeline { agent any environment { HARBOR_CREDENTIALS credentials(harbor-robot-account-id) // 在Jenkins中预先配置的凭据 HARBOR_HOST reg.yourdomain.com PROJECT_NAME backend-services IMAGE_NAME user-service } stages { stage(Build Push Image) { steps { script { // 1. 登录 Harbor sh docker login -u ${HARBOR_CREDENTIALS_USR} -p ${HARBOR_CREDENTIALS_PSW} ${HARBOR_HOST} // 2. 构建镜像并打标签 sh docker build -t ${HARBOR_HOST}/${PROJECT_NAME}/${IMAGE_NAME}:${BUILD_NUMBER} . sh docker tag ${HARBOR_HOST}/${PROJECT_NAME}/${IMAGE_NAME}:${BUILD_NUMBER} ${HARBOR_HOST}/${PROJECT_NAME}/${IMAGE_NAME}:latest // 3. 推送镜像 sh docker push ${HARBOR_HOST}/${PROJECT_NAME}/${IMAGE_NAME}:${BUILD_NUMBER} sh docker push ${HARBOR_HOST}/${PROJECT_NAME}/${IMAGE_NAME}:latest } } } } }6. 运维、升级与故障排查6.1 日常运维命令Harbor 通过docker-compose管理所有运维操作都应在 Harbor 安装目录下进行。查看服务状态docker-compose ps查看日志查看所有服务日志docker-compose logs查看特定服务如 core日志docker-compose logs -f core停止 Harbordocker-compose down(这会停止容器但保留数据卷)启动 Harbordocker-compose up -d重启单个服务docker-compose restart service_name 如docker-compose restart portal6.2 数据备份与恢复备份 Harbor 的数据主要存在于两个地方数据库PostgreSQL 存储用户、项目、策略等元数据。存储卷data_volume配置的路径默认为/data 存储镜像文件、Chart 文件等。最可靠的备份方式是停止 Harbordocker-compose down备份整个数据目录例如/data和数据库导出。也可以使用 Harbor 官方提供的harbor.yml中的backup功能如果配置了外部存储备份会更简单。一个简单的脚本化备份示例#!/bin/bash BACKUP_DIR/backup/harbor-$(date %Y%m%d) mkdir -p $BACKUP_DIR cd /your/harbor-path # 1. 停止服务 docker-compose down # 2. 备份数据卷假设数据卷为 /data tar czf $BACKUP_DIR/data.tar.gz /data # 3. 备份数据库进入数据库容器执行dump docker-compose exec database pg_dump -U postgres registry $BACKUP_DIR/registry_backup.sql # 4. 备份配置文件 cp harbor.yml $BACKUP_DIR/ # 5. 重新启动服务 docker-compose up -d echo Backup completed at $BACKUP_DIR恢复 过程与备份相反将备份文件解压到相应位置并导入数据库然后启动服务。6.3 版本升级Harbor 的升级相对平滑。务必在升级前进行完整备份前往 Harbor 安装目录停止当前服务docker-compose down下载新版本的离线安装包并解压。将旧版本的harbor.yml配置文件复制到新版本目录中。根据新版本的发布说明检查harbor.yml是否有配置项变更并进行相应调整。在新版本目录下运行升级脚本sudo ./install.sh --with-trivy --with-chartmuseum(根据你需要的组件添加参数)脚本会自动迁移数据库和数据。6.4 常见问题排查实录问题1推送镜像时报错x509: certificate signed by unknown authority原因 Docker 客户端不信任 Harbor 服务器的自签名证书。解决 确保已按照5.1节的步骤将ca.crt正确放置到客户端的/etc/docker/certs.d/harbor_hostname/目录下并重启 Docker。问题2Web 界面可以访问但docker login失败提示Error response from daemon: Get https://reg.yourdomain.com/v2/: dial tcp: lookup reg.yourdomain.com on ...原因 客户端无法解析harbor.yml中配置的hostname。解决在客户端机器的/etc/hosts文件中添加一条记录harbor_server_ip reg.yourdomain.com或者配置内网 DNS 服务器将该域名解析到 Harbor 服务器 IP。问题3推送大镜像时超时或失败原因 可能是网络问题或 Docker 客户端/服务器配置限制。解决在 Docker 客户端和服务器的daemon.json(/etc/docker/daemon.json) 中增加超时和缓存配置{ max-concurrent-uploads: 10, max-download-attempts: 10, shutdown-timeout: 30 }检查 Harbor 所在服务器的网络带宽和防火墙设置。如果使用 HTTP 代理确保 Docker 已正确配置代理。问题4Harbor 服务启动后部分容器状态为Restarting或Unhealthy原因 最常见的原因是资源不足内存、磁盘或依赖服务如数据库启动超时。解决使用docker-compose logs -f service_name查看具体容器的错误日志。检查服务器内存和磁盘空间free -hdf -h。尝试增加 Docker 守护进程的内存和 CPU 限制。对于数据库启动问题可以尝试单独重启数据库容器docker-compose restart database并观察其日志。问题5Web 界面访问非常慢原因 前端 Portal 服务资源不足或浏览器缓存问题。解决检查服务器资源使用情况。尝试清理浏览器缓存或使用无痕模式访问。可以适当调整docker-compose.yml中portal服务的资源限制如mem_limit。安装和配置 Harbor 是一个系统工程涉及网络、存储、安全和运维多个层面。我的经验是严格按照官方文档操作理解每个配置项的含义并在测试环境充分验证后再上生产。一旦 Harbor 稳定运行它将成为你容器化运维体系中坚实可靠的一环大大提升镜像管理的安全性和效率。