企业官网建设流程全解析

1. 为什么你需要一个自己的Harbor镜像仓库？

如果你已经用了一段时间Docker，或者正在团队里搞容器化，那你肯定遇到过下面这些让人头疼的事儿：从Docker Hub拉镜像，速度慢得像蜗牛，特别是那些大镜像，一个上午就耗在等待上了；团队内部开发了一堆微服务，每个服务都有自己的镜像，版本管理混乱，谁手滑删了latest标签，整个测试环境可能就崩了；更别提安全问题了，直接把业务镜像推到公共仓库，心里总是不踏实。这时候，一个搭建在自己服务器上的私有镜像仓库，就成了刚需。

Harbor，就是这个领域的“明星选手”。它不是一个简单的镜像存储服务器，而是一个企业级的、开源的容器镜像仓库解决方案。你可以把它理解为你公司内部的“Docker Hub Pro Max版”。它原生支持镜像的存储、分发、安全扫描、漏洞分析、权限管理、镜像复制，甚至还能做Helm Chart仓库。对于中小团队或者个人开发者来说，自己搭一套Harbor，意味着你彻底掌控了镜像的生命周期，构建、测试、发布的流程可以变得非常清晰和自动化。

我见过不少团队一开始图省事，用Docker自带的registry:2镜像搭个简易仓库。初期确实够用，但一旦镜像数量上来、团队成员增多，没有UI界面、没有权限控制、没有安全审计的短板就暴露无遗，后期迁移到Harbor反而更麻烦。所以，如果你的项目已经步入正轨，或者你预见到未来会有这些需求，那么从一开始就选择Harbor，绝对是笔划算的投资。这篇教程，就是带你从零开始，手把手搭建一个生产可用的Harbor服务，我会把每一步的原理、可能遇到的坑，以及我趟过的雷，都给你讲清楚。

2. 部署前准备：环境、资源与关键决策

在真正动手安装之前，充分的准备工作能避免你掉进无数个坑里。这一部分，我们不仅要检查环境，更要理解每个要求背后的原因。

2.1 硬件与操作系统要求

Harbor本身对资源要求并不苛刻，但你需要根据预期的镜像存储量和并发访问量来规划。

• CPU与内存：对于一个小型团队或测试环境，2核4GB内存是起步配置。如果镜像数量庞大（超过数千个）或需要启用漏洞扫描等重度功能，建议配置4核8GB或更高。内存不足会导致Harbor的UI组件（特别是Core和Jobservice）响应缓慢甚至崩溃。
• 磁盘空间：这是最重要的资源。你需要预估：单个镜像的平均大小 × 镜像数量 × 保留的版本数。例如，一个200MB的基础镜像，团队有20个服务，每个服务保留10个历史版本，那么仅这部分就需要约 200MB * 20 * 10 = 40GB。这还不包括镜像的层（Layer）去重存储带来的节省，以及日志、数据库等开销。强烈建议预留至少100GB的专用存储空间，并确保有便捷的扩容方案。磁盘I/O性能也很关键，使用SSD能显著提升镜像推送和拉取的速度。
• 操作系统：官方主要支持Linux发行版。我强烈推荐使用Ubuntu 20.04/22.04 LTS或CentOS/RHEL 7/8。这些系统有长期支持，社区资料丰富，能减少因系统版本过新或过旧带来的兼容性问题。本文将以Ubuntu 22.04 LTS为例进行演示，其他系统的命令会有细微差别，但核心逻辑一致。

2.2 软件依赖安装与配置

Harbor的运行依赖于Docker和Docker Compose。它本质上是一组通过Docker Compose编排起来的容器。

1. 安装Docker：这是基石。不要使用系统默认的、过旧的Docker版本。

   # 更新软件包索引 sudo apt-get update # 安装必要的依赖，允许apt通过HTTPS使用仓库 sudo apt-get install -y ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置Docker稳定版仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 再次更新，并安装Docker引擎 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

   安装后，将当前用户加入docker组，避免每次都要sudo。

   sudo usermod -aG docker $USER # 退出当前终端并重新登录，使组生效

   验证安装：docker --version和docker compose version（注意是compose，不是docker-compose）。

2. 安装Docker Compose（独立版本）：虽然Docker现在内置了docker compose插件，但Harbor的安装脚本和部分文档仍可能依赖独立的docker-compose（带短横线）命令。为了兼容性，我们两者都装。

   # 下载Docker Compose的稳定版本（例如v2.20.0） sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose # 赋予可执行权限 sudo chmod +x /usr/local/bin/docker-compose # 验证 docker-compose --version

   注意：这里有一个常见的混淆点。docker compose（插件）和docker-compose（独立二进制文件）命令功能几乎相同，但并非100%兼容所有历史脚本。Harbor的install.sh脚本通常会检查docker-compose命令。确保两个命令都能用是最稳妥的。

2.3 关键决策：安装模式与证书

这是安装前最重要的选择题，决定了你后续的使用方式和安全性。

• 安装模式：Harbor提供在线和离线安装包。我强烈推荐下载离线安装包。在线安装包在安装过程中会从互联网拉取所有Docker镜像，如果你的服务器网络不稳定，或者处于内网环境，这个过程极易失败。离线安装包（约1GB）包含了所有必需的镜像，部署过程完全离线，稳定可靠。

  • 前往 Harbor GitHub Releases 页面，下载最新稳定版（如v2.8.0）的离线安装包，文件名类似harbor-offline-installer-v2.8.0.tgz。

• HTTP vs HTTPS：对于任何生产或准生产环境，必须使用HTTPS。使用HTTP会导致Docker客户端在推送/拉取镜像时报错（默认需要安全连接），你需要修改所有客户端Docker守护进程的配置，这是巨大的安全隐患和管理负担。

  • 方案一（推荐，用于正式环境）：使用受信任的CA签发的证书（如 Let‘s Encrypt）。这需要你有自己的域名，并将该域名解析到Harbor服务器的IP。
  • 方案二（测试/内部环境）：使用自签名证书。这是本篇教程采用的方式，因为它不依赖外部域名和CA，适合快速搭建内部测试环境。你需要生成证书，并在所有访问Harbor的客户端机器上信任该证书。

3. 步步为营：Harbor离线安装与基础配置

假设你已经将下载好的harbor-offline-installer-v2.8.0.tgz上传到了服务器的/opt目录下。

3.1 解压与准备配置文件

# 切换到安装目录 cd /opt # 解压离线安装包 tar xzvf harbor-offline-installer-v2.8.0.tgz # 进入解压后的目录 cd harbor

解压后，你会看到几个关键文件，其中harbor.yml.tmpl是配置模板。我们需要复制它并生成我们自己的配置文件。

cp harbor.yml.tmpl harbor.yml

现在，用文本编辑器（如vim或nano）打开harbor.yml。下面是一个针对自签名证书场景的最小化配置示例，我会逐段解释：

# 设置 Harbor 服务器的主机名。这是最重要的配置之一！ # 如果你有域名，就写域名（如 harbor.yourcompany.com）。 # 如果是内网IP测试，就写IP地址（如 192.168.1.100），但注意证书需要匹配。 hostname: your.harbor.domain # 请务必修改为你服务器的IP或域名 # HTTP相关配置（因为我们用HTTPS，所以可以禁用或保留一个端口给重定向） http: port: 80 # HTTP端口，可以关闭或用于重定向到HTTPS # HTTPS配置 - 这是核心 https: port: 443 # HTTPS端口 # 证书和私钥的路径。我们将自己生成，放在当前目录下。 certificate: /opt/harbor/your.harbor.domain.crt private_key: /opt/harbor/your.harbor.domain.key # Harbor管理员用户的初始密码。安装后一定要改！ harbor_admin_password: Harbor12345 # 请修改为强密码！ # Harbor的数据持久化目录 data_volume: /data # Harbor的日志配置 log: level: info # 日志级别：info, debug, error, warning local: rotate_count: 50 # 保留的日志文件个数 rotate_size: 200M # 每个日志文件大小 location: /var/log/harbor # 日志存储路径 # 其他组件可以暂时保持默认 # ...

关键提示：hostname配置必须与后续生成证书时使用的Common Name (CN)完全一致，否则客户端会报证书域名不匹配的错误。如果使用IP，这里就填IP，证书CN也必须是这个IP。

3.2 生成自签名证书（用于HTTPS）

我们在Harbor目录下生成证书。首先，创建一个目录存放证书，并进入。

mkdir -p /opt/harbor/certs cd /opt/harbor/certs

假设你的hostname配置为192.168.1.100（请替换为你的实际IP或域名）。

1. 生成根证书私钥和自签名根证书（充当自己的CA）：

   openssl genrsa -out ca.key 4096 openssl req -x509 -new -nodes -sha512 -days 3650 \ -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=192.168.1.100" \ -key ca.key \ -out ca.crt

   • -subj参数里的信息可以根据需要修改，但CN必须设置为你的 Harbor 主机地址（IP或域名）。
   • -days 3650表示证书10年有效，测试环境可以设短点。

2. 生成服务器证书签名请求（CSR）和私钥：

   openssl genrsa -out your.harbor.domain.key 4096 openssl req -sha512 -new \ -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=192.168.1.100" \ -key your.harbor.domain.key \ -out your.harbor.domain.csr

3. 生成x509 v3扩展文件：这个文件告诉OpenSSL，这个证书是用于服务器身份验证的。

   cat > v3.ext <<-EOF authorityKeyIdentifier=keyid,issuer basicConstraints=CA:FALSE keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment extendedKeyUsage = serverAuth subjectAltName = @alt_names [alt_names] DNS.1=192.168.1.100 # 如果你的hostname是域名，可以同时添加IP和域名 # DNS.1=harbor.yourcompany.com # IP.1=192.168.1.100 EOF

   重要：[alt_names]部分必须包含你的hostname。如果是IP，就写IP.1=；如果是域名，就写DNS.1=。可以同时写多个。

4. 使用自签CA签发服务器证书：

   openssl x509 -req -sha512 -days 3650 \ -extfile v3.ext \ -CA ca.crt -CAkey ca.key -CAcreateserial \ -in your.harbor.domain.csr \ -out your.harbor.domain.crt

5. 转换证书格式供Docker使用：Docker客户端需要一种特定格式的证书。

   openssl x509 -inform PEM -in your.harbor.domain.crt -out your.harbor.domain.cert

6. 将证书复制到Docker和系统信任库（在Harbor服务器本机）：

   # 复制服务器证书和密钥到Harbor配置指定的路径（我们之前配置在/opt/harbor/） cp your.harbor.domain.crt /opt/harbor/ cp your.harbor.domain.key /opt/harbor/ # 复制CA根证书和服务器证书到Docker证书目录 mkdir -p /etc/docker/certs.d/192.168.1.100/ # 目录名必须是你的Harbor主机地址 cp your.harbor.domain.cert /etc/docker/certs.d/192.168.1.100/ cp ca.crt /etc/docker/certs.d/192.168.1.100/ # 将CA根证书添加到系统信任库（Ubuntu） cp ca.crt /usr/local/share/ca-certificates/192.168.1.100.crt sudo update-ca-certificates

   完成这些步骤后，Harbor服务器本机的Docker客户端就已经信任了这个自签名证书。

3.3 执行安装脚本

现在，一切准备就绪。回到Harbor目录，执行安装脚本。

cd /opt/harbor sudo ./install.sh

这个脚本会做以下几件事：

1. 解析harbor.yml配置文件。
2. 为各个组件（PostgreSQL, Redis, Core, Jobservice, Portal, Registry等）准备环境配置文件。
3. 通过docker-compose命令拉取并启动所有容器（离线包已包含镜像，所以很快）。

安装成功的标志是，最后看到类似下面的输出，并且所有容器状态都是Up：

✔ ----Harbor has been installed and started successfully.----

你可以通过docker-compose ps命令来查看所有容器的运行状态。

3.4 防火墙与SELinux配置

如果服务器开启了防火墙，需要放行Harbor使用的端口（默认80和443）。

# 如果使用ufw（Ubuntu） sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw reload # 如果使用firewalld（CentOS/RHEL） sudo firewall-cmd --permanent --add-port=80/tcp sudo firewall-cmd --permanent --add-port=443/tcp sudo firewall-cmd --reload

对于CentOS/RHEL系统，如果开启了SELinux，需要调整策略以允许Docker容器访问宿主机目录。

# 临时设置为宽松模式（重启失效） sudo setenforce 0 # 永久禁用（需要重启） sudo sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

注意：生产环境不建议直接禁用SELinux，而是应该配置正确的SELinux策略。这里为了简化，采用宽松模式。

4. 安装后的关键操作与验证

安装完成只是第一步，要让Harbor真正可用，还需要进行一些关键配置和验证。

4.1 访问Web界面与初始化登录

打开浏览器，访问https://your.harbor.domain（或https://192.168.1.100）。由于使用的是自签名证书，浏览器会显示安全警告，选择“高级”->“继续前往”即可。

使用默认用户名admin和你在harbor.yml中配置的harbor_admin_password（例如Harbor12345）登录。

登录后第一件事：立即修改管理员密码！在右上角用户下拉菜单 -> “修改密码”中完成。

4.2 创建项目与配置用户权限

Harbor的核心管理单元是“项目”。镜像必须属于某个项目。

1. 创建项目：点击“项目” -> “新建项目”。

   • 项目名称：例如dev（开发环境）、test（测试环境）、prod（生产环境），或者按团队划分如team-a。
   • 访问级别：
     • 公开：任何能访问Harbor的人（包括未登录用户）都可以拉取此项目下的镜像。适合存放公共基础镜像。
     • 私有：只有被授权的用户才能拉取和推送。这是最常用的设置。
   • 存储配额：可以设置项目可使用的最大存储空间，防止某个项目占用全部磁盘。

2. 创建用户与分配权限：点击“用户管理” -> “新建用户”。

   • 填写用户名、邮箱、密码等信息。
   • 创建用户后，进入具体的项目（如dev），点击“成员” -> “+ 用户”。
   • 选择刚才创建的用户，并分配角色：
     • 项目管理员：拥有项目的全部管理权限。
     • 维护人员：可以推送、拉取镜像，管理项目内的Helm Chart等。
     • 开发人员：可以推送、拉取镜像。
     • 访客：只能拉取镜像。 这种基于项目的RBAC（基于角色的访问控制）权限模型，非常灵活，能满足团队协作的需求。

4.3 客户端Docker配置（信任自签名证书）

要让其他机器上的Docker客户端能推送/拉取镜像，必须让它们信任Harbor服务器的自签名CA证书。

1. 从Harbor服务器获取CA证书：将之前生成的ca.crt文件拷贝到客户端机器上。你可以用scp命令：

   # 在客户端机器执行，从服务器下载ca.crt scp your_username@192.168.1.100:/opt/harbor/certs/ca.crt .

2. 在客户端配置Docker信任该证书：

   • Linux/macOS：

     # 创建对应Harbor主机地址的目录 sudo mkdir -p /etc/docker/certs.d/192.168.1.100/ # 将ca.crt复制进去 sudo cp ca.crt /etc/docker/certs.d/192.168.1.100/ # 重启Docker服务 sudo systemctl restart docker

   • Windows (Docker Desktop)：
     • 将ca.crt文件复制到C:\ProgramData\Docker\certs.d\192.168.1.100\目录下（如果目录不存在则创建）。
     • 重启Docker Desktop。

4.4 基础功能测试：推送与拉取镜像

现在，让我们进行最关键的测试，验证整个链路是否通畅。

1. 登录到Harbor：在客户端机器上，使用Docker命令登录。

   docker login 192.168.1.100

   输入用户名（如admin）和密码。如果成功，会显示Login Succeeded。

2. 标记一个本地镜像：我们以官方的nginx:alpine小镜像为例。

   # 先拉取一个测试镜像 docker pull nginx:alpine # 按照 Harbor 的镜像命名规范重新标记 # 格式：<Harbor主机地址>/<项目名称>/<镜像名称>:<标签> docker tag nginx:alpine 192.168.1.100/library/nginx:alpine

   这里我们把镜像推送到library这个默认的公开项目。你也可以推送到自己创建的私有项目，如192.168.1.100/dev/nginx:alpine。

3. 推送镜像到Harbor：

   docker push 192.168.1.100/library/nginx:alpine

   如果一切配置正确，你会看到镜像层被一层层上传。完成后，在Harbor的Web界面，进入“library”项目，就能看到刚刚推送的nginx镜像。

4. 从Harbor拉取镜像：

   # 先删除本地已标记的镜像 docker rmi 192.168.1.100/library/nginx:alpine # 从Harbor拉取 docker pull 192.168.1.100/library/nginx:alpine

   如果能成功拉取，说明整个安装、配置、网络、证书全部环节都已打通。

5. 生产环境进阶配置与优化

基础安装完成后，Harbor已经可以工作。但要用于生产环境，还需要考虑高可用、性能、安全和维护。

5.1 配置外部数据库与Redis

默认安装使用容器内的PostgreSQL和Redis。这对于测试没问题，但在生产环境，强烈建议使用外部的、有专人维护的数据库和Redis实例。这能带来更好的性能、可靠性和数据安全性。

修改harbor.yml中的相关部分：

# 外部数据库配置 external_database: harbor: host: harbor-db-host # 你的数据库主机IP或域名 port: 5432 # PostgreSQL默认端口 db_name: harbor username: harbor password: your_strong_db_password ssl_mode: disable # 生产环境建议启用SSL max_idle_conns: 50 max_open_conns: 100 # 外部Redis配置 external_redis: host: redis-host # 你的Redis主机IP或域名 port: 6379 password: your_strong_redis_password registry_db_index: 1 jobservice_db_index: 2 chartmuseum_db_index: 3 clair_db_index: 4 trivy_db_index: 5

配置后，需要运行./prepare脚本更新配置，然后停止并重新启动Harbor：docker-compose down -v和docker-compose up -d。注意：迁移数据需要额外步骤，官方文档有详细说明，务必在测试环境演练。

5.2 启用漏洞扫描（Trivy）

安全是Harbor的一大亮点。集成漏洞扫描器后，每当有镜像被推送到仓库，Harbor可以自动或手动触发扫描，并生成漏洞报告。

1. 在harbor.yml中启用Trivy：

   trivy: # 启用漏洞扫描 enabled: true # 忽略未修复的漏洞 ignore_unfixed: false # 安全级别：可设置为“high,critical”只关注高危漏洞 severity: unknown,low,medium,high,critical # 扫描超时时间 timeout: 5m

2. 更新配置并重启：

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

   重启后，在项目下的镜像列表中，点击镜像，在“漏洞”标签页就可以手动触发扫描或查看历史扫描报告。你还可以在项目配置中设置“自动扫描镜像”，实现安全左移。

5.3 配置日志与数据持久化

默认的日志和数据都存储在/data目录下。你需要确保这个目录所在磁盘空间充足，并考虑备份策略。

• 日志：日志路径在harbor.yml的log.local.location中配置。生产环境建议将日志收集到集中的日志平台（如ELK Stack）进行分析。可以修改配置，让容器日志直接输出到stdout/stderr，然后由Docker的日志驱动（如json-file,syslog,journald）或第三方工具（如Fluentd）收集。
• 数据：data_volume配置了镜像和Chart的存储路径。对于大规模部署，可以考虑使用网络存储（如NFS、Ceph、云存储）作为后端，并通过Docker卷插件或修改registry组件的配置来实现。这涉及到更复杂的配置，需要参考Harbor和对应存储的官方文档。

5.4 日常维护与故障排查

• 启停服务：

  # 停止Harbor cd /opt/harbor docker-compose down # 启动Harbor docker-compose up -d # 查看日志（跟踪Core组件日志） docker-compose logs -f core

• 修改配置：任何对harbor.yml的修改，都需要运行./prepare脚本使配置生效，然后重启服务。

  sudo ./prepare sudo docker-compose down -v sudo docker-compose up -d

• 备份与恢复：Harbor的备份主要包括两部分：1) 数据库数据（镜像元数据、用户信息等）；2) 存储卷中的镜像文件。官方提供了harbor.yml中关于备份的配置说明和迁移工具。定期备份/data目录和数据库是必须的。

• 常见问题排查：

  • 无法登录Web界面：检查core、portal、postgresql容器是否正常运行 (docker-compose ps)。查看core容器的日志 (docker-compose logs core)。
  • Docker客户端登录/推送失败：
    • x509: certificate signed by unknown authority：客户端没有正确安装/信任CA证书。检查证书目录和文件权限。
    • Get "https://.../v2/": dial tcp ...:443: connect: connection refused：防火墙未放行443端口，或Harbor服务未启动。
    • denied: requested access to the resource is denied：1) 未登录或登录已过期 (docker login)。2) 用户对该项目没有推送权限。3) 镜像名称中的项目名拼写错误。
  • 磁盘空间不足：Harbor不会自动清理旧的镜像层。需要定期手动或在CI/CD流水线中清理无用镜像。可以通过Web界面删除镜像标签，或者使用Harbor API结合GC（垃圾回收）来清理物理存储。注意：删除镜像标签后，需要手动执行Registry的垃圾回收命令才能真正释放磁盘空间，这需要在Harbor服务器上操作，且服务会短暂中断。

6. 集成到CI/CD流水线

Harbor搭建好后，最大的价值在于无缝集成到你的开发运维流程中。这里以Jenkins Pipeline为例，展示一个简单的推送镜像的步骤。

在你的Jenkinsfile或Pipeline脚本中：

pipeline { agent any environment { HARBOR_REGISTRY = '192.168.1.100' HARBOR_PROJECT = 'dev' IMAGE_NAME = 'my-app' // 使用Jenkins的凭据ID来安全地存储Harbor密码 HARBOR_CREDENTIALS = credentials('harbor-credentials-id') } stages { stage('Build & Push Image') { steps { script { // 1. 构建Docker镜像 docker.build("${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:${BUILD_NUMBER}") // 2. 登录Harbor sh "echo \$HARBOR_CREDENTIALS_PSW | docker login ${HARBOR_REGISTRY} -u \$HARBOR_CREDENTIALS_USR --password-stdin" // 3. 推送镜像 docker.image("${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:${BUILD_NUMBER}").push() // 4. 可选：推送latest标签 sh "docker tag ${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:${BUILD_NUMBER} ${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:latest" sh "docker push ${HARBOR_REGISTRY}/${HARBOR_PROJECT}/${IMAGE_NAME}:latest" } } } } post { always { // 清理工作空间，登出Docker（可选） sh 'docker logout ${HARBOR_REGISTRY}' } } }

这个流水线会在每次构建时，生成一个带构建编号的镜像标签推送到Harbor，同时更新latest标签。在实际生产中，你还需要加入漏洞扫描结果检查、测试环境自动部署等环节。

7. 我踩过的那些坑与避坑指南

最后，分享几个我在多次部署Harbor过程中遇到的典型问题，希望能帮你节省时间。

1. 证书的“主机名/IP不匹配”陷阱：这是最常见的问题。harbor.yml中的hostname、生成证书时-subj参数里的CN、v3.ext文件里的subjectAltName，以及客户端访问时使用的地址，四者必须完全一致。哪怕一个是域名一个是IP，都会导致失败。最稳妥的测试方法是：在客户端用curl -vk https://your.harbor.domain先测试证书是否被信任，再测试Docker。

2. 离线安装包版本与Docker Compose的兼容性：曾经遇到过，用较新版本的docker-compose（v2.x）去安装一个旧版本Harbor（v1.x），因为Compose文件语法不兼容导致启动失败。确保你的Docker Compose版本与Harbor版本大致匹配。如果遇到启动失败，查看docker-compose logs输出的具体错误信息。

3. 磁盘空间耗尽导致服务异常：Harbor的Registry组件在磁盘满时行为不可预测，可能导致推送失败或UI显示异常。一定要设置监控告警，监控/data目录的磁盘使用率。定期清理无用镜像，并在规划时预留足够的缓冲空间（比如用到70%就告警）。

4. 忘记配置客户端证书：在另一台机器上兴致勃勃地测试，结果docker login一直报证书错误。切记，每一台需要访问Harbor的Docker客户端机器，都必须按照步骤4.3配置信任证书。这是一个很容易遗漏的步骤。

5. 修改配置后未重启所有服务：修改harbor.yml后，只运行了./prepare，但没有执行docker-compose down -v && docker-compose up -d，导致新配置不生效。prepare脚本只生成容器的配置文件，必须重启容器才能加载新配置。

6. 使用“localhost”或“127.0.0.1”作为hostname：如果你在服务器本机用Docker客户端测试，这么配置可能暂时能通。但一旦其他机器要访问，就会完全失败。从一开始就使用服务器在网络中可被其他客户端访问的IP地址或域名进行配置，避免后续修改带来的麻烦。

Harbor的安装，难点不在于点击按钮，而在于对网络、证书、存储这些基础设施的理解和正确配置。按照上面的步骤，耐心地走一遍，遇到问题多查日志（docker-compose logs [服务名]），你一定能搭建起一个稳定可靠的私有镜像仓库。当你的团队能顺畅地从内网秒拉镜像，当CI/CD流水线自动将构建好的镜像推送到仓库并触发安全扫描时，你会觉得这一切的折腾都是值得的。