Harbor 是 VMware 开源的企业级容器镜像仓库，基于 Docker Registry 二次开发，在其之上补齐了 Web 管理界面、基于角色的权限控制、项目隔离、镜像扫描、镜像签名和跨仓库复制等能力。对于内网环境或者对镜像安全有要求的团队来说，自建一套 Harbor 是非常常见的方案。下面从零开始演示在一台 CentOS 或 Ubuntu 服务器上部署 Harbor 的完整流程，并解释每一步背后的原理。
环境准备与前置条件
Harbor 对硬件要求不算高，2 核 CPU、4GB 内存、40GB 磁盘就能跑起来，但磁盘要留够增长空间，因为镜像会随着业务迭代不断累积。软件层面需要先装好 Docker 引擎和 Docker Compose。Harbor 官方推荐的 Docker 版本是 20.10 以上，Compose 则支持 v2 插件形式。安装完之后用下面命令确认版本：
docker --version docker compose version
如果系统里还残留着老版本的 docker-compose（Python 实现），建议直接卸载，避免和 v2 插件冲突。Harbor 的安装脚本会调用 compose 来编排十几个容器，包括核心服务 core、jobservice、registry、数据库 postgres、Redis 缓存、trivy 扫描器等。这些容器全部跑在同一台宿主机上，通过一个内部网络互通，宿主机只需要暴露 80 和 443 端口即可。
另外要注意关闭或者正确配置防火墙。很多部署失败的案例并不是 Harbor 本身的问题，而是防火墙拦截了 443 端口，导致客户端推送镜像时一直报 connection refused。SELinux 在 CentOS 上也可能干扰容器对数据目录的读写，简单粗暴的做法是设为 permissive 模式，生产环境则应该针对性配置策略。
下载安装包与配置 harbor.yml
Harbor 提供在线和离线两种安装包，离线包体积大但包含了全部镜像文件，适合内网服务器。到 Harbor 的官方 GitHub 发布页下载对应版本的离线包，例如 harbor-offline-installer-v2.9.0.tgz，然后解压：
tar -zxvf harbor-offline-installer-v2.9.0.tgz cd harbor cp harbor.yml.tmpl harbor.yml vim harbor.yml
配置文件里有几个关键项必须修改。hostname 填服务器的域名或 IP，客户端推送镜像时会用到这个名字；http.port 默认 80；harbor_admin_password 是 admin 账号的初始密码，首次登录前务必改掉；数据库和 Redis 的密码如果只是单机使用可以保持默认，但要确保这些容器端口没有对外暴露。
HTTPS 部分是新手最容易踩坑的地方。如果暂时没有正式证书，可以先把 https 整段注释掉，让 Harbor 以 HTTP 方式启动。但要注意 Docker 客户端默认拒绝向非 HTTPS 仓库推送镜像，需要在客户端的 /etc/docker/daemon.json 中添加 insecure-registries 配置并重启 Docker 服务。生产环境强烈建议启用 HTTPS，可以用 Let's Encrypt 免费证书，或者公司内部 CA 签发的证书。配置好证书路径之后，安装命令可以选择带 trivy 参数，同时装上漏洞扫描组件：
sudo ./install.sh --with-trivy
脚本执行过程中会先加载本地镜像，再生成各服务的配置，最后调用 docker compose up 启动全部容器。看到 ---- Harbor has been installed and started successfully. ---- 字样就说明部署完成了。
验证使用与常见问题排查
部署完成后用浏览器访问服务器地址，输入 admin 和刚才设置的密码即可进入管理界面。第一步建议创建一个项目，比如 myapp，访问级别选私有。然后在客户端机器上登录并推送镜像验证：
docker login 192.168.10.20 docker tag nginx:latest 192.168.10.20/myapp/nginx:v1 docker push 192.168.10.20/myapp/nginx:v1 docker pull 192.168.10.20/myapp/nginx:v1
推送成功后，Web 界面的项目仓库列表里就能看到这个镜像，点进去还可以查看镜像详情、扫描结果和拉取命令。日常运维中常用的命令是先切换到 Harbor 安装目录，用 docker compose stop 停止服务，用 ./prepare 重新生成配置后再 docker compose up -d。修改 harbor.yml 之后一定要执行 prepare，否则新配置不会生效，这是很多人改了密码不生效的原因。
排查报错时有几个高频问题。第一是登录报 unauthorized，多半是密码输错，或者账号没有被加入对应项目的成员，去界面的项目管理里添加成员并分配角色即可。第二是推送报 denied，通常是因为项目不存在或者项目访问级别是私有而用户没有推送权限。第三是 HTTPS 证书不信任，客户端报 x509: certificate signed by unknown authority，解决办法是把 CA 证书复制到客户端的 /etc/docker/certs.d/服务器地址/ca.crt 目录下。第四是磁盘占满导致推送失败，Harbor 的镜像数据默认存放在 /data/harbor 目录，可以在 harbor.yml 的 data_volume 中调整，同时建议定期在界面上配置镜像保留策略，自动清理旧 tag。
整体来看，Harbor 的部署难度并不大，重点在于理解配置文件各项含义以及 Docker 客户端与仓库之间的认证机制。把 HTTPS、权限和存储规划这三件事提前想清楚，后面接入 CI/CD 流水线时就会顺畅很多。
Harbor部署Docker私有仓库镜像仓库修改时间：2026-09-05 11:50:31