Docker镜像仓库Harbor搭建：从零部署到HTTPS访问的完整步骤

如果你需要在内网或自有服务器上存放Docker镜像，Harbor是目前比较常用的私有镜像仓库方案。
它比Docker自带的registry多了用户权限、项目管理、镜像扫描和图形界面。
下面按零基础也能照着做的顺序，讲清楚Harbor搭建的完整过程。

开始之前需要确认的环境条件

Harbor官方推荐在Linux服务器上运行，本文以常见的64位Linux发行版为例。
开始前请确认以下条件：

• 已安装Docker Engine，执行 docker version 能看到Client和Server信息。
• 已安装Docker Compose插件，执行 docker compose version 能正常输出版本号。
• 服务器至少2核CPU、4GB内存、40GB磁盘空间，否则Harbor部分容器可能启动失败。
• 服务器有固定IP或可解析的域名，因为HTTPS证书和客户端配置都需要用到。
• 防火墙或安全组放行80和443端口，如果只做HTTP测试可临时放行80。

如果Docker还没装好，先完成Docker安装再继续，否则Harbor的安装脚本会直接报错退出。

下载并解压Harbor离线安装包

Harbor提供在线和离线两种安装包。
在线包体积小，但安装时需要访问外网拉取镜像；
离线包体积大，适合内网或网络不稳定的环境。

从Harbor官方GitHub Releases页面下载对应版本的离线安装包，文件名通常类似 harbor-offline-installer-vX.Y.Z.tgz。
由于版本会持续更新，请以官方发布页实际显示的最新稳定版为准，不要照搬本文外的旧版本号。

下载完成后执行：

tar -zxvf harbor-offline-installer-vX.Y.Z.tgz
cd harbor
ls

解压后应能看到 harbor.yml.tmpl、install.sh、prepare 等文件。

修改harbor.yml的关键配置

复制模板文件再修改，避免改坏原始配置：

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

需要重点确认的配置项：

• hostname：填写服务器的域名或IP。如果要用HTTPS，建议填域名，且该域名能解析到本机。
• http.port：HTTP端口，默认80。
• https：如果要启用HTTPS，取消https段的注释，填写 port: 443、certificate 和 private_key 的证书路径。
• harbor_admin_password：Harbor管理后台的admin初始密码，安装后可在后台修改。
• data_volume：Harbor数据存储目录，默认 /data，确保该目录所在磁盘空间充足。
• database.password：内部数据库密码，保持默认或改成自己的强密码。

如果暂时没有证书，可以先只配置HTTP做功能验证，但生产环境建议启用HTTPS，否则Docker客户端推送镜像时需要额外配置不安全仓库。

生成配置并启动Harbor

配置修改完成后，执行安装脚本：

./install.sh

脚本会自动调用 prepare 生成docker-compose文件，然后拉取并启动Harbor相关容器。
看到类似 ✔ ----Harbor has been installed and started successfully.---- 的提示，说明安装完成。

检查容器状态：

docker compose ps

正常情况下能看到 harbor-core、harbor-db、harbor-portal、nginx、registry 等容器处于running状态。

验证访问与镜像推送拉取

浏览器打开 https://你的域名 或 http://你的IP，应能看到Harbor登录页。
默认用户名是 admin，密码是 harbor.yml 中配置的 harbor_admin_password。

登录后先创建一个项目，例如 test。
然后在另一台已安装Docker的机器上测试推送：

docker login 你的域名
docker tag nginx:latest 你的域名/test/nginx:latest
docker push 你的域名/test/nginx:latest

推送成功后在Harbor后台的test项目下应能看到nginx镜像。
再拉取验证：

docker pull 你的域名/test/nginx:latest

如果使用HTTP而非HTTPS，需要在客户端Docker的daemon配置中把该地址加入 insecure-registries，并重启Docker服务。

常见报错与避坑说明

容器启动后无法访问页面：先检查 docker compose ps 中nginx和harbor-core是否正常运行，再检查服务器防火墙和安全组是否放行对应端口。

推送镜像时报证书错误：如果使用自签名证书，需要把CA证书放到客户端 /etc/docker/certs.d/你的域名/ 目录下，并重启Docker。

提示dial tcp连接超时：确认客户端能解析Harbor的hostname，且网络可达。
内网环境要检查DNS或hosts配置。

磁盘写满导致服务异常：Harbor的镜像、数据库和日志都会写入 data_volume 指定目录，建议单独挂载数据盘并定期清理无用镜像。

升级或迁移Harbor：不要直接覆盖旧目录。
应先备份 harbor.yml 和数据库，再下载新版本安装包，按官方升级说明操作。

几个容易被问到的问题

Harbor和Docker registry有什么区别？
registry只提供最基础的镜像存储和分发，Harbor在registry之上增加了用户管理、项目管理、RBAC权限、镜像复制和漏洞扫描等企业常用功能。

必须用HTTPS吗？
功能上HTTP也能用，但Docker客户端默认要求HTTPS，用HTTP需要配置不安全仓库，生产环境建议启用HTTPS。

Harbor能装在宝塔面板的服务器上吗？
可以，只要服务器满足Docker和Docker Compose条件即可。
但要注意Harbor自带的nginx会占用80和443端口，如果宝塔的nginx已经占用，需要修改Harbor的端口或先停掉冲突服务。

Harbor搭建完成后，建议先在一个测试项目中完整走一遍登录、推送、拉取流程，确认权限和网络都正常，再接入实际业务。
后续如果要调整配置，修改 harbor.yml 后重新执行 ./install.sh 即可，但升级前务必做好数据备份。