项目介绍
Harbor 是带项目、权限、镜像扫描等功能的镜像仓库。适合团队管理私有镜像;组件较多,需要使用同一发行版的安装器与配置文件,不能用单服务示例代替。
项目隔离镜像,用户和机器人账号控制推拉权限,保留策略帮助管理空间。完整服务栈由对应版本安装器生成。
适合团队私有镜像管理。域名、HTTPS 与数据目录先确定,再执行官方初始化。
核心功能
| 功能 | 作用与使用方式 |
|---|---|
| 项目仓库 | 组织私有镜像 |
| 权限管理 | 限制推送拉取 |
| 机器人账号 | 供流水线使用 |
| 镜像扫描 | 按组件检查风险 |
| 保留策略 | 管理历史版本 |
功能示意

图 1:自制功能示意图,概括本文的使用要点。
项目信息
| 项目 | 说明 |
|---|---|
| 类型 | 项目指南 |
| 分类 | NAS 与运维 |
| 项目仓库 | goharbor/harbor |
| 官方入口或文档 | 直接访问 |
| 整理日期 | 2026-11-14 |
安装与运行
在拥有固定地址的 x86-64 Linux 服务器或群晖 Linux 虚拟机安装 Docker、Compose 和 Python 3。这里使用当前官方 v2.15.5 离线安装包,安装数据放在该 Linux 主机的 /opt/harbor;不要把它当作一个普通 DSM 套件。
Harbor 的 install.sh 会加载离线镜像并生成完整 docker-compose.yml;不能只用一个 harbor-core 镜像代替整套服务。官方离线包还提供 Sigstore 签名资料,可在发布页核对来源。
1. 安装和初始化
sudo -i
mkdir -p /opt/harbor-installer
cd /opt/harbor-installer
curl -fL https://github.com/goharbor/harbor/releases/download/v2.15.5/harbor-offline-installer-v2.15.5.tgz -o harbor-offline-installer-v2.15.5.tgz
test ! -e harbor || { echo "harbor 目录已存在,请先检查已有安装,不重复解压覆盖"; exit 1; }
tar -xzf harbor-offline-installer-v2.15.5.tgz
cd harbor
printf '输入此 Linux 主机的 IP 或域名,不带协议和端口: '
read -r HARBOR_HOST
export HARBOR_HOST
python3 - <<'PYCONFIG'
import os,re,secrets
from pathlib import Path
host=os.environ['HARBOR_HOST']
assert re.fullmatch(r'[A-Za-z0-9.-]+',host), '主机名格式不正确'
p=Path('harbor.yml')
assert not p.exists(), '已有 harbor.yml,请先备份和比较'
t=Path('harbor.yml.tmpl').read_text()
t=re.sub(r'^hostname:.*$', 'hostname: '+host,t,flags=re.M)
t=re.sub(r'^https:\n.*?(?=^[A-Za-z_])','',t,flags=re.M|re.S)
t=re.sub(r'(^http:\n(?:[ \t]+#.*\n)*[ \t]+port:)[ \t]*80',r'\1 8088',t,flags=re.M)
t=re.sub(r'^harbor_admin_password:.*$','harbor_admin_password: '+secrets.token_hex(20),t,flags=re.M)
t=re.sub(r'(^database:\n(?:.*\n)*?\s+password:).*',lambda m:m[1]+' '+secrets.token_hex(24),t,count=1,flags=re.M)
t=re.sub(r'^data_volume:.*$','data_volume: /opt/harbor/data',t,flags=re.M)
p.write_text(t);p.chmod(0o600)
PYCONFIG
./install.sh
docker compose ps
docker compose logs --tail=100
2. 第一次使用
浏览器打开 http://Linux主机IP:8088,账号 admin,随机密码在私有 harbor.yml 的 harbor_admin_password 项。先创建一个私有测试项目,配置机器人账号,再进行登录、推送和拉取测试。这里的 HTTP 起步方案需要 Docker 客户端为该地址配置 insecure-registries;正式长期使用应配置自己的 HTTPS 证书,避免长期依赖明文仓库。
生成文件位于 /opt/harbor-installer/harbor,数据位于 /opt/harbor/data。以后在生成文件所在目录运行 docker compose config --quiet、docker compose stop 和 docker compose start。升级必须使用对应版本的迁移步骤并先备份数据库、registry 数据、harbor.yml 和证书,不直接把跨版本镜像标签全部改成 latest。
常见问题
- 命令不存在:确认依赖已安装,关闭并重新打开终端,再检查实际使用的环境。Python 虚拟环境与系统 Python、Windows 与 WSL 的工具路径各自独立。
- 下载依赖失败:先查看具体失败的仓库和包名,检查该终端的网络;浏览器能访问不代表命令行已使用同一代理。
- 配置后仍报错:从当前项目目录启动,检查配置文件名、变量名和日志。真实账号与 API Key 放在本机私有配置中,不复制到公开教程或截图。
更新与备份
更新前保存项目配置、输入资料和输出结果。源码项目记录当前提交与依赖锁文件,比较新版本说明后再更新;安装包项目保留可回退的版本号。服务账号的授权与模型账单在对应平台管理,删除本地目录不会自动撤销授权。