Docker 私有仓库 Harbor 搭建与镜像推送（系列第六篇：企业私有镜像仓库实战）

文章目录

- 前言
- [一、Harbor 核心认知与架构介绍](#一、Harbor 核心认知与架构介绍)
- - [1.1 什么是 Harbor？](#1.1 什么是 Harbor？)
  - [1.2 为什么企业不用原生 Registry，首选 Harbor？](#1.2 为什么企业不用原生 Registry，首选 Harbor？)
  - [1.3 Harbor 核心架构组件（通俗讲解）](#1.3 Harbor 核心架构组件（通俗讲解）)
  - [1.4 适用场景区分](#1.4 适用场景区分)
- [二、单机版 Harbor 快速部署（零报错实战）](#二、单机版 Harbor 快速部署（零报错实战）)
- - [2.1 下载 Harbor 离线安装包](#2.1 下载 Harbor 离线安装包)
  - [2.2 核心配置文件修改](#2.2 核心配置文件修改)
  - [2.3 解决内网 HTTP 镜像推送报错](#2.3 解决内网 HTTP 镜像推送报错)
  - [2.4 一键安装启动 Harbor](#2.4 一键安装启动 Harbor)
  - [2.5 访问 Harbor 后台](#2.5 访问 Harbor 后台)
  - [2.6 Harbor 日常启停命令](#2.6 Harbor 日常启停命令)
- 三、镜像打标签、推送私有仓库（完整实操）
- - [3.1 核心原理](#3.1 核心原理)
  - [3.2 实操步骤](#3.2 实操步骤)
  - - 第一步：本地准备自定义镜像
    - 第二步：给镜像打私有仓库标签（关键步骤）
    - [第三步：本地登录私有 Harbor 仓库](#第三步：本地登录私有 Harbor 仓库)
    - 第四步：推送镜像到私有仓库
    - 第五步：服务器拉取私有镜像
- 四、企业团队协作镜像版本管理规范
- - [4.1 项目空间分类管理](#4.1 项目空间分类管理)
  - [4.2 镜像版本命名规范（企业标准）](#4.2 镜像版本命名规范（企业标准）)
  - [4.3 团队权限分配](#4.3 团队权限分配)
  - [4.4 镜像生命周期管理](#4.4 镜像生命周期管理)
- 五、本篇总结

前言

通过前五篇文章的学习，我们已经掌握了 Docker 镜像制作、容器运行、数据持久化、网络配置、Compose 多容器编排，能够快速搭建本地完整开发环境。

但在真实企业团队开发、服务器部署场景中，我们会遇到一个核心问题：自定义镜像无法高效共享、统一管理。

默认的 Docker 公共仓库 Docker Hub 存在诸多企业使用痛点：

外网访问速度慢、拉取镜像超时，严重影响部署效率
公共仓库镜像公开透明，项目业务镜像上传存在代码与数据安全风险
免费仓库有镜像数量、存储容量限制，无法适配企业大量业务镜像存储
没有权限管控、版本管理、镜像清理、安全扫描等企业级功能，无法适配团队协作

为了解决企业镜像私有化存储、团队共享、版本管控的需求，Harbor 企业级私有镜像仓库成为行业标准解决方案。

本篇带你从零掌握 Harbor 架构原理、单机快速部署、镜像打标推送、团队协作版本管理，是 Docker 进阶、企业项目上线、微服务集群部署的必备技能。

一、Harbor 核心认知与架构介绍

1.1 什么是 Harbor？

Harbor 是 VMware 开源、CNCF 认证的企业级 Docker 私有镜像仓库，基于原生 Docker Registry 二次开发，弥补了原生 Registry 功能简陋、无界面、无权限管控的短板。

简单理解：Harbor 就是企业内部的私人 Docker Hub，专门用于存储、管理、分发团队自定义的业务镜像，支持内网高速访问、权限隔离、版本管控，是目前企业使用最广泛的私有镜像仓库。

1.2 为什么企业不用原生 Registry，首选 Harbor？

Docker 原生 Registry 仅具备基础的镜像存储、推拉功能，无任何企业级能力，而 Harbor 拥有完整的生产级能力：

可视化 Web 界面：直观管理项目、镜像、版本、用户，操作简单
精细化权限管理：支持管理员、开发、测试多角色权限隔离，适配团队协作
镜像版本管理：支持版本标记、删除、保留策略、镜像清理
安全扫描：自动检测镜像漏洞，规避安全风险
日志审计：记录所有镜像推拉、用户操作日志，便于运维排查
高可用扩展：支持单机、集群部署，适配开发、测试、生产全环境

1.3 Harbor 核心架构组件（通俗讲解）

Harbor 本身是基于 Docker Compose 编排的多容器应用，核心由 6 大组件组成，新手只需掌握核心作用即可：

Registry（核心仓库）：原生镜像存储组件，负责真正存储、接收、分发 Docker 镜像
UI（可视化界面）：Web 管理后台，提供项目创建、镜像查看、权限配置、日志查询功能
Database（数据库）：存储用户信息、项目配置、权限规则、镜像元数据（版本、大小、上传时间）
Log（日志服务）：统一收集所有组件操作日志，用于审计和问题排查
Notary（安全签名）：实现镜像签名校验，防止镜像被篡改，保障镜像安全
Clair（漏洞扫描）：自动扫描镜像系统漏洞、依赖漏洞，企业生产必备安全能力

1.4 适用场景区分

单机 Harbor：适合中小企业、开发测试环境、日常团队协作，部署简单、运维成本低（本篇重点）
集群 Harbor：适合大型企业、生产高可用环境，搭配负载均衡实现容灾扩容

二、单机版 Harbor 快速部署（零报错实战）

Harbor 官方推荐使用 离线安装包 + Docker Compose 部署，部署简单、环境兼容稳定，是企业单机部署的标准方案。

前置环境要求：已安装 Docker、Docker Compose（前两篇已讲解安装方式）

2.1 下载 Harbor 离线安装包

选用企业稳定版 v2.10.3（兼容性强、bug 少，生产通用），推荐离线包部署，无需在线拉取镜像：

bash 复制代码

# 创建安装目录
mkdir -p /usr/local/harbor
cd /usr/local/harbor

# 下载离线安装包
wget https://github.com/goharbor/harbor/releases/download/v2.10.3/harbor-offline-installer-v2.10.3.tgz

# 解压安装包
tar -zxvf harbor-offline-installer-v2.10.3.tgz
cd harbor-offline-installer-v2.10.3

2.2 核心配置文件修改

解压后复制模板配置文件，生成正式配置文件并修改核心参数，这是部署成功的关键：

bash 复制代码

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

# 编辑配置文件
vim harbor.yml

重点修改以下 3 项核心配置（新手仅改这几项即可，其余默认）：

yaml 复制代码

# 1、修改仓库地址（服务器IP/域名，本机就写本机IP）
hostname: 192.168.3.100

# 2、关闭https（开发/内网环境必备，避免证书报错）
# http端口配置
http:
  port: 8080

# 这里不使用https，注释该配置
#https:
  # https port for harbor, default is 443
#  port: 443
  # The path of cert and key files for nginx
#  certificate: /your/certificate/path
#  private_key: /your/private/key/path  

# 3、设置管理员初始密码（自定义，记住后续登录使用）
harbor_admin_password: Harbor123456

# 4、数据存储路径（建议默认，持久化镜像数据）
data_volume: /data/harbor

2.3 解决内网 HTTP 镜像推送报错

Docker 默认禁止 HTTP 不安全仓库推送镜像，需要手动配置信任私有仓库地址，否则后续 push 会报错：

bash 复制代码

# 创建docker配置文件
vim /etc/docker/daemon.json

写入以下配置（替换为你的 Harbor 服务器 IP）：

json 复制代码

{
  "insecure-registries": ["192.168.3.100:80"]
}

重启 Docker 生效配置：

bash 复制代码

systemctl daemon-reload
systemctl restart docker

2.4 一键安装启动 Harbor

执行官方安装脚本，自动生成 Compose 配置、启动所有 Harbor 容器：

bash 复制代码

# 一键安装并后台启动
./install.sh -d

2.5 访问 Harbor 后台

启动完成后，浏览器访问：http://你的服务器IP

用户名：admin
密码：刚才配置的 Harbor123456

登录成功即代表私有仓库部署完成，全程无复杂配置，开箱即用。

2.6 Harbor 日常启停命令

Harbor 基于 Docker Compose 编排，所有操作均在安装目录执行：

bash 复制代码

# 停止Harbor
docker compose down

# 启动Harbor
docker compose up -d

# 重启Harbor
docker compose restart

三、镜像打标签、推送私有仓库（完整实操）

部署完 Harbor 后，核心实操就是本地镜像上传私有仓库、服务器拉取私有镜像，这是企业上线的核心流程。

完整流程：本地镜像 → 打私有仓库标签 → 登录仓库 → 推送镜像 → 服务器拉取镜像

3.1 核心原理

Docker 推送镜像时，会根据镜像前缀标签识别仓库地址：

无前缀：默认推送到官方 Docker Hub
自定义前缀（仓库IP/域名）：推送到指定私有 Harbor 仓库

3.2 实操步骤

第一步：本地准备自定义镜像

以 SpringBoot 业务镜像为例，本地已有镜像：springboot-demo:1.0

第二步：给镜像打私有仓库标签（关键步骤）

标签格式：Harbor地址/项目名/镜像名:版本号

bash 复制代码

# 格式：docker tag 原镜像:版本 仓库IP/项目名/镜像名:版本
docker tag springboot-demo:1.0 192.168.3.100/dev/springboot-demo:1.0

说明：dev 是 Harbor 后台创建的项目名称，用于分类管理镜像。

第三步：本地登录私有 Harbor 仓库

bash 复制代码

docker login 192.168.3.100 -u admin -p Harbor123456

提示 Login Succeeded 即登录成功。

第四步：推送镜像到私有仓库

bash 复制代码

docker push 192.168.3.100/dev/springboot-demo:1.0

推送完成后，登录 Harbor 后台，即可看到刚刚上传的镜像，支持在线查看、下载、删除。

第五步：服务器拉取私有镜像

其他开发/服务器配置信任仓库后，直接拉取镜像：

bash 复制代码

docker login 192.168.3.100
docker pull 192.168.3.100/dev/springboot-demo:1.0

四、企业团队协作镜像版本管理规范

Harbor 最大的企业价值就是标准化团队镜像管理，解决多人开发镜像混乱、版本不统一、镜像丢失的问题，下面是企业通用落地规范。

4.1 项目空间分类管理

在 Harbor 后台创建不同项目，实现环境与业务隔离，通用规范：

dev：开发环境镜像，存放开发测试版本
test：测试环境镜像，存放测试验收版本
prod：生产环境镜像，仅存放稳定上线版本
public：公共基础镜像（mysql、redis、nginx 等），全员可拉取

4.2 镜像版本命名规范（企业标准）

杜绝 latest 模糊版本，采用时间+功能+环境精准版本号，避免版本覆盖丢失：

开发版：项目名-v1.0.0-dev-20260510
测试版：项目名-v1.0.0-test-20260510
生产版：项目名-v1.0.0-prod

优势：版本可追溯、可回滚、不会误覆盖正式镜像。

4.3 团队权限分配

管理员：负责仓库配置、项目创建、权限分配、镜像清理
开发人员：仅拥有 dev 项目推拉权限，禁止操作生产镜像
测试人员：拥有 test 项目查看、拉取权限

实现权限隔离，避免误删、误改生产镜像，保障线上环境稳定。

4.4 镜像生命周期管理

开启 Harbor 自动清理策略：自动清理30天未使用的开发镜像，释放磁盘空间
生产镜像永久保留，如需更新版本，新增版本号不覆盖旧版本
上线前通过 Harbor 漏洞扫描，杜绝高危漏洞镜像上线

五、本篇总结

1、Harbor 是企业级私有镜像仓库，弥补了官方 Docker Hub 不安全、速度慢、无管控的短板，是团队开发、项目上线的必备基础设施；

2、Harbor 基于 Docker Compose 多容器部署，核心由仓库、UI、数据库、日志、安全扫描组件构成，结构清晰、运维简单；

3、单机版 Harbor 部署核心：关闭 HTTPS、配置 Docker 信任私有仓库、一键脚本安装，新手可快速落地；

4、镜像推拉核心流程：打私有标签 → 登录仓库 → 推送镜像 → 远程拉取，是企业镜像分发的标准流程；

5、通过 Harbor 项目分类、版本规范、权限管控，可实现团队镜像标准化管理，彻底解决镜像混乱、版本不一致、安全风险等问题，为后续 K8s 集群镜像部署打下基础。