Harbor镜像仓库搭建：从零部署到推送验证

Harbor 是一个开源的容器镜像仓库，用来在自有服务器上存放和分发 Docker 镜像。
搭建它的核心步骤是：准备一台 Linux 服务器，安装 Docker 与 Docker Compose，下载 Harbor 离线安装包，修改 harbor.yml 里的主机名和密码，执行 install.sh 启动，最后在客户端配置信任并推送一个测试镜像。
下面按顺序说明，适合零基础照做。

环境准备与版本确认

Harbor 官方通过 Docker Compose 编排多个容器运行，所以宿主机必须先有可用的 Docker 环境。
建议使用 2 核 4G 以上的 Linux 服务器，磁盘预留 40G 以上，因为镜像层会持续占用空间。

先确认系统信息并安装依赖：

cat /etc/os-release
uname -m

安装 Docker（以常见发行版为例，具体源地址以官方文档为准）：

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker version

再安装 Docker Compose 插件并确认：

docker compose version

如果输出类似 Docker Compose version v2.x，说明环境可用。
没有输出时，需要先补装 compose 插件，否则 Harbor 的 install.sh 会报找不到 compose 命令。

获取安装包与修改 harbor.yml

到 Harbor 官方发布页下载离线安装包，本文不写死具体版本号，请以官方页面当前稳定版为准。
下载后解压：

tar -xzf harbor-offline-installer-*.tgz
cd harbor
ls

目录里会有 harbor.yml.tmpl，复制一份再改，保留模板方便对照：

cp harbor.yml.tmpl harbor.yml
vi harbor.yml

需要重点改这几项：

• hostname：改成服务器 IP 或已解析的域名，例如 192.168.1.10。客户端推送时会用这个地址，写错会导致登录失败。
• harbor_admin_password：设置管理员初始密码，不要保留默认值。
• data_volume：数据存放目录，确认所在磁盘空间充足。
• http 与 https：先用 HTTP 测试可以只保留 http 段；正式环境建议配置 HTTPS 证书。

如果暂时不配 HTTPS，把 https 相关行注释掉，只留：

http:
  port: 80

保存后执行安装脚本：

./install.sh

脚本会拉取镜像并启动一组容器。
看到 Harbor has been installed and started successfully 之类的提示后，用浏览器访问 http://服务器IP，用 admin 和刚才设置的密码登录。

客户端推送镜像前的信任配置

在推送镜像的机器上，如果 Harbor 用的是 HTTP 或自签名证书，Docker 默认会拒绝，需要把地址加入信任列表。
编辑或新建：

vi /etc/docker/daemon.json

写入：

{
  "insecure-registries": ["192.168.1.10"]
}

然后重启 Docker：

systemctl restart docker

登录仓库：

docker login 192.168.1.10

输入用户名 admin 和密码。
登录成功后，给本地镜像打标签并推送：

docker tag nginx:latest 192.168.1.10/library/nginx:latest
docker push 192.168.1.10/library/nginx:latest

回到 Harbor 网页，在 library 项目下能看到 nginx 仓库和对应标签，就说明推送链路已经打通。

常见报错与避坑说明

容器起不来或端口被占用：先看 docker compose ps 和 docker compose logs，常见原因是 80 或 443 已被 Nginx、Apache 占用。
改 harbor.yml 里的端口，重新执行 ./install.sh 即可。

登录报 http: server gave HTTP response to HTTPS client：说明客户端没把 Harbor 地址加入 insecure-registries，或改完没重启 Docker。
按上一节配置后重启再试。

推送报 denied: requested access to the resource is denied：多数是项目不存在或权限不足。
先在 Harbor 网页创建对应项目，或确认当前用户对该项目有推送权限。

证书相关错误：使用自签名证书时，需要把 CA 证书放到客户端的 /etc/docker/certs.d/仓库地址/ 目录下，文件名通常为 ca.crt，放好后重启 Docker。

数据备份：Harbor 的数据默认在 data_volume 指定的目录，迁移或升级前先停止服务并备份该目录，避免镜像和数据库丢失。

验证与后续维护

搭建完成后，建议做一次完整验证：登录、推送、拉取、删除各走一遍。
拉取测试：

docker rmi 192.168.1.10/library/nginx:latest
docker pull 192.168.1.10/library/nginx:latest

能正常拉回，说明仓库读写都正常。
日常维护主要是定期清理无用镜像、关注磁盘占用、升级前备份数据目录。
如果只是个人或小团队内部使用，用 HTTP 加信任配置能快速跑通；
对公网开放或多人协作时，建议尽早配置正式证书和访问控制。
遇到异常时，优先查看 Harbor 各容器的日志，再对照本文的报错章节定位。