香港服务器部署Harbor镜像仓库,如何配置存储、证书与访问权限?

发布人:A5数据发布时间:2026-10-15 11:24阅读量:186

目标是让香港服务器上的 Harbor 通过 https://harbor.example.com 提供镜像推送与拉取服务:镜像层、数据库和运行状态落在独立持久化存储上,客户端能够验证 HTTPS 证书,项目默认私有,人员与流水线按最小权限访问。部署完成后,还应具备可验证的备份、证书续期流程,以及配置变更失败后的恢复路径。

本文采用 Ubuntu Server 22.04 LTS、Docker Engine、Docker Compose V2 和 Harbor 离线安装包,部署单节点仓库。TLS 在 Harbor 自带的 Nginx 上终止,不额外增加反向代理;存储使用挂载到 /srv/harbor 的独立数据盘。这个方案适合内部研发和规模有限的 CI/CD 场景,但单节点不提供高可用,服务器或数据盘故障期间仓库会中断服务。

部署方案概述配图

一、准备条件:固定域名、版本与访问边界

1. 确认服务器与上线目标

以下参数是便于执行的示例,不是 Harbor 的统一容量要求。

项目本文示例上线前需要确认
操作系统Ubuntu Server 22.04 LTS,x86_64系统仍在维护期,时间同步正常
计算资源4 vCPU、8 GiB 内存扫描任务、并发推送较多时增加资源
系统盘60 GiB安装包、Docker 镜像、日志不能挤满系统盘
数据盘300 GiB,挂载到 /srv/harbor文件系统正常,支持备份或快照
域名harbor.example.comDNS 指向服务器实际服务地址
证书域名证书、完整证书链和私钥域名匹配,客户端信任签发机构
网络入口TCP 443允许开发出口、CI 出口等必要来源访问
管理入口SSH仅允许运维来源,保留控制台恢复通道

香港服务器的地域不会改变 Harbor 的安装方法,但会影响开发机、构建节点与仓库之间的传输体验。上线前应从实际使用网络测试 DNS、HTTPS 建连和镜像上传,而不是只在服务器本机验证。

以十进制单位估算,上传一个新增层合计为 2 GB 的镜像,在有效吞吐为 100 Mbps 时,纯传输时间约为:

2 GB × 8 × 1000 ÷ 100 Mbps = 160 秒

这不包含鉴权、层校验、磁盘写入和重试时间。若部分镜像层已经存在,实际上传量会更小。

面向香港 Harbor 私有镜像仓库与 CI/CD 场景,A5数据提供 Xeon Gold、AMD EPYC 等物理服务器,配合大内存及 SSD、NVMe 存储,为仓库组件运行、镜像层读写和制品保存提供资源基础。香港产品中的 CN2 与国际带宽方案,可承接不同地区研发团队和流水线的镜像传输需求;另有大容量存储服务器,可用于搭建仓库备份与历史制品归档环境。

2. 先限制入口,再启动服务

建议在服务器所属平台的安全组或上游防火墙中设置:

  • TCP 443:仅允许实际开发出口、CI 出口和必要业务网络。
  • SSH:仅允许运维管理来源。
  • TCP 80:本文不对外开放;若证书签发或续期依赖 HTTP 验证,需要单独安排。
  • Harbor 内部数据库、Redis、Registry 等端口:不对外开放。

Docker 发布端口可能不受普通 UFW 入站规则按预期限制,不能仅凭 ufw status 判断仓库已经隔离。 本文以安全组或上游防火墙作为入口控制,并在后续从允许和禁止的网络分别验证。

修改安全组会影响远程管理和业务连接。操作前导出现有规则,保留当前 SSH 会话及控制台入口;若误封管理连接,应通过控制台恢复,而不是继续叠加未知规则。

3. 固定软件版本

安装包、配置模板和后续恢复使用的版本必须一致。下文以 Harbor 2.12.2 展示离线安装流程,不将其视为部署时的最新或推荐补丁版本。正式上线应核对维护状态、安全公告和依赖要求,选定仍受支持的补丁版本,并使用该版本随包提供的模板。

服务器端命令在 root shell 中执行:

sudo -i

uname -m
cat /etc/os-release
timedatectl status
df -hT
ss -lntp

确认架构为 x86_64、时间正确,且 80、443 没有被其他服务占用。不要为了安装 Harbor 直接停止已有业务,先确认端口使用者及变更窗口。

二、分步部署:先落实存储,再配置证书和服务

1. 将数据盘挂载到固定路径

本文只使用已经初始化文件系统的专用数据盘,不包含格式化操作。先识别设备、UUID 和挂载状态:

lsblk -f
findmnt /srv/harbor

若 /srv/harbor 已有业务数据,不应直接挂载新磁盘覆盖该目录;挂载后原目录内容会被遮蔽,但并没有迁移到新盘。

首次部署且目录为空时:

install -d -m 0755 /srv/harbor
cp -a /etc/fstab "/etc/fstab.bak.$(date +%Y%m%d-%H%M%S)"

编辑 /etc/fstab,为已有的 ext4 数据盘添加一行。UUID 必须替换为 lsblk -f 显示的实际值:

UUID=替换为实际UUID /srv/harbor ext4 defaults 0 2

然后挂载并检查:

mount /srv/harbor
findmnt /srv/harbor
df -hT /srv/harbor
install -d -m 0755 /srv/harbor/data

如果磁盘使用 XFS,应按实际文件系统设置挂载参数,不能照抄 ext4 行。若挂载失败,停止后续安装,恢复 /etc/fstab 的备份并修正 UUID、文件系统类型或设备问题。

Harbor 的 data_volume 必须放在这个挂载点内。每次启动前都要确认挂载有效,否则服务可能把数据写入系统盘上同名目录,造成“数据盘恢复挂载后镜像消失”的假象。

二、分步部署:先落实存储,再配置证书和服务配图

存储配置的关键不是目录名字,而是挂载可靠、数据完整且可以恢复。 不要对数据目录执行 chmod -R 777 或统一递归 chown;Harbor 各组件使用不同的容器身份,应由对应版本的准备过程建立所需权限。

2. 安装 Docker Engine 与 Compose V2

对于全新的 Ubuntu 22.04 主机,可使用 Docker 软件源安装。已有容器业务的服务器不要直接替换 Docker,先核对现有版本、存储驱动和变更影响。

apt-get update
apt-get install -y ca-certificates curl openssl

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu jammy stable" \
  > /etc/apt/sources.list.d/docker.list

apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker
docker version
docker compose version

核对选定 Harbor 版本要求的 Docker、Compose 版本。不要同时套用旧版 docker-compose 和新版 docker compose 操作,也不要将普通用户加入 Docker 组作为默认措施;Docker 控制权限接近主机 root 权限。

数据盘的 data_volume 不会自动迁移 Docker 自身的 /var/lib/docker。离线包导入的组件镜像仍可能占用系统盘,容量评估必须分别计算。

3. 下载并核验 Harbor 离线包

VERSION=2.12.2

install -d -m 0755 "/opt/harbor/releases/${VERSION}"
cd "/opt/harbor/releases/${VERSION}"

curl -fL --retry 3 \
  -o "harbor-offline-installer-v${VERSION}.tgz" \
  "https://github.com/goharbor/harbor/releases/download/v${VERSION}/harbor-offline-installer-v${VERSION}.tgz"

sha256sum "harbor-offline-installer-v${VERSION}.tgz"

将输出与可信发布校验信息或组织内部审核后的制品校验值比较,再解压。仅计算本地哈希并不能证明安装包可信;不要使用来源不明的二次打包文件。

tar -xzf "harbor-offline-installer-v${VERSION}.tgz"
cd harbor

cp -a harbor.yml.tmpl harbor.yml
chmod 600 harbor.yml

后续命令均在这个 harbor 目录执行。保存原始安装包、校验记录和版本号,恢复时需要使用相同制品。

4. 安装证书与私钥

准备两个文件:

  • fullchain.pem:服务器证书及中间证书链。
  • privkey.pem:与证书匹配的私钥。

私钥应允许服务无交互启动,并通过文件权限保护。下例源路径仅为示例,需替换为实际证书文件:

install -d -m 0700 /etc/harbor/tls

install -m 0644 /root/cert-input/fullchain.pem \
  /etc/harbor/tls/fullchain.pem

install -m 0600 /root/cert-input/privkey.pem \
  /etc/harbor/tls/privkey.pem

核验证书域名、有效期和密钥匹配:

openssl x509 -in /etc/harbor/tls/fullchain.pem \
  -noout -subject -issuer -dates -ext subjectAltName

openssl x509 -in /etc/harbor/tls/fullchain.pem \
  -pubkey -noout | openssl pkey -pubin -outform DER | sha256sum

openssl pkey -in /etc/harbor/tls/privkey.pem \
  -pubout -outform DER | sha256sum

后两条命令的哈希应一致,SAN 应包含 harbor.example.com。域名证书不能用于通过服务器 IP 访问仓库。

若使用企业内部 CA,所有 Docker 客户端都需要信任其根证书。默认 443 的目录示例为:

sudo install -d -m 0755 \
  /etc/docker/certs.d/harbor.example.com

sudo install -m 0644 company-root-ca.crt \
  /etc/docker/certs.d/harbor.example.com/ca.crt

这里放的是 CA 证书,不是服务器私钥。非默认端口对应目录需包含端口,如 harbor.example.com:8443。如果客户端仍未加载新信任配置,可在维护窗口重启 Docker;这可能影响本机容器,不应在生产节点上直接执行。

使用公共可信 CA 时,通常无需单独添加信任。无论哪种证书,都不应通过 insecure-registries 或关闭 TLS 校验来代替正确配置。

5. 修改 Harbor 配置并启动

编辑 harbor.yml,修改对应字段,保留模板中的其他配置,不要将下面片段当作完整文件覆盖:

hostname: harbor.example.com

http:
  port: 80

https:
  port: 443
  certificate: /etc/harbor/tls/fullchain.pem
  private_key: /etc/harbor/tls/privkey.pem

harbor_admin_password: "替换为独立生成的管理员密码"

database:
  password: "替换为独立生成的数据库密码"

data_volume: /srv/harbor/data

log:
  level: info
  local:
    rotate_count: 20
    rotate_size: 100M
    location: /var/log/harbor

管理员密码和数据库密码应不同,避免示例密码、弱口令及难以正确转义的字符。不要把包含密码的配置提交到代码仓库。

本文直接通过域名访问 Harbor,不启用 external_url。如果将来增加前置负载均衡或反向代理,需要重新核对外部地址、协议和鉴权令牌地址,不能只修改一层的端口。

再次确认数据盘存在,然后安装:

findmnt /srv/harbor
./install.sh --with-trivy

docker compose ps
docker compose logs --tail=100

这里启用了 Trivy 扫描组件,因此主机还需能够访问其漏洞数据库更新来源。离线安装包只解决组件安装问题,不意味着漏洞数据库可以持续更新;完全离线环境需另行建立数据库分发机制。

检查容器状态是否正常、健康检查是否通过。若安装报错,先查看具体日志,不要反复执行安装或删除数据目录。

三、配置访问权限:网络准入与项目授权分开处理

Harbor 访问控制至少包含两层:网络层决定谁能连接 443,项目授权决定连接后可以操作哪些镜像。只限制网络、不设置项目权限,或只设置账号、不限制管理入口,都不能替代另一层。

三、配置访问权限:网络准入与项目授权分开处理配图

1. 创建私有项目

用 admin 登录 Web 页面,在首次开放给其他人员前修改初始密码,并妥善保存到密码管理系统。

创建项目 app-prod 时保持“公开”关闭。私有项目的匿名拉取应失败;公开项目则允许匿名读取镜像,不能把“没有分配用户”理解为完全不可访问。

推荐的授权边界如下:

使用主体授权方式权限边界
仓库运维人员少量管理员账号负责系统设置、用户和项目管理
开发人员私有项目成员需要推送时使用开发者角色,并核对该版本附带的删除等权限
仅需拉取的人员项目访客角色不授予推送及管理权限
CI 构建任务项目级机器人账号仅授予目标项目所需的拉取、推送权限
部署任务独立机器人账号仅授予目标项目拉取权限

Harbor 是项目级授权为主。若同一项目内不同镜像需要明显不同的权限,应优先拆分项目,不要假定可以像文件系统一样逐目录设置访问权限。

2. 为流水线创建独立机器人账号

在 app-prod 中创建项目级机器人账号,例如 ci-build。勾选镜像推送所需权限时,按页面提示保留其依赖的拉取权限,不授予项目管理、成员管理或不需要的删除权限。

将生成的完整账号名和令牌保存到 CI 的秘密变量中。机器人令牌应设置适当有效期,并安排轮换;不要多条流水线共用管理员密码。

登录时使用标准输入,避免密码出现在命令历史和进程参数中:

printf '%s' "$HARBOR_TOKEN" | docker login harbor.example.com \
  --username "$HARBOR_ROBOT_USER" \
  --password-stdin

机器人用户名可能包含 $,手工输入时应使用单引号,或通过变量传递。令牌一旦泄露,应禁用对应账号、生成新凭据并检查相关访问记录。

CI 执行器还应使用凭据助手或临时 Docker 配置目录,防止共享工作目录残留登录信息。任务结束后执行 docker logout harbor.example.com,不能只删除构建日志。

3. 同时配置配额与清理策略

为项目设置容量配额,避免一个流水线耗尽整个数据盘。开启清理或保留策略前,应先明确哪些标签承担发布回滚用途。

删除标签并不一定立即释放磁盘空间,因为镜像层可能仍被其他制品引用;垃圾回收也不能代替容量规划。首次执行保留策略或垃圾回收前,应备份,查看预览或试运行结果,并按选定版本的行为安排维护窗口。

四、结果验证:证书、推拉与越权必须分别测试

1. 从实际客户端验证 HTTPS

curl -I https://harbor.example.com/

curl -i https://harbor.example.com/v2/

页面应返回正常的 HTTP 响应。未登录访问 /v2/ 返回 401 Unauthorized 并带有 Registry 鉴权信息,通常是正常的认证挑战,不表示服务故障。

检查服务器实际提供的证书链:

openssl s_client \
  -connect harbor.example.com:443 \
  -servername harbor.example.com \
  -verify_hostname harbor.example.com \
  -verify_return_error </dev/null

使用内部 CA 时可增加 -CAfile company-root-ca.crt。验收应确认域名校验和证书链验证通过,不使用 curl -k 掩盖问题。

如果 DNS 配置了 IPv6,也必须验证 AAAA 对应的地址;IPv4 正常并不能证明 IPv6 路径可用。

2. 使用临时镜像完成推送和拉取

在已有 Docker 的测试客户端上构建一个不依赖外部基础镜像的小型镜像:

mkdir -p harbor-smoke
cd harbor-smoke

printf 'harbor acceptance test\n' > marker.txt

cat > Dockerfile <<'EOF'
FROM scratch
COPY marker.txt /marker.txt
EOF

docker build -t harbor.example.com/app-prod/smoke:acceptance .
docker push harbor.example.com/app-prod/smoke:acceptance

记录推送后的 digest,并在另一个干净客户端使用只读机器人账号拉取:

docker pull harbor.example.com/app-prod/smoke:acceptance
docker image inspect harbor.example.com/app-prod/smoke:acceptance \
  --format '{{json .RepoDigests}}'

结果应与仓库页面或推送输出对应。独立客户端验证可以避免本地缓存掩盖拉取故障。

还需完成三项负向测试:

  • 匿名客户端无法拉取私有项目镜像。
  • 只读账号无法推送镜像。
  • app-prod 的机器人账号无法访问未授权的其他私有项目。

验收失败时不要临时提高账号权限。先区分网络、证书、身份和项目授权问题。

如果最终使用方是 Kubernetes,还要从实际节点验证运行时的证书信任,并通过 imagePullSecrets 配置仓库凭据。节点使用 containerd 时,Docker 的证书目录不会自动成为 containerd 的信任配置。

五、失败处理:按外部连接到内部存储的顺序排查

现象优先检查结果含义与处理
域名解析错误A、AAAA 记录及客户端解析结果修正错误记录;确认没有访问旧地址
连接超时安全组、来源出口地址、443 监听无法连接时先修网络,不调整 Harbor 用户权限
x509 错误SAN、有效期、完整链、客户端时间修复证书或信任链,不关闭 TLS 校验
登录失败账号完整名称、令牌有效期、认证模式登录身份有问题不等于存储故障
登录成功但推送被拒绝项目名称、私有状态、机器人权限确认镜像路径属于账号获授权的项目
上传中断或返回 5xx磁盘容量、inode、组件日志检查配额、存储和服务状态,避免盲目重试
重启后服务异常数据盘挂载、Docker、组件健康状态挂载缺失时先停止服务,再恢复正确存储

服务器端低风险检查命令:

findmnt /srv/harbor
df -h /srv/harbor /var/lib/docker /var/log/harbor
df -i /srv/harbor

docker compose ps
docker compose logs --tail=200

日志不足时,先执行 docker compose config --services 查看本版本的服务名,再查询对应组件日志,不凭印象使用其他版本的名称。

如果发现数据盘未挂载,但 Harbor 已运行,应先在部署目录停止服务:

docker compose stop

随后分别核对系统盘同名目录和真正数据盘中的内容,不要直接混合两个目录。恢复正确挂载后,确认数据一致性,再启动服务。混合复制数据库文件可能造成比短暂停机更严重的损坏。

六、备份、回滚与上线验收

1. 建立可恢复的冷备份

备份至少包括持久化数据、当前部署目录及生成配置、TLS 文件和版本信息。Harbor 的内部密钥也必须随持久化数据和配置保存;只复制镜像层不足以恢复完整仓库。

下面采用停服务后的文件级冷备份,适合单节点维护窗口。执行期间推送、拉取和登录会中断;备份目标必须位于另一块存储或备份挂载上,并有足够空间:

cd /opt/harbor/releases/2.12.2/harbor

docker compose stop

BACKUP_FILE="/mnt/harbor-backup/harbor-$(date +%Y%m%d-%H%M%S).tar"
umask 077

tar --xattrs --acls -cpf "$BACKUP_FILE" \
  -C / \
  srv/harbor/data \
  opt/harbor/releases/2.12.2/harbor \
  etc/harbor/tls

sha256sum "$BACKUP_FILE" > "${BACKUP_FILE}.sha256"

docker compose start
docker compose ps

执行前先确认 /mnt/harbor-backup 是真实备份存储,而不是系统盘上的普通空目录。若归档失败,应确认服务已重新启动,并重新安排完整备份;不完整文件不能作为回滚依据。

备份包含私钥、数据库及凭据,需限制读取权限,异机保存时进行加密。还应定期在隔离主机上恢复,验证账号、镜像和推拉功能。

2. 配置与证书变更的回滚

修改 harbor.yml 或证书前,备份当前配置和整个 TLS 目录。更新通常会造成短暂中断,应安排维护窗口:

cp -a harbor.yml "harbor.yml.bak.$(date +%Y%m%d-%H%M%S)"
cp -a /etc/harbor/tls \
  "/etc/harbor/tls.bak.$(date +%Y%m%d-%H%M%S)"

docker compose down
./prepare --with-trivy
docker compose up -d

这里的 docker compose down 不带 -v。不要为了“重新安装”删除持久化目录。

若变更失败,保持服务停止,将已核验的旧配置和旧证书恢复到原路径,重新执行同版本的 prepare 和 docker compose up -d,再复测 HTTPS 与镜像推拉。只替换源证书文件、不重新准备配置,可能无法更新 Harbor 实际使用的证书。

六、备份、回滚与上线验收配图

3. 版本升级后的回滚边界

升级前要同时保留旧安装包、旧部署目录和完整数据备份。若升级触发数据库迁移,不能简单换回旧镜像并连接新数据库。

需要回滚时,应停止新版本,在干净的恢复环境或替换数据卷上恢复升级前的完整备份,再使用对应旧版本启动。不要将备份直接覆盖到正在运行或混有新数据的数据库目录。

恢复会丢失备份之后新增的镜像、成员、令牌及配置变更,因此上线前要明确可接受的数据损失窗口和停机时间。

4. 上线验收检查清单

  • [ ] DNS、IPv4/IPv6 地址与实际入口一致,必要来源可访问,非授权来源被拒绝。
  • [ ] SSH 管理入口受限,数据库、Redis 和 Registry 内部端口未对外暴露。
  • [ ] /srv/harbor 确认为数据盘挂载点,重启后挂载与启动顺序已经验证。
  • [ ] HTTPS 域名、证书链和有效期正确,客户端未关闭 TLS 校验。
  • [ ] 管理员密码已更换,配置文件、私钥和机器人令牌受保护。
  • [ ] 项目默认私有,构建和部署使用不同机器人账号。
  • [ ] 推送、跨客户端拉取、digest 核对及三项负向权限测试通过。
  • [ ] 数据盘容量、inode、系统盘、日志增长和项目配额均有监控。
  • [ ] 若启用扫描,漏洞数据库更新和扫描结果已经验证。
  • [ ] 证书续期后会重新准备配置、重建服务并验证实际提供的证书。
  • [ ] 冷备份已异机保存,并在隔离环境完成恢复演练。
  • [ ] 明确单节点停机影响、升级回滚条件及备份之后的数据损失范围。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3868.html

相关推荐