家用住宅主机Linux Harbor私有镜像仓库搭建教程
为什么要在家用主机上搭 Harbor
许多开发者或运维朋友希望在家庭网络里拥有一套私有的镜像仓库，用于同步公共镜像、管理自研容器项目。
Harbor 作为开源的企业级镜像仓库，功能完整（权限、扫描、复制），完全可以在一台普通 Linux 主机上跑起来。
本文假设你只有一台家用电脑或二手服务器，系统为 Ubuntu 20.04/22.04 或 CentOS 7/8，并已装好基础编程环境。
跟着做，你就能得到一个可存可取、支持 HTTPS 访问的私有仓库。
准备阶段：确认硬件与软件
硬件最低要求
- CPU： 2 核及以上
- 内存： 推荐 4GB 以上（Harbor 本身 + PostgreSQL + Redis 约占用 1.5GB）
- 磁盘： 至少 40GB（镜像存储会快速增长）
软件清单
- 操作系统： Ubuntu 22.04（本文以此为例）或 CentOS 7。
- Docker： 版本 20.10+，含 Docker Compose（可单独安装）。
- 域名与证书： 家用环境可用
xxx.local或自定义内网域名，并使用 Let's Encrypt 或自签证书。
如果没有域名，可在客户端通过修改 hosts 文件临时使用 IP 访问（非 HTTPS 需额外配置）。
第一步：安装 Docker 与 Docker Compose
安装 Docker（Ubuntu）
sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo 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 $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin验证 Docker 与 Compose
sudo docker --version
sudo docker compose version（若 docker compose 报错，可改用 docker-compose，但新版已推荐无横杠版本。
）
第二步：下载 Harbor 并准备配置
- 获取最新离线安装包（避免在线下载依赖慢）：
wget https://github.com/goharbor/harbor/releases/download/v2.11.0/harbor-offline-installer-v2.11.0.tgz
tar zxf harbor-offline-installer-v2.11.0.tgz
cd harbor- 复制配置文件模板：
cp harbor.yml.tmpl harbor.yml- 编辑 harbor.yml（重点修改以下项）：
hostname: harbor.internal.local # 改成你的内网域名或 IP（如192.168.1.100）
http:
port: 80
https:
port: 443
certificate: /data/cert/server.crt
private_key: /data/cert/server.key
harbor_admin_password: YourStrongSecret123!如果不想用 HTTPS，可将 https 部分整段注释掉，但生产不建议。家用环境建议至少配置自签证书。
- 生成自签证书（跳过则直接注释 https）：
mkdir -p /data/cert
openssl req -newkey rsa:4096 -nodes -sha256 -keyout /data/cert/server.key -x509 -days 365 -out /data/cert/server.crt -subj "/C=CN/ST=Beijing/L=Beijing/O=Home/CN=harbor.internal.local"证书生成后必须在所有需要 push/pull 的客户端上信任该 CA（否则报 x509 错误）。
第三步：执行安装脚本
sudo ./install.sh安装过程会拉取 Harbor 所需镜像并启动容器，耗时约 2-5 分钟。
安装完成后输出包含管理后台地址、管理员账号（admin）和密码。
第四步：验证功能是否正常
浏览器访问
在局域网内任意设备浏览器输入 https://harbor.internal.local 或 https://192.168.1.100，看到 Harbor 登录页面即成功。
使用 Docker 客户端登录
docker login harbor.internal.local -u admin -p YourStrongSecret123!如果出现 Error response from daemon: Get "https://harbor.internal.local/v2/": x509: certificate signed by unknown authority，说明客户端未信任自签证书。
解决方法（以 Ubuntu 为例）：
# 将服务端证书复制到客户端并信任
sudo cp server.crt /usr/local/share/ca-certificates/harbor.crt
sudo update-ca-certificates
sudo systemctl restart docker推送测试镜像
docker pull hello-world
docker tag hello-world harbor.internal.local/library/hello-world:latest
docker push harbor.internal.local/library/hello-world:latest在 Harbor Web 界面的“项目”->“library”中可看到该镜像。
避坑指南：家用环境常见问题
- 内存不足导致容器退出：降低 Harbor 资源占用，编辑
harbor.yml中database和redis配置，或使用--memory参数限制。 - 域名解析问题：家用路由器不支持自定义域名解析，建议在每一台机器的 hosts 文件添加映射，或在局域网 DNS（如 AdGuard Home）中设置。
- 端口冲突：如果 80/443 已被占用，可在
harbor.yml中修改为其他端口（如 8080/8443），但之后登录也需要指定端口。 - 磁盘爆满：定期清理旧镜像。Harbor 自带垃圾回收功能，可在“管理”->“垃圾清理”中执行。
- 重启后服务丢失：Harbor 安装默认不会自启动。将 Docker 容器设置为
restart: always需修改docker-compose.yml（不推荐手动改，用docker-compose up -d启动即可）。
常见问题解答（FAQ）
问：我可以用 IP 直接访问 Harbor 吗？
答：可以，但需在 harbor.yml 中 hostname 填写 IP，并且客户端必须信任证书或使用 HTTP 模式（不推荐）。
问：Harbor 后台登录密码忘记怎么办？
答：进入 Harbor 数据库（PostgreSQL）重置 harbor_user 表密码字段。更简单的方法：重装并保留 /data 目录下的 secretkey 文件。
问：家用带宽有限，推送大镜像很慢怎么办？
答：可先在本地导出镜像为 tar 包，再 docker load 到主机，或使用 Harbor 的复制功能从公网镜像站同步。
结尾
通过以上步骤，你已经成功在家用 Linux 主机上跑起了 Harbor 私有镜像仓库。
后续可以根据需要配置 LDAP 认证、开启安全扫描、设置项目配额等。
如果在执行中遇到其他异常，优先检查 Docker 日志（docker logs <容器名>）和 Harbor 管理日志（/var/log/harbor/）。
如果你对跨网访问或备份容灾感兴趣，也可以在栏目内搜索“Harbor 高可用”或“HTTPS 反向代理”继续了解。
