在云原生技术飞入寻常百姓家的今天，很多 HomeLab 玩家的 NAS 或者家庭服务器上都运行着几十甚至上百个 Docker 容器。从 Jellyfin 媒体服务器到 Home Assistant 智能家居中枢，容器化已经成为部署家庭服务的标准方式。

Docker 极大地简化了我们"折腾"新应用的流程，但随之而来的问题是：自己构建的、或者为了加速而拉取下来的镜像，该放在哪里？

对于轻度用户，直接用 Docker Hub 也没问题。但对于追求极致体验的 HomeLab 玩家来说，网络环境的不确定性、Docker Hub 的拉取频率限制、以及对自己数据的掌控欲，使得搭建一个私有的镜像仓库成为了进阶必修课。而在众多方案中，Harbor 凭借其强大的功能，成为了 HomeLab 里的"核武器"级装备。

本文将从 HomeLab 的视角，深入了解 Harbor 的核心价值以及它为何值得你投入资源去部署。

一、什么是 Harbor

Harbor 是一个开源的云原生工件仓库（Cloud Native Artifact Registry）。虽然它出身名门（VMware 于 2014 年发起，2016 年开源，2018 年 7 月加入 CNCF，并于 2020 年 6 月正式毕业成为 CNCF 顶级项目），听起来非常"企业级"，但它同样适合家庭环境。

简单来说，在你的 HomeLab 里，Harbor 就是你的 "私有 Docker Hub"。它在 Docker 官方的基础 Registry（现已更名为 CNCF Distribution 项目）之上，穿上了一层漂亮且功能强大的"外衣"，提供了图形化界面、权限管理、镜像同步和安全扫描等功能。

💡 一句话总结：Harbor = 本地高速 Docker 仓库 + 漂亮的 Web 管理界面 + 自动化同步工具 + 企业级安全扫描。

值得注意的是，自 Harbor 2.0 版本起，Harbor 成为首个完全兼容 OCI（Open Container Initiative）规范的开源镜像仓库。这意味着 Harbor 不仅能存储传统的 Docker 容器镜像，还能存储各种云原生工件（Artifacts），包括：

这种"万能仓库"的特性，让 Harbor 成为整合你所有云原生资产的理想选择。

二、为什么你的 HomeLab 需要 Harbor

你可能会问："我就几台机器，直接 docker save 和 docker load 不行吗？或者直接搭个简单的 registry 容器？"

当然可以，但 Harbor 解决的是从"能用"到"好用"的质变，特别是解决了 HomeLab 常见的以下痛点：

1️⃣ 告别龟速拉取，实现内网千兆/万兆分发

这是最直观的收益。受限于国内网络环境，从 Docker Hub 拉取镜像经常速度感人，甚至连接超时。

🏠 HomeLab 场景：你在 Harbor 中配置"代理缓存（Proxy Cache）"功能。当你第一次拉取 nginx 镜像时，Harbor 会通过代理下载并缓存到本地硬盘。之后，你家里所有的设备（树莓派、软路由、NAS）再拉取 nginx 时，走的都是内网流量，速度直接跑满你的千兆或 2.5G 内网，秒级完成。

2️⃣ 统一管理你的"魔改"镜像

HomeLab 玩家最喜欢做的事就是"魔改"：为了汉化修改代码、为了精简体积更换 Base 镜像、或者为了特定的硬件（如 N1 盒子）重新编译 ARM 架构镜像。

🏠 HomeLab 场景：你无需再把这些魔改后的镜像手动拷贝到每台机器上，直接 docker push 到 Harbor。你的所有设备都能随时拉取到你定制的最新版镜像。

3️⃣ 多设备环境的"中转站"

很多玩家家里有多种架构的设备：x86 的服务器、ARM 的树莓派/Mac、甚至 RISC-V 的开发板。

🏠 HomeLab 场景：你可以在性能最强的 x86 服务器上配置 CI/CD（如 Jenkins 或 Drone），自动构建不同架构的镜像并推送到 Harbor。其他弱性能设备只需负责拉取并运行，无需在本地进行漫长的编译过程。

4️⃣ 漂亮的图形化管理界面 (GUI)

原生的 Docker Registry 只有一个 API 接口，想看里面存了什么镜像还得靠 curl 命令或者第三方简陋的 UI。

🏠 HomeLab 场景：Harbor 提供了一个极其现代化的 Web 界面。你可以像浏览 App Store 一样浏览你的镜像库，清晰地看到每个镜像的标签（Tag）、大小、上传时间，甚至可以直接查看镜像的构建历史。这对于强迫症玩家来说极度舒适。

5️⃣ 镜像复制（Replication）：你的异地灾备

如果你是一个硬核玩家，可能在公司、老家或者云服务器上还有一套环境。

🏠 HomeLab 场景：Harbor 支持强大的复制策略。你可以设置规则，让家里的 Harbor 自动把重要的镜像同步到你购买的廉价云服务器上作为冷备份。或者反过来，让云服务器下载好镜像，自动同步回你家里的 NAS，利用云服务器的带宽解决家庭宽带拉取慢的问题。

6️⃣ 安全漏洞扫描

虽然是家庭环境，但安全依然重要。你从网上随便找的 latest 镜像真的安全吗？

🏠 HomeLab 场景：Harbor 内置了 Trivy 扫描器（自 Harbor 2.2 版本起成为默认扫描器）。当你把镜像推上来时，它会自动扫描是否存在已知的 CVE 漏洞。这能帮你识别出那些常年不更新、潜藏风险的"僵尸"镜像。

7️⃣ 应对 Docker Hub 政策变化的"避风港"

2025 年，Docker Hub 曾计划大幅收紧免费用户的拉取限制（从 100 次/6 小时 降至 10 次/小时），虽然该政策最终未强制执行，但这种不确定性本身就是风险。根据 Docker 官方声明，未来任何限制变更将提前至少 6 个月通知。

拥有自己的 Harbor 实例意味着：

• ✅ 完全不受第三方服务条款和速率限制的影响
• ✅ 敏感镜像不暴露在公共网络
• ✅ 可实施细粒度的访问控制和审计
• ✅ 与源代码托管平台解耦，避免供应商锁定

当然，在选择容器镜像仓库时，了解各方案的差异有助于做出正确决策。以下是 2025 年主流方案的对比：

📊 市场参考数据：根据 2025 年 11 月的数据，在容器镜像仓库领域，Harbor 占据约 26.2% 的市场心智份额，JFrog 约 29.0%。Harbor 作为完全免费的开源方案，性价比极高。值得注意的是，Mirantis 公司已将其商业产品 Mirantis Secure Registry (MSR) 的开源核心迁移至 CNCF Harbor，这进一步证明了 Harbor 在企业级应用中的成熟度。

三、极简版 Harbor 架构原理

Harbor 的部署其实就是一个大型的 Docker Compose 项目。它虽然组件多，但逻辑清晰：

🔄 请求流程简述：

用户/Docker CLI  →  Nginx Proxy  →  Core Service（认证/授权）
                                         ↓
                              Registry（镜像存取）
                                         ↓
                              PostgreSQL（元数据）
                                         ↓
                              Job Service（异步任务：扫描/复制/清理）

💾 存储架构说明：

Harbor 的镜像数据存储具有高度灵活性。除了默认的本地文件系统外，还支持以下后端存储：

• 对象存储：S3、Azure Blob、Google Cloud Storage、阿里云 OSS、MinIO
• 分布式存储：Ceph（通过 S3 接口）

对于 HomeLab 用户，通常使用本地 NAS 存储即可。如果你使用 TrueNAS 或群晖，可以创建专用的共享目录挂载给 Harbor 使用。

四、快速上手：如何在 HomeLab 部署 Harbor

对于 HomeLab 用户，最推荐使用 Docker Compose 进行离线部署，稳定且易于维护。

📋 前置条件

⚠️ 重要提示：Harbor 组件较多，建议至少分配 4GB 内存。如果启用 Trivy 扫描功能，内存消耗会更高（首次扫描需下载漏洞数据库）。对于资源受限的设备（如树莓派），可考虑使用更轻量的 Docker Registry + 第三方 UI 方案。

📝 简要安装步骤

Step 1：下载离线安装包

# 访问 GitHub Releases 页面下载最新版本
# https://github.com/goharbor/harbor/releases
# 截至 2025 年底，最新稳定版为 v2.13.x

wget https://github.com/goharbor/harbor/releases/download/v2.13.3/harbor-offline-installer-v2.13.3.tgz

💡 为什么选择离线包：离线包包含所有预构建的 Docker 镜像，无需在安装时从 Docker Hub 拉取，既快速又稳定，特别适合网络环境不佳的 HomeLab。

Step 2：解压并配置 harbor.yml

tar xzvf harbor-offline-installer-v2.13.3.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml

打开 harbor.yml 进行编辑，以下是关键配置点：

# ========== 关键修改点 1：Hostname ==========
# 如果你有内网域名（如通过 Pi-hole/AdGuard Home 配置），填域名
# 没有就填服务器的静态 IP（不要用 localhost 或 127.0.0.1）
hostname: harbor.home.lan  # 或 192.168.1.100

# ========== 关键修改点 2：HTTPS 配置 ==========
# 强烈建议开启 HTTPS，否则 Docker 会拒绝连接
https:
  port: 443
  certificate: /your/certificate/path/server.crt
  private_key: /your/certificate/path/server.key

# ========== 关键修改点 3：管理员密码 ==========
harbor_admin_password: YourStrongPassword123!

# ========== 关键修改点 4：数据存储路径 ==========
data_volume: /data/harbor  # 确保这个目录有足够空间

🔐 关于 HTTPS 证书的几种方案：

如果使用自签名证书，Harbor 安装脚本可以自动生成，但你需要在所有 Docker 客户端配置信任该 CA。

Step 3：执行安装脚本

# 基础安装
sudo ./install.sh

# 推荐：一步到位启用漏洞扫描
sudo ./install.sh --with-trivy

# 可选：同时启用 Chart 仓库服务（2.8+ 已内置 OCI Charts，无需此选项）
# sudo ./install.sh --with-trivy --with-chartmuseum  # 仅 2.7 及以下版本需要

⏱️ 安装过程通常需要 3-5 分钟，脚本会自动：

• 加载离线镜像到本地 Docker
• 生成必要的配置文件
• 启动所有服务容器

Step 4：验证安装

# 检查所有容器是否正常运行
docker compose ps

# 你应该看到类似这样的输出：
# NAME                IMAGE                                  STATUS
# harbor-core         goharbor/harbor-core:v2.13.3          Up (healthy)
# harbor-db           goharbor/harbor-db:v2.13.3            Up (healthy)
# harbor-jobservice   goharbor/harbor-jobservice:v2.13.3    Up (healthy)
# harbor-log          goharbor/harbor-log:v2.13.3           Up (healthy)
# harbor-portal       goharbor/harbor-portal:v2.13.3        Up (healthy)
# nginx               goharbor/nginx-photon:v2.13.3         Up (healthy)
# redis               goharbor/redis-photon:v2.13.3         Up (healthy)
# registry            goharbor/registry-photon:v2.13.3      Up (healthy)
# registryctl         goharbor/harbor-registryctl:v2.13.3   Up (healthy)
# trivy-adapter       goharbor/trivy-adapter-photon:v2.13.3 Up (healthy)

打开浏览器，访问你的 IP 或域名，看到那个蓝色的登录界面，恭喜你，你的私有镜像仓库上线了！🎉

默认管理员账号：admin，密码：你在 harbor.yml 中设置的密码。

五、安装后的基础配置建议

成功安装 Harbor 后，以下是一些推荐的初始配置：

1. 创建项目结构

Harbor 使用"项目"（Project）来组织镜像，类似于 Docker Hub 的用户名/组织名。建议的项目规划：

2. 配置代理缓存（Proxy Cache）

这是 HomeLab 最实用的功能之一。设置步骤：

1. 进入 管理 → 仓库管理 → 新建目标
2. 添加 Docker Hub 端点：https://registry-1.docker.io
3. 创建新项目，类型选择 代理缓存，关联上述端点

之后拉取镜像时使用：

docker pull your-harbor.lan/proxy-cache/library/nginx:latest

3. 配置自动扫描策略

进入项目设置，启用：

• ✅ 推送时自动扫描
• ✅ 阻止存在高危漏洞的镜像部署（可选）

六、常见问题与故障排除

Q1：Docker 客户端报错 "x509: certificate signed by unknown authority"

原因：使用了自签名证书但客户端未信任

解决方案：

# 在每个 Docker 客户端执行
sudo mkdir -p /etc/docker/certs.d/your-harbor.lan/
sudo cp ca.crt /etc/docker/certs.d/your-harbor.lan/

# 或者配置 Docker daemon 信任不安全仓库（不推荐）
# 编辑 /etc/docker/daemon.json
{
  "insecure-registries": ["your-harbor.lan"]
}
sudo systemctl restart docker

Q2：Trivy 首次扫描非常慢

原因：Trivy 需要下载漏洞数据库（约 600MB）

解决方案：

• 耐心等待首次下载完成
• 对于离线环境，可以手动下载数据库并配置离线模式。Harbor 2.13.2 增加了"跳过 Java 数据库更新"选项用于离线场景

Q3：升级 Harbor 版本的注意事项

⚠️ Harbor 仅支持从 n-2 小版本升级。例如：

• ✅ 2.11 → 2.13（支持）
• ❌ 2.9 → 2.13（不支持，需分步升级）

升级前务必备份 PostgreSQL 数据库和 /data 目录！

📚 总结

在 HomeLab 中部署 Harbor，不仅仅是为了"存镜像"。

如果你厌倦了 Docker Hub 的限速，或者想让你的家庭数据中心看起来更专业、更自动化，那么 Harbor 绝对是你值得投入时间去折腾的"首选利器"。

随着你对 OCI 标准的深入了解，你甚至可以用它来存储 Helm Charts、SBOM 文件、甚至 AI 模型工件（Harbor 2.13 引入了 CNAI 集成），为将来进阶 K8s 和 MLOps 打下坚实基础。

📎 参考资源

• Harbor 官方网站
• Harbor GitHub 仓库
• CNCF Harbor 项目页面
• Harbor 安装文档
• Trivy 漏洞扫描器
• Docker Hub 使用限制政策
• 2025 容器镜像仓库选型指南