Harbor私有镜像仓库搭建教程：从零开始完整实操指南

为什么需要自己的镜像仓库

在生产环境中，频繁从公共镜像仓库拉取容器镜像存在网络延迟、安全风险和管理不便的问题。
Harbor 是一个开源的私有镜像仓库，提供镜像存储、权限控制、漏洞扫描和复制等功能。
本文围绕 Harbor私有镜像仓库搭建教程，带你在 Linux 服务器上从零完成部署，适合刚接触容器化的小团队或个人开发者。

第一步：准备好运行环境

搭建前需要确认服务器满足以下条件：

• 操作系统：CentOS 7.x 或 Ubuntu 20.04+（本文以 CentOS 7.9 为例）
• 硬件：至少 2 核 CPU、4GB 内存、50GB 磁盘（镜像会占用大量空间）
• 软件：Docker（20.10+）和 Docker Compose（1.29+）

安装 Docker（如果未安装）：

curl -fsSL https://get.docker.com | bash
sudo systemctl start docker
sudo systemctl enable docker

安装 Docker Compose：

sudo curl -L "https://github.com/docker/compose/releases/latest/download/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。

第二步：下载并部署 Harbor

Harbor 提供在线安装和离线安装两种方式。
对于内网环境，推荐使用离线包。

1. 下载 Harbor 离线包（以 2.11.0 版本为例，具体版本可到 GitHub Releases 页查看最新）：

wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar -zxvf harbor-offline-installer-v2.11.0.tgz
cd harbor

1. 生成配置文件：

cp harbor.yml.tmpl harbor.yml

编辑 harbor.yml，至少要修改以下几项：

• hostname：改为服务器的 IP 或域名（例如 192.168.1.100）
• http.port：默认 80，如果 80 被占用可以改成 8080（同时后面访问地址也要加端口）
• 如果配置 HTTPS，需要提供证书路径；测试环境可先注释掉 HTTPS 相关行

重点：如果使用 HTTPS，需要提前准备好 SSL 证书；
如果不配置，务必确认 hostname 不能带协议。

1. 执行安装脚本：

sudo ./install.sh

安装过程会下载 Docker 镜像并启动 Harbor 所有组件（Nginx、Registry、UI 等）。
约 5-10 分钟完成，看到 ✔ ----Harbor has been installed and started successfully.---- 即表示成功。

第三步：登录与验证

打开浏览器访问 http://服务器IP（如果修改了端口则加端口号）。
默认管理员账号 admin，密码 Harbor12345。
登录后可以进行以下操作：

• 创建项目（如 myproject）
• 创建用户并赋予项目权限
• 查看镜像存储状态

推送一个测试镜像到 Harbor：

先在 Docker 客户端登录：

docker login 服务器IP
# 输入 admin / Harbor12345

给本地镜像打标签并推送：

docker pull nginx:latest
docker tag nginx:latest 服务器IP/myproject/nginx:latest
docker push 服务器IP/myproject/nginx:latest

推送成功后，在 Harbor Web 界面的 myproject 项目下可以看到该镜像。

避坑指南与常见问题

Q：安装时提示容器启动失败？

A：通常是端口被占用。
检查 80、443、8080 等端口是否被其他服务占用。
修改 harbor.yml 中的端口后重新执行 sudo ./install.sh。

Q：无法通过 HTTP 拉取镜像？

A：Docker 默认只允许 HTTPS 仓库。
如果使用 HTTP，需要在每个 Docker 客户端的 /etc/docker/daemon.json 中添加 "insecure-registries": ["你的HarborIP:端口"]，然后重启 Docker。

Q：磁盘空间不足怎么办？

A：Harbor 默认将镜像存储在 /data 目录。
可以在 harbor.yml 中修改 data_volume 路径到有大容量挂载点的目录（如 /mnt/harbor_data）。

Q：如何重置管理员密码？

A：
进入 Harbor 容器：docker exec -it harbor-core /bin/bash，
然后执行 /harbor/change_admin_password.sh 按提示操作。

总结与后续维护

本文完整的 Harbor私有镜像仓库搭建教程到此结束。
部署完成后建议立即修改默认密码、配置 HTTPS 证书（生产环境必须）、开启自动垃圾回收和镜像复制功能。
如果遇到文中未覆盖的报错，大部分都可以通过 docker-compose logs 查看组件日志定位原因。
后续还可以集成 LDAP 认证、配置漏洞扫描等高级功能，请继续关注相关专题文章。