Linux服务器如何部署可用的Harbor镜像仓库?首次推送镜像前要配置什么
Harbor 的最小可用部署,核心不是把所有功能一次打开,而是先让 Linux 服务器上的 Docker、Harbor 服务、持久化目录和访问入口形成闭环。本文以 Ubuntu 22.04/24.04、单台 Linux 服务器、Docker Engine、Docker Compose Plugin 和 Harbor 离线安装包为例,部署一个使用本地存储的 Harbor 实例。
首次推送镜像前至少要配置好四项:Harbor 的可解析主机名、HTTPS 证书及客户端信任、Harbor 项目、Docker 登录凭据。推送地址必须包含项目名称,例如 harbor.example.com/demo/nginx:1.25;仅配置服务器而没有项目或证书信任,通常无法完成第一次推送。
一、准备部署环境
1. 确认适用环境
本文采用以下示例参数:
| 项目 | 示例值 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04/24.04 x86_64 | 其他发行版需调整 Docker 安装命令 |
| Harbor 版本 | 2.10.2 示例 | 生产环境应固定经过验证的版本,不要直接使用 latest |
| Harbor 主机名 | harbor.example.com | 不要写 http:// 或 https:// |
| Harbor 内网地址 | 192.168.10.20 | 仅为示例地址 |
| 访问端口 | TCP 443 | HTTPS 部署 |
| 数据目录 | /data | 保存镜像、数据库和 Harbor 数据 |
| 示例项目 | demo | 首次推送使用 |
| 示例镜像 | nginx:1.25 | 也可以替换为已有本地镜像 |
小规模测试或内部团队使用时,可以先准备 4 vCPU、8 GB 内存和 SSD 存储。镜像仓库的空间需求取决于镜像层数量、镜像大小和保留策略,示例环境建议为 /data 预留至少 100 GB;这属于部署估算,不是所有场景的固定要求。
Harbor 会在同一台服务器上启动代理、核心服务、Registry、数据库、Redis、任务服务和日志服务。最小部署不需要单独准备 MySQL、Redis 或外部对象存储,但必须保证 Docker Compose 能正常运行,并为镜像数据准备持久化磁盘。

对于需要长期运行 Harbor 的镜像仓库、容器服务和业务后台,A5数据提供中国香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器资源,覆盖常规 Xeon、AMD EPYC、大内存与 NVMe 存储配置,可为 Registry 镜像数据、数据库及多任务容器运行提供硬件基础。同时,不同地区配有相应的国际或优化线路,便于结合团队分布、访问来源和数据规模构建匹配的 Harbor 部署环境。
2. 检查主机名、磁盘和端口
先在 Harbor 服务器上检查系统版本、磁盘、内存和端口占用:
cat /etc/os-release
uname -m
free -h
df -h /
df -h /data 2>/dev/null || true
sudo ss -lntp | grep -E ':(80|443)\b' || true
预期结果:
- 系统为 Ubuntu 22.04 或 Ubuntu 24.04;
- 架构通常为
x86_64; /data所在文件系统有足够可用空间;- 80、443 端口没有被 Nginx、Apache 或其他服务占用。
如果 /data 不存在,可以创建目录。这个操作不会删除已有数据,但不要对已有生产目录执行清空或覆盖操作:
sudo install -d -m 0750 /data
df -h /data
在 DNS 尚未配置时,可以临时在客户端的 /etc/hosts 中增加解析记录。确认没有重复记录后再执行:
192.168.10.20 harbor.example.com
在客户端验证:
getent hosts harbor.example.com
预期能返回 192.168.10.20。如果解析失败,先处理 DNS 或 hosts 配置,不要急于排查 Harbor 容器。
3. 放行访问端口
如果服务器启用了 UFW,只放行实际使用的端口。修改防火墙策略前,应确认当前 SSH 来源和云平台安全组规则,避免误封管理连接。
sudo ufw status verbose
sudo ufw allow 443/tcp
sudo ufw status numbered
如果还需要通过 HTTP 提供访问,才增加 80 端口:
sudo ufw allow 80/tcp
上述命令会改变服务器入站策略。回滚时可以删除对应规则:
sudo ufw delete allow 443/tcp
sudo ufw delete allow 80/tcp
云服务器还需要在云平台安全组中放行相同端口。只修改 UFW 而忽略安全组,客户端仍可能无法连接。
二、安装 Docker Engine 和 Compose
1. 配置 Docker 软件源
如果服务器已经安装 Docker,可以直接检查版本;如果没有安装,Ubuntu 可按以下方式安装 Docker Engine 和 Compose Plugin:
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
| sudo gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
. /etc/os-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu ${VERSION_CODENAME} stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
启动 Docker 并设置为开机启动:
sudo systemctl enable --now docker
sudo systemctl is-active docker
预期返回:
active
检查 Docker 和 Compose:
sudo docker version --format '{{.Server.Version}}'
sudo docker compose version
sudo docker run --rm hello-world
预期能看到 Docker 服务端版本、Compose v2 版本以及 Hello from Docker!。Harbor 不使用旧的 docker-compose 命令作为前提,本文统一使用 docker compose。
具体 Harbor 版本对 Docker Engine 和 Compose 的支持范围可能不同。固定版本后,应检查该版本随附的安装说明或兼容性要求;如果服务器上的 Docker 版本过旧,不要通过忽略检查强行安装。
三、准备 Harbor 安装包和证书
1. 下载固定版本的离线安装包
离线安装包包含 Harbor 所需的镜像,适合首次部署时减少外部依赖。下面使用 2.10.2 作为示例固定版本,实际部署时可替换为已经验证的版本:
export HARBOR_VERSION=2.10.2
cd /tmp
curl -fLO "https://github.com/goharbor/harbor/releases/download/v${HARBOR_VERSION}/harbor-offline-installer-v${HARBOR_VERSION}.tgz"
sha256sum "harbor-offline-installer-v${HARBOR_VERSION}.tgz"
sha256sum 输出应与该版本发布页面提供的校验值进行比对。不要使用来源不明的安装包,也不要把未验证的版本直接用于生产环境。
确认 /opt/harbor 不存在或已经完成备份后再解压:
cd /tmp
tar -xzf "harbor-offline-installer-v${HARBOR_VERSION}.tgz"
sudo mv harbor /opt/harbor
sudo ls -la /opt/harbor
如果 /opt/harbor 已经存在,先停止当前 Harbor 并备份配置,不要直接覆盖目录。
2. 为 HTTPS 准备证书
生产环境建议使用企业 CA 或受信任 CA 签发的证书。证书的域名必须包含 harbor.example.com,客户端还必须信任签发该证书的 CA。
如果只是内网验证,可以使用自签名证书。下面的命令生成一个带 SAN 的示例证书:
sudo install -d -m 0750 /opt/harbor/certs
sudo openssl req -x509 -nodes -newkey rsa:4096 \
-days 825 \
-keyout /opt/harbor/certs/harbor.key \
-out /opt/harbor/certs/harbor.crt \
-subj "/C=CN/ST=Beijing/L=Beijing/O=Example/OU=IT/CN=harbor.example.com" \
-addext "subjectAltName=DNS:harbor.example.com,IP:192.168.10.20"
sudo chmod 600 /opt/harbor/certs/harbor.key
sudo chmod 644 /opt/harbor/certs/harbor.crt
检查证书中的主题和 SAN:
sudo openssl x509 \
-in /opt/harbor/certs/harbor.crt \
-noout -subject -issuer -dates -ext subjectAltName
预期至少能看到:
DNS:harbor.example.com
IP Address:192.168.10.20
如果客户端通过主机名访问,证书必须包含主机名;如果客户端通过 IP 访问,证书还应包含对应 IP。仅把主机名写入 CN、而没有写入 SAN,现代客户端通常仍会提示证书名称不匹配。
3. 让 Docker 客户端信任证书
对于企业 CA 签发的证书,应复制 CA 根证书或完整信任链中的 CA 证书。对于上面的自签名测试证书,可以把 harbor.crt 作为客户端信任证书使用。
在 Harbor 服务器上执行:
sudo install -d -m 0755 /etc/docker/certs.d/harbor.example.com
sudo cp /opt/harbor/certs/harbor.crt \
/etc/docker/certs.d/harbor.example.com/ca.crt
sudo systemctl restart docker
systemctl restart docker 会影响该主机上的 Docker 容器,执行前应确认没有其他重要容器正在运行。远程 Docker 客户端也要执行同样的信任配置;如果 Harbor 使用非标准端口,目录名必须包含端口,例如:
/etc/docker/certs.d/harbor.example.com:8443/ca.crt
四、配置并启动 Harbor
1. 复制配置模板
进入 Harbor 目录,复制配置模板:
cd /opt/harbor
sudo cp harbor.yml.tmpl harbor.yml
sudo chmod 600 harbor.yml
使用编辑器修改配置:
sudoedit /opt/harbor/harbor.yml
至少确认以下内容。不要把 https:// 写入 hostname:
hostname: harbor.example.com
https:
port: 443
certificate: /opt/harbor/certs/harbor.crt
private_key: /opt/harbor/certs/harbor.key
harbor_admin_password: "请替换为强密码"
database:
password: "请替换为数据库密码"
data_volume: /data
这里的密码只是配置示意,部署时应替换为独立的强密码,并避免在命令行参数中直接暴露。harbor.yml 中可能还有其他模板字段,首次部署可以保留默认值;不要因为追求“完整配置”而一次打开外部数据库、对象存储、扫描器或额外服务。
对配置做基本检查:
cd /opt/harbor
sudo grep -nE '^(hostname:|harbor_admin_password:|data_volume:|https:| port:| certificate:| private_key:)' harbor.yml
sudo test -r /opt/harbor/certs/harbor.crt
sudo test -r /opt/harbor/certs/harbor.key
sudo test -d /data
如果证书路径、私钥路径或数据目录检查失败,应先修正配置。
2. 执行安装
首次部署使用安装脚本:
cd /opt/harbor
sudo ./install.sh
最小可用部署先不加 --with-trivy,这样可以减少首次启动的组件和资源占用。后续如需漏洞扫描,应按照对应 Harbor 版本的方式单独启用并评估磁盘、CPU 和更新依赖。
安装成功后,检查服务状态:
cd /opt/harbor
sudo docker compose ps
预期各主要服务处于 Up 或健康状态。不同 Harbor 版本显示的容器名称和健康检查字段可能略有差异,重点检查 proxy、core、registry、portal、postgresql、redis 和 jobservice 是否持续运行。
查看监听端口:
sudo ss -lntp | grep -E ':(443)\b'
如果 443 没有监听,先检查容器状态和日志:
cd /opt/harbor
sudo docker compose logs --tail=100 proxy core registry
五、首次启动验证
1. 验证 HTTPS 和 Registry API
使用自签名证书时,测试请求需要指定证书:
curl --cacert /opt/harbor/certs/harbor.crt \
-I https://harbor.example.com/
企业 CA 证书被系统信任后,可以直接执行:
curl -I https://harbor.example.com/
门户页面通常返回 200 或重定向响应。再检查 Registry API:
curl --cacert /opt/harbor/certs/harbor.crt \
-sS -o /dev/null -w '%{http_code}\n' \
https://harbor.example.com/v2/
未登录访问 /v2/ 返回 401 是正常现象,说明 HTTPS、代理和 Registry 已经连通;如果返回 404、502 或连接超时,再继续检查服务和端口。
2. 创建首个项目
浏览器访问:
https://harbor.example.com
使用配置文件中的 admin 和管理员密码登录,进入 Projects,创建项目:
项目名称:demo
可见性:Private
项目创建后,在项目列表中确认 demo 存在。Harbor 的镜像地址通常采用以下格式:
harbor.example.com/<项目名称>/<镜像名称>:<标签>
因此,demo 项目中的 Nginx 镜像地址为:
harbor.example.com/demo/nginx:1.25
项目名称缺失时,例如直接推送到 harbor.example.com/nginx:1.25,通常会因路径或权限不正确而失败。
3. 登录并推送镜像
先确认本地有待推送镜像:
sudo docker image ls
如果没有示例镜像,可以拉取一个公开镜像作为验证对象:
sudo docker pull nginx:1.25
给镜像增加 Harbor 地址和项目路径:
sudo docker tag nginx:1.25 harbor.example.com/demo/nginx:1.25
sudo docker image ls harbor.example.com/demo/nginx
登录 Harbor:
sudo docker login harbor.example.com
输入 admin 和对应密码。预期显示:
Login Succeeded
执行首次推送:
sudo docker push harbor.example.com/demo/nginx:1.25
成功时会显示各镜像层上传进度,并在结尾出现摘要或完成信息。之后可以从 Harbor 页面进入 demo 项目查看该制品。
为了验证仓库不只是“能写入”,还要执行一次拉取验证:
sudo docker pull harbor.example.com/demo/nginx:1.25
sudo docker image inspect harbor.example.com/demo/nginx:1.25 \
--format '{{.RepoTags}}'
如果条件允许,最好从另一台已配置 DNS 和 CA 信任的 Docker 客户端执行相同的 docker login 和 docker pull。这样可以排除仅本机 hosts、缓存或本机证书配置造成的假成功。
六、首次推送前的配置核对
首次推送前,可以按以下对应关系检查:
| 检查项 | 必须满足的条件 | 验证方式 |
|---|---|---|
| 主机名 | 客户端能解析 harbor.example.com | getent hosts harbor.example.com |
| 网络端口 | 客户端能访问 TCP 443 | curl -I https://harbor.example.com/ |
| 证书 | SAN 包含访问用的主机名,客户端信任 CA | curl --cacert ... |
| Harbor 服务 | proxy、core、registry 正常运行 | docker compose ps |
| 项目 | demo 项目已经创建 | Harbor 页面检查 |
| 登录 | Docker 凭据有效 | docker login harbor.example.com |
| 镜像标签 | 包含仓库域名和项目路径 | docker image ls |
| 存储 | /data 有可用空间 | df -h /data |
其中,证书信任和 Docker 登录是两个不同问题。证书不受信任时,通常出现 x509: certificate signed by unknown authority;登录失败时,通常出现 unauthorized 或 denied。应根据错误位置分别处理。
七、常见失败处理
1. 出现 x509 证书错误
先确认访问地址与证书 SAN 一致:
openssl s_client -connect harbor.example.com:443 \
-servername harbor.example.com </dev/null 2>/dev/null \
| openssl x509 -noout -subject -issuer -ext subjectAltName
处理顺序如下:
- 确认 Docker 客户端的
/etc/docker/certs.d/harbor.example.com/ca.crt存在; - 确认放入的是正确的 CA 证书,而不是另一套证书;
- 执行
sudo systemctl restart docker; - 再执行
docker login。
不要把 docker login 改成忽略证书校验。对于生产环境,应修正证书链或客户端信任配置。
2. 出现 HTTP/HTTPS 协议不匹配
如果日志类似:
server gave HTTP response to HTTPS client
说明 Harbor 实际使用 HTTP,而 Docker 客户端按 HTTPS 访问,或者反过来。检查 harbor.yml 的 http、https 配置以及访问端口:
cd /opt/harbor
grep -nE '^(hostname:|http:|https:)|certificate:|private_key:' harbor.yml
sudo docker compose ps
推荐重新配置 HTTPS,而不是把生产环境改成不安全 Registry。
仅限隔离测试环境使用 HTTP 时,需要同时完成两件事:
- Harbor 配置为 HTTP;
- 每个 Docker 客户端在
/etc/docker/daemon.json的insecure-registries中加入 Harbor 地址。
示例配置如下,必须与现有 JSON 合并,不能直接覆盖已有 Docker 配置:
{
"insecure-registries": [
"harbor.example.com"
]
}
修改 Docker daemon 配置会影响该主机上的 Docker 服务,执行前应备份原文件并确认容器影响范围:
sudo cp -a /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo systemctl restart docker
HTTP 模式不适合承载需要保护的镜像凭据和生产镜像。恢复时删除 insecure-registries 中的条目,恢复备份文件并再次重启 Docker。
3. 页面打不开或返回 502/503
先从外到内排查:
getent hosts harbor.example.com
curl -vk https://harbor.example.com/
sudo ss -lntp | grep -E ':(443)\b'
cd /opt/harbor
sudo docker compose ps
sudo docker compose logs --tail=100 proxy core registry
不同结果通常代表不同问题:
- 域名无法解析:处理 DNS 或 hosts;
- TCP 连接超时:检查云安全组、防火墙和路由;
- 443 无监听:检查 Harbor 容器或端口冲突;
proxy正常但core、registry重启:查看对应容器日志;- 页面正常但
/v2/返回 5xx:重点检查registry、core和/data磁盘。
如果端口被 Nginx 或 Apache 占用,不要直接停止进程。先确认其业务用途,再选择释放端口、调整 Harbor 端口或将现有反向代理正确转发到 Harbor。
4. 登录成功但推送被拒绝
确认镜像标签和项目路径:
sudo docker image ls harbor.example.com/demo/nginx
正确格式应类似:
harbor.example.com/demo/nginx 1.25
如果镜像名称中没有 demo,重新打标签:
sudo docker tag nginx:1.25 harbor.example.com/demo/nginx:1.25
sudo docker push harbor.example.com/demo/nginx:1.25
还需要确认:
demo项目已经存在;- 登录账号拥有推送权限;
- 使用的是同一个 Harbor 地址;
- Docker 客户端没有登录到其他域名或端口;
- Harbor 磁盘空间没有耗尽。
5. 容器反复重启或启动超时
检查资源和日志:
free -h
df -h /data
df -ih /data
cd /opt/harbor
sudo docker compose ps --all
sudo docker compose logs --tail=200 postgresql redis registry core
常见原因包括数据盘空间不足、数据库密码配置不一致、证书路径不可读、主机内存不足以及 80/443 端口冲突。不要直接删除 /data 重新安装,因为该目录保存 Harbor 的镜像和元数据。
八、配置变更与回滚
1. 首次部署前保留配置备份
在修改 Harbor 配置前保存一份副本:
cd /opt/harbor
sudo cp -a harbor.yml "harbor.yml.bak.$(date +%F-%H%M%S)"
证书私钥、管理员密码和数据库密码都属于敏感信息,备份文件应限制读取权限:
sudo chmod 600 /opt/harbor/harbor.yml*
sudo chmod 600 /opt/harbor/certs/harbor.key
2. 仅回滚配置,不删除镜像数据
如果只是证书路径、端口或主机名配置错误,可以恢复备份并重新生成配置:
cd /opt/harbor
sudo cp -a harbor.yml.bak.备份时间 harbor.yml
sudo ./prepare
重新生成配置会影响 Harbor 服务,先停止并再次启动容器:
sudo docker compose down
sudo docker compose up -d
sudo docker compose ps
docker compose down 会造成 Harbor 短暂不可用,默认不会删除 /data 中的镜像数据。不要使用带有删除卷或删除数据目录的命令作为常规回滚手段。
3. 取消本次失败部署
如果是全新部署且尚未推送任何镜像,可以停止 Harbor 容器并保留现场:
cd /opt/harbor
sudo docker compose down --remove-orphans
sudo mv /opt/harbor "/opt/harbor.failed.$(date +%F-%H%M%S)"
--remove-orphans 会清理当前 Compose 项目中不再声明的容器,但不会自动删除 /data。确认不再需要其中的数据后,才可以在经过备份和审批的前提下处理数据目录;生产环境不要直接执行递归删除。
4. 最终验收项
部署完成后逐项确认:
harbor.example.com在所有需要推送的客户端上可解析;- HTTPS 证书的 SAN 与访问地址一致;
- Docker 客户端已信任 CA;
sudo docker compose ps中主要 Harbor 服务持续运行;/v2/未登录返回401,而不是连接失败或 5xx;- Harbor 中已创建目标项目;
docker login harbor.example.com返回Login Succeeded;- 镜像能够以
仓库域名/项目/镜像:标签格式推送; - 另一台客户端能够登录并拉取该镜像;
/data有足够空间,且没有把 Harbor 数据目录误当作临时目录;- 已保存
harbor.yml、证书、Docker 配置和防火墙变更记录。
完成这些检查后,Harbor 才具备“可访问、可登录、可推送、可拉取、数据可保留”的最小可用条件。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6064.html



