Start Chat
Search
Ithy Logo

Harbor 容器镜像仓库：全面安装与配置指南

构建您的企业级私有镜像管理平台

harbor-installation-guide-f8tvaqlr

Harbor 是一个企业级的云原生容器镜像仓库，专为 Docker 和 Kubernetes 等平台设计，提供了一套强大的管理工具，用于存储、管理和分发容器镜像。它扩展了开源 Docker Registry 的功能，增加了许多企业级特性，例如安全性、身份验证、访问控制（RBAC）、审计日志、图形化管理界面、镜像复制以及漏洞扫描等，使其成为企业私有镜像仓库的理想选择。

以下是安装 Harbor 的关键亮点：

  • 多种安装方式： Harbor 支持在线和离线两种安装方式，灵活适应不同网络环境，尤其适合内网环境部署。
  • 组件化架构： Harbor 由多个 Docker 容器组成，通过 Docker Compose 进行管理，每个组件负责不同的功能，如核心服务、数据库、日志、反向代理等。
  • 企业级特性： Harbor 不仅仅是镜像存储，更提供了高级安全功能（如漏洞扫描）、身份认证（LDAP/AD集成）、权限管理和审计日志，满足企业对镜像管理的严格要求。

Harbor 架构与核心组件解析

在深入安装步骤之前，了解 Harbor 的架构和核心组件至关重要。Harbor 的设计理念是模块化和容器化，所有功能都通过 Docker 容器来实现，并通过 Docker Compose 进行协调管理。

Harbor Architecture Diagram

Harbor 的主要组件及其交互示意图

Harbor 的主要组件包括：

  • Proxy (Nginx)： 作为前端反向代理，统一接收来自浏览器和 Docker 客户端的请求，并将其转发给后端不同的服务。
  • Registry： 官方 Docker 镜像仓库，负责实际的镜像存储，并处理 docker push 和 docker pull 命令。它与 Harbor 的令牌服务交互，确保只有携带合法 token 的请求才能访问。
  • Core Services (UI/API)： Harbor 的核心服务，提供图形化管理界面和 RESTful API，用于用户管理、项目管理、镜像管理等。
  • Database (PostgreSQL/MySQL)： 为核心服务提供数据存储，保存用户权限、审计日志、Docker 镜像分组信息等数据。
  • Job Service： Harbor 的任务管理服务，负责执行一些后台任务，如镜像复制、垃圾回收、漏洞扫描等。
  • Log： 运行着 rsyslog 的容器，用于收集和管理所有 Harbor 组件的日志。
  • Redis： 用于存储会话信息和缓存数据，提高系统性能。
  • Trivy Adapter (可选)： 提供镜像漏洞检测功能，扫描镜像中的已知漏洞。
  • Chart Museum (可选)： 提供 Helm Chart 仓库服务，用于存储和管理 Helm Charts。

这些组件协同工作，共同构建了一个功能强大、安全可靠的企业级镜像仓库。

安装 Harbor 的先决条件与准备工作

确保您的环境已准备就绪

在安装 Harbor 之前，需要确保您的服务器环境满足以下基本要求：

  • 操作系统： 推荐使用 CentOS 7+、Ubuntu 等主流 Linux 发行版。
  • Docker： Harbor 依赖 Docker 引擎来运行其各个组件，因此需要安装 Docker CE (Community Edition) 17.03.0-ce 或更高版本。
  • Docker Compose： Harbor 使用 Docker Compose 来管理其多容器应用，因此需要安装 Docker Compose 1.18.0 或更高版本。
  • 硬件资源： 建议至少 2 核 CPU、4GB 内存和足够的硬盘空间（取决于您存储的镜像数量）。生产环境建议更多资源。
  • 网络： 确保服务器具备网络连接，以便下载 Harbor 安装包和 Docker 镜像。对于离线安装，则不需要外部网络连接。
  • 端口开放： Harbor 默认会使用以下端口，请确保这些端口未被占用且已在防火墙中开放：
    • 80 (HTTP)： 用于 Harbor 门户和核心 API 的 HTTP 请求（通常会重定向到 HTTPS）。
    • 443 (HTTPS)： Harbor 门户和核心 API 接受 HTTPS 请求。
    • 4443 (HTTPS)： 与 Harbor 的 Docker 内容信任服务 (Notary) 的连接，仅在启用 Notary 时需要。

安装 Docker 与 Docker Compose

如果您的服务器尚未安装 Docker 和 Docker Compose，可以按照以下步骤进行安装（以 CentOS 为例）：


# 卸载旧版本Docker（如果存在）
sudo yum remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-engine

# 安装所需的依赖包
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

# 添加 Docker 的官方 YUM 仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker CE
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker version
docker-compose version

注意： 您可以配置 Docker 镜像加速器（例如阿里云、腾讯云等），以加快 Docker 镜像的下载速度。


sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": ["https://<your-mirror-id>.mirror.aliyuncs.com"]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Harbor 的安装方式：在线与离线

选择适合您的部署策略

Harbor 提供了两种主要的安装方式：在线安装和离线安装。选择哪种方式取决于您的服务器网络环境和部署需求。

在线安装

在线安装方式简单快捷，适合能够连接到互联网的服务器。它会从 Docker Hub 下载 Harbor 相关镜像，因此安装包体积较小。安装速度取决于您的网络带宽。

Online Installation Steps

在线安装 Harbor 的一个示例界面

离线安装

离线安装方式适合部署 Harbor 的主机没有连接到互联网的环境（例如公司内网）。离线安装包包含了预先构建好的所有 Harbor 镜像，因此安装包体积较大。这种方式可以避免因网络问题导致镜像下载失败或缓慢。

大多数企业级部署会优先选择离线安装，以确保稳定性和安全性。以下是离线安装的详细步骤：

Harbor Offline Installer Package

Harbor 离线安装包的内容预览

分步指南：离线安装 Harbor

从下载到启动的详细过程

第一步：下载 Harbor 离线安装包

访问 Harbor 的 GitHub Release 页面 (https://github.com/goharbor/harbor/releases)，下载最新稳定版本的离线安装包（例如 harbor-offline-installer-vX.Y.Z.tgz）。


# 创建一个目录用于存放Harbor安装文件
mkdir -p /usr/local/harbor
cd /usr/local/harbor

# 下载Harbor离线安装包（这里以一个示例版本为例，请替换为最新版本）
# 如果服务器无法直接访问GitHub，请先下载到本地再上传到服务器
wget https://github.com/goharbor/harbor/releases/download/v2.9.1/harbor-offline-installer-v2.9.1.tgz

第二步：解压安装包

将下载的压缩包解压到您选择的安装目录中：


tar -zxvf harbor-offline-installer-v2.9.1.tgz -C /usr/local/harbor/
# 解压后会生成一个名为harbor的目录，进入该目录
cd /usr/local/harbor/harbor

解压后的目录中包含 harbor.yml.tmpl（配置文件模板）和 install.sh（安装脚本）等重要文件。

第三步：配置 Harbor

复制 harbor.yml.tmpl 为 harbor.yml，并根据您的实际需求进行修改。这是安装过程中最关键的步骤之一。


cp harbor.yml.tmpl harbor.yml
vim harbor.yml

主要修改的配置项包括：

配置项 描述 示例值
hostname Harbor 服务的主机名或 IP 地址。这是 Docker 客户端访问 Harbor 的地址。 your.harbor.domain.com 或 192.168.1.100
port Harbor 门户和核心 API 的 HTTP 端口。通常会设置为 80 或其他未被占用的端口。 80 (HTTP) 或 443 (HTTPS)
harbor_admin_password Harbor 管理员 (admin) 用户的初始密码。强烈建议修改为强密码。 MySecurePass123
data_volume Harbor 数据卷的存储路径，用于存储镜像、数据库数据、日志等。确保该路径有足够的空间。 /data/harbor (默认)
https 是否启用 HTTPS。生产环境强烈建议启用 HTTPS。如果启用，需要配置证书和私钥路径。 
https:
  port: 443
  certificate: /your/certificate/path/harbor.crt
  private_key: /your/private/key/path/harbor.key
clair 是否启用 Clair（镜像漏洞扫描）。 enabled: true 或 false
trivy 是否启用 Trivy（镜像漏洞检测）。 enabled: true 或 false

如果选择启用 HTTPS，您需要生成或准备好您的 SSL 证书和私钥文件，并将其路径配置在 harbor.yml 中。示例如下：


# 生成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=your.harbor.domain.com" \
  -key ca.key \
  -out ca.crt
# 生成服务器证书私钥
openssl genrsa -out your.harbor.domain.com.key 4096
# 生成证书签名请求（CSR）
openssl req -sha512 -new \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=your.harbor.domain.com" \
  -key your.harbor.domain.com.key \
  -out your.harbor.domain.com.csr
# 使用CA证书签名服务器证书
openssl x509 -req -sha512 -days 3650 \
  -extfile <(printf "subjectAltName=DNS:your.harbor.domain.com,IP:192.168.1.100") \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -in your.harbor.domain.com.csr \
  -out your.harbor.domain.com.crt

然后将 your.harbor.domain.com.crt 和 your.harbor.domain.com.key 放置到 harbor.yml 中指定的路径。

第四步：运行安装脚本

配置完成后，运行安装脚本 install.sh。您可以根据需要添加参数来启用可选组件：

  • --with-clair：启用 Clair 漏洞扫描器。
  • --with-trivy：启用 Trivy 漏洞检测器。
  • --with-notary：启用内容信任服务。
  • --with-chartmuseum：启用 Chart Museum (Helm Chart 仓库)。

# 进入Harbor安装目录
cd /usr/local/harbor/harbor

# 运行安装脚本
./install.sh --with-trivy --with-chartmuseum

安装脚本会自动加载离线安装包中的 Docker 镜像，生成必要的配置文件，并通过 Docker Compose 启动所有 Harbor 服务。

安装成功后，您会看到类似以下输出：


----Harbor has been installed and started successfully.----
Now you should be able to visit the admin portal at http://your.harbor.domain.com or https://your.harbor.domain.com

第五步：验证 Harbor 运行状态

使用 docker-compose ps 命令检查所有 Harbor 容器的运行状态，确保它们都处于 Up 状态：


cd /usr/local/harbor/harbor
docker-compose ps

您应该会看到类似以下输出：


      Name                     Command               State      Ports
--------------------------------------------------------------------------
harbor-core          /harbor/entrypoint.sh ...   Up (healthy) 80/tcp
harbor-db            /docker-entrypoint.sh ...   Up (healthy) 5432/tcp
harbor-jobservice    /harbor/entrypoint.sh ...   Up (healthy) 80/tcp
harbor-log           /bin/sh -c /usr/loca...   Up (healthy) 127.0.0.1:1514->10514/tcp
harbor-portal        /harbor/entrypoint.sh ...   Up (healthy) 80/tcp
harbor-registry      /etc/docker/registry...   Up (healthy) 5000/tcp
harbor-registryctl   /harbor/harbor_regis...   Up (healthy) 80/tcp
harbor-trivy-adapt...  /usr/local/bin/trivy-...   Up (healthy) 80/tcp

第六步：访问 Harbor 网页界面

在浏览器中访问您在 harbor.yml 中配置的 hostname 和端口（例如 http://your.harbor.domain.com 或 https://your.harbor.domain.com）。

使用默认管理员用户名 admin 和您在 harbor.yml 中设置的 harbor_admin_password 登录。

Harbor Login Page

Harbor 登录页面

Harbor Dashboard

Harbor 管理控制台概览

Harbor 部署与使用能力评估

多维度考量 Harbor 在企业环境中的表现

为了更直观地评估 Harbor 在企业级镜像仓库中的表现，我将通过一个雷达图展示其在关键能力上的综合评分。这些评分基于 Harbor 的常见功能、社区支持以及部署实践经验。

从雷达图中可以看出，Harbor 在安全性、扩展性、功能丰富性方面表现突出，远超基础的 Docker Registry。这得益于其集成的漏洞扫描、身份认证、权限管理和丰富的管理界面。虽然在易用性方面安装配置步骤相对基础 Registry 略复杂，但考虑到其提供的企业级功能，这是可以接受的。社区与支持以及性能与稳定性方面，Harbor 作为一个广泛使用的开源项目，也拥有良好的表现。

Harbor 的日常操作与管理

推送、拉取镜像与基本配置

成功安装 Harbor 后，您可以开始使用它来管理您的容器镜像。

配置 Docker 客户端

为了让 Docker 客户端能够与 Harbor 交互，如果您的 Harbor 使用的是 HTTP 协议（非 HTTPS），需要将 Harbor 地址添加到 Docker 的不安全仓库列表中。如果使用 HTTPS 并配置了有效的证书，则无需此步骤。


# 修改Docker daemon配置文件
sudo vim /etc/docker/daemon.json
# 添加或修改 insecure-registries 字段
# 如果已经有 registry-mirrors，请注意JSON格式
{
  "insecure-registries": ["your.harbor.domain.com:80"]
}
# 重启Docker服务
sudo systemctl daemon-reload
sudo systemctl restart docker

登录 Harbor

使用 Docker 命令行登录到您的 Harbor 仓库：


docker login your.harbor.domain.com
Username: admin
Password: [您在harbor.yml中设置的密码]

登录成功后，您的凭据将保存在 ~/.docker/config.json 中。

制作和推送镜像

首先，您需要有一个 Docker 镜像。您可以构建自己的镜像或使用现有镜像。然后，为镜像打上 Harbor 仓库的标签：


# 假设您有一个名为 'my-app' 的镜像，版本为 '1.0'
# 为镜像打tag，格式为：[Harbor地址]/[项目名]/[镜像名]:[版本]
docker tag my-app:1.0 your.harbor.domain.com/myproject/my-app:1.0

# 推送镜像到Harbor
docker push your.harbor.domain.com/myproject/my-app:1.0

在 Harbor 网页界面中，您可以创建一个新的项目 (Project)，例如 myproject，然后将镜像推送到该项目中。

从 Harbor 拉取镜像

从 Harbor 仓库拉取镜像非常简单：


docker pull your.harbor.domain.com/myproject/my-app:1.0

Harbor 与持续集成/持续部署 (CI/CD)

赋能自动化部署流程

Harbor 在 CI/CD 流程中扮演着核心角色，作为私有镜像的中央存储，它确保了镜像的安全、可靠分发。结合 Jenkins、GitLab CI 等工具，可以实现从代码提交到镜像构建、存储和部署的自动化流程。

该视频展示了 DevOps 训练营中关于 GitLab CI 集成制品库和 Harbor 镜像库实践的内容，非常适合了解 Harbor 在自动化部署中的作用。

视频中提到的“Harbor 镜像库实践”环节，正是讨论了如何将 Harbor 作为一个不可或缺的组件融入到 DevOps 工作流中。通过 Harbor，企业可以：

  • 统一镜像管理： 所有团队成员将构建的镜像推送到同一个Harbor仓库，避免版本混乱和重复构建。
  • 安全漏洞扫描： 在镜像进入生产环境前，Harbor 可以自动对镜像进行漏洞扫描，及时发现并修复潜在安全问题。
  • 权限细粒度控制： 通过项目和用户管理，可以为不同团队或成员设置不同的镜像访问权限。
  • 镜像复制与高可用： Harbor 支持跨区域或跨数据中心镜像复制，提高镜像分发的效率和可用性。

例如，在 Jenkins 或 GitLab CI 中配置流水线时，可以将镜像构建步骤的输出直接推送到 Harbor，然后部署工具（如 Kubernetes）再从 Harbor 拉取镜像进行部署。


# 示例 Jenkinsfile 片段 (Groovy)
pipeline {
    agent any
    stages {
        stage('Build Image') {
            steps {
                script {
                    sh "docker build -t your.harbor.domain.com/myproject/my-app:${env.BUILD_NUMBER} ."
                }
            }
        }
        stage('Push Image') {
            steps {
                script {
                    withCredentials([usernamePassword(credentialsId: 'harbor-credentials', passwordVariable: 'HARBOR_PASSWORD', usernameVariable: 'HARBOR_USERNAME')]) {
                        sh "docker login -u ${HARBOR_USERNAME} -p ${HARBOR_PASSWORD} your.harbor.domain.com"
                        sh "docker push your.harbor.domain.com/myproject/my-app:${env.BUILD_NUMBER}"
                    }
                }
            }
        }
        stage('Deploy to Kubernetes') {
            steps {
                script {
                    # 使用 kubectl 或 Helm 从 Harbor 拉取镜像并部署
                    sh "kubectl set image deployment/my-app my-app=your.harbor.domain.com/myproject/my-app:${env.BUILD_NUMBER}"
                }
            }
        }
    }
}

这种集成方式极大地提升了软件交付的速度和可靠性。

常见问题解答 (FAQ)

Harbor 安装失败怎么办？

首先，检查您的服务器是否满足所有先决条件，特别是 Docker 和 Docker Compose 的版本。其次，仔细检查 harbor.yml 配置文件，确保所有路径、端口和凭据都正确无误。查看安装日志（通常在 /var/log/harbor/ 目录下）或通过 docker-compose logs 命令查看容器日志，找出具体的错误信息。常见的错误包括端口冲突、存储空间不足、网络问题（无法下载镜像）或证书配置错误。

Harbor 是否支持高可用部署？

是的，Harbor 支持高可用部署。您可以通过 Helm 在 Kubernetes 集群上安装 Harbor 来实现高可用。这种部署方式通常涉及多个 Harbor 实例、共享存储（如 NFS、S3 等）和高可用数据库集群，以确保服务的持续可用性。

如何升级已有的 Harbor 版本？

升级 Harbor 通常需要下载新版本的安装包，更新 harbor.yml 配置文件，并执行升级脚本。Harbor 官方文档提供了详细的升级指南，通常会涉及数据迁移以适应新版本的数据库架构。在升级前，强烈建议备份所有数据。

Harbor 如何集成 LDAP/AD 进行用户认证？

Harbor 提供了内置的 LDAP/AD 集成功能。您可以在 Harbor 的管理界面中配置 LDAP/AD 服务器的连接信息、用户和组的搜索规则等，从而将企业现有的用户体系与 Harbor 进行对接，实现统一身份认证。

结论

Harbor 作为一款功能强大、企业级的云原生容器镜像仓库，为 Docker 和 Kubernetes 用户提供了全面的镜像管理解决方案。从初始的 Docker 及 Docker Compose 环境准备，到离线安装包的下载、配置和部署，再到最终的日常使用和与 CI/CD 流程的集成，Harbor 都展现出其卓越的实用性和可靠性。通过本文的详细指南，希望您能够顺利地在自己的环境中搭建并高效管理您的私有容器镜像仓库。

推荐阅读

参考搜索结果

blog.csdn.net
一文读懂Harbor以及部署实践攻略原创 - CSDN博客
zhuanlan.zhihu.com
Harbor 快速部署指南 - 知乎专栏
docsv4.qingcloud.com
部署Harbor 镜像仓库 - 公有云文档中心
blog.csdn.net
Harbor 部署、操作使用指南原创 - CSDN博客
bambrow.com
私有镜像仓库Harbor 极简搭建指南（HTTP 版） - Bambrow's Blog
cnblogs.com
docker harbor-入门指南 - 博客园
huangzhongde.cn
4.2 部署企业级私有仓库Harbor · Istio实战指南
developer.aliyun.com
harbor 部署入门指南（1） - 阿里云开发者社区
cnblogs.com
Harbor私有仓库部署与配置-http - lldhsds - 博客园
blog.csdn.net
Harbor 的安装及使用_goharbor-CSDN博客
juejin.cn
Harbor安装及配置 - 稀土掘金
fwhyy.com
私有镜像仓库Harbor 安装和使用- 冯威的博客
cnblogs.com
Harbor的安装与使用 - 博客园
blog.csdn.net
Harbor安装教程-完全根据官方文档2.6.0版本 - CSDN博客
cnblogs.com
安装Harbor的简单过程（仅使用http 未使用https） - 博客园
cloud.tencent.com
私有镜像仓库Harbor 安装和使用- 腾讯云
chengchaos.github.io
Harbor 安装 - Red Dragonfly
docs.deepin.org
harbor 部署入门指南（1） - deepin开发者平台
learnku.com
企业级镜像仓库Harbor 的安装与配置 - LearnKu
Last updated June 3, 2025
Ask Ithy AI
Download Article
Delete Article
Help|Privacy|Terms