Harbor：HomeLab 玩家的终极 Docker 镜像仓库

發布人 Brave 2025-12-29 04:22

在云原生技术飞入寻常百姓家的今天，很多 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），包括：

工件类型	用途说明
Helm Charts	Kubernetes 应用包管理
SBOM（软件物料清单）	软件成分分析与供应链安全
OPA Bundles	Open Policy Agent 策略包
Singularity 镜像	高性能计算容器
WASM 模块	WebAssembly 工件
签名与证明文件	Cosign/Notary 签名等

这种"万能仓库"的特性，让 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 年主流方案的对比：

特性	Harbor	Docker Hub	Docker Registry (Distribution)	JFrog Artifactory
部署方式	自托管	云服务	自托管	自托管/云服务
成本	免费开源	免费层有限制	免费开源	企业版收费
Web UI	✅ 功能丰富	✅	❌ 需第三方	✅
漏洞扫描	✅ 内置 Trivy	✅（付费版）	❌	✅
镜像复制	✅	❌	❌	✅
RBAC 权限	✅ 精细控制	✅（团队版）	❌	✅
OCI 工件支持	✅ 完整支持	部分支持	✅	✅
SBOM 管理	✅（2.11+）	❌	❌	✅
LDAP/OIDC 集成	✅	✅（企业版）	❌	✅
适合场景	HomeLab/企业	个人/开源项目	极简需求	大型企业

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

三、极简版 Harbor 架构原理

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

组件	职责	技术栈
🚪 Proxy (Nginx)	门户大门，负责处理所有的 HTTPS 请求，路由到内部服务	Nginx
🧠 Core Services	大脑，处理登录、权限、Web 界面逻辑、API 网关	Go
📝 Database (PostgreSQL)	记账本，记录有哪些镜像、谁上传的、权限配置等元数据	PostgreSQL
📦 Registry	仓库管理员，真正负责把镜像文件（blob）存到硬盘里	Distribution
⚙️ Job Services	打工仔，负责后台默默地同步镜像、清理垃圾、执行扫描任务	Go
🔒 Trivy（可选）	安全卫士，扫描镜像中的已知漏洞	Trivy
📊 Redis	缓存层，提供会话管理和临时数据存储	Redis

🔄 请求流程简述：

用户/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 进行离线部署，稳定且易于维护。

📋 前置条件

要求	推荐配置	最低配置
操作系统	Ubuntu 22.04 LTS / Debian 12	任意现代 Linux 发行版
内存	8GB+	4GB（不含 Trivy）
存储	SSD 100GB+	取决于镜像数量
Docker	24.x+	20.10+
Docker Compose	v2.x（Compose Plugin）	v1.29+（standalone）
CPU	4 核+	2 核

⚠️ 重要提示：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 证书的几种方案：

方案	适用场景	难度
自签名证书	纯内网使用，需在客户端配置信任	⭐ 简单
Let's Encrypt	有公网域名，可自动续期	⭐⭐ 中等
内网 CA	已有 PKI 基础设施	⭐⭐⭐ 复杂
反向代理终结	使用 Traefik/Nginx Proxy Manager	⭐⭐ 中等

如果使用自签名证书，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 的用户名/组织名。建议的项目规划：

项目名	用途	访问级别
`library`	系统默认项目，通用基础镜像	私有
`homelab`	你的自定义镜像	私有
`proxy-cache`	代理缓存 Docker Hub 镜像	私有
`public`	可分享给朋友的镜像	公开

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

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

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

之后拉取镜像时使用：

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，不仅仅是为了"存镜像"。

收益维度	具体价值
🎮 数据主权	拥有数据的绝对掌控权，不受第三方政策变化影响
⚡ 性能提升	内网千兆/万兆分发，极大提升部署速度和体验
🔒 安全加固	漏洞扫描、访问控制、审计日志一应俱全
📖 技能成长	接触 HTTPS 证书、反向代理、Docker Compose、OCI 标准等知识
🚀 进阶基石	为 Kubernetes、GitOps、SBOM 供应链安全等进阶之路打下基础

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

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

网络安全与大数据研究小组

組織者: