Harbor 是一个企业级镜像仓库，不只是一个 registry 容器。它包含 Portal、Core、Registry、Jobservice、PostgreSQL、Redis、Nginx、日志服务，以及可选的 Trivy 漏洞扫描服务。

所以先说结论：

Harbor 不适合用一条 docker run 完整部署。
官方单机部署方式是 Docker Compose。
如果只需要单容器 registry，可以用 registry:2，但那不是 Harbor。

Harbor 官方文档也把单机部署方式写成 Docker Compose，把 Kubernetes 部署方式写成 Helm。本文记录在一台 Linux 主机上部署 Harbor 的流程，重点使用官方安装包生成的 Docker Compose 文件。

官方文档入口：

版本说明

本文固定使用 Harbor：

v2.14.4

不要使用 latest 这种浮动标签。Harbor 是多组件系统，升级涉及数据库、配置模板、镜像版本和迁移逻辑，不能只靠重新拉镜像解决。

如果官方 release 页面已经有更新版本，可以把下面命令里的 HARBOR_VERSION 替换成目标版本。升级生产环境前要先看对应版本的 release notes 和 upgrade 文档。

部署规划

本文假设部署在一台 Linux 主机上：

Harbor 域名: harbor.example.com
安装目录:   /opt/harbor-installer
数据目录:   /data/harbor
HTTP 端口:  80
HTTPS 端口: 443

把 harbor.example.com 替换成自己的域名或内网 DNS 名称。不要把 hostname 写成 localhost、127.0.0.1 或 0.0.0.0，否则其他 Docker 客户端无法按正常 registry 地址访问。

资源建议按官方最低要求起步：

CPU:    最低 2 Core，推荐 4 Core+
Memory: 最低 4GB，推荐 8GB+
Disk:   最低 40GB，推荐 160GB+

如果要长期保存构建镜像，磁盘要按镜像数量、标签数量和清理策略单独规划。

前置条件

主机需要先安装：

Docker Engine
Docker Compose Plugin
OpenSSL
curl
tar

验证版本：

docker version
docker compose version
openssl version

如果 Docker 还没装，可以先参考本站的 Docker 入门：Ubuntu 安装与基础配置。

docker run 方式的边界

Harbor 不能像下面这样部署：

docker run -d --name harbor -p 80:80 goharbor/harbor:latest

原因很简单：Harbor 没有这样一个官方单体镜像。完整 Harbor 需要多个容器、共享配置、内部证书、数据库、Redis、Nginx 反向代理、任务服务和 registry 存储目录。手工把这些组件全部翻译成一堆 docker run 命令，不但容易漏配置，也不利于后续升级和迁移。

如果只是想临时跑一个最简单的 Docker Registry，可以用下面的命令，但它不是 Harbor，没有 Harbor 的 Web UI、项目权限、审计、复制、漏洞扫描等功能：

docker run -d \
  --name registry \
  --restart unless-stopped \
  -p 5000:5000 \
  -v /opt/registry/data:/var/lib/registry \
  registry:2.8.3

验证普通 registry：

docker pull busybox:1.36.1
docker tag busybox:1.36.1 localhost:5000/library/busybox:1.36.1
docker push localhost:5000/library/busybox:1.36.1

如果目标是 Harbor，继续使用下面的 Docker Compose 方式。

Docker Compose 部署 Harbor

创建目录：

sudo mkdir -p /opt/harbor-installer /data/harbor
sudo chown -R "$USER:$USER" /opt/harbor-installer /data/harbor
cd /opt/harbor-installer

下载固定版本的在线安装包：

export HARBOR_VERSION=v2.14.4

curl -L -o harbor-online-installer-${HARBOR_VERSION}.tgz \
  https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz

tar xzf harbor-online-installer-${HARBOR_VERSION}.tgz --strip-components=1

在线安装包体积小，安装时会从镜像仓库拉取 Harbor 组件镜像。如果部署机器不能访问外网，改用同版本的 harbor-offline-installer-${HARBOR_VERSION}.tgz。

复制配置文件：

cp harbor.yml.tmpl harbor.yml

编辑配置：

vim harbor.yml

内网测试环境可以先使用 HTTP，核心配置类似下面这样：

hostname: harbor.example.com

http:
  port: 80

# https:
#   port: 443
#   certificate: /your/certificate/path
#   private_key: /your/private/key/path

harbor_admin_password: change-me-to-a-strong-admin-password

database:
  password: change-me-to-a-strong-db-password

data_volume: /data/harbor

注意事项：

  • harbor_admin_password 只在第一次初始化时生效，后续要在 Web 页面里修改管理员密码。
  • database.password 不要使用默认值，生产环境必须改成强密码。
  • data_volume 是 Harbor 数据目录，删除这里会丢失镜像、数据库和任务数据。
  • HTTP 只适合内网测试或隔离环境，生产环境应该启用 HTTPS。

如果要启用 HTTPS，把 https 配置取消注释，并填入证书和私钥路径：

hostname: harbor.example.com

https:
  port: 443
  certificate: /opt/harbor-installer/certs/harbor.example.com.crt
  private_key: /opt/harbor-installer/certs/harbor.example.com.key

证书可以来自可信 CA，也可以是自签证书。自签证书需要额外分发到所有 Docker 客户端，否则 docker login、docker push 会因为证书不受信任失败。

安装并启动 Harbor：

cd /opt/harbor-installer
sudo ./install.sh --with-trivy

如果暂时不需要漏洞扫描，可以不带 Trivy：

sudo ./install.sh

安装脚本会根据 harbor.yml 生成 docker-compose.yml 和组件配置，然后用 Docker Compose 启动 Harbor。

查看容器状态：

cd /opt/harbor-installer
docker compose ps

查看日志：

docker compose logs -f

正常情况下可以看到类似这些容器：

nginx
harbor-core
harbor-portal
harbor-jobservice
harbor-db
redis
registry
registryctl
harbor-log
trivy-adapter

在 QNAP NAS 中安装 Harbor

QNAP NAS 上可以通过 Container Station 运行 Docker 和 Docker Compose 应用，但 Harbor 不是普通的单个 Compose YAML 就能手工写完的应用。它需要先执行官方安装包里的 install.sh 或 prepare，生成 docker-compose.yml、common/config 和各组件配置。

所以在 QNAP 上推荐这条路线：

1. 在 QTS / QuTS hero 的 App Center 安装 Container Station
2. 开启 SSH
3. 通过 SSH 登录 NAS
4. 在 NAS 上运行 Harbor 官方安装包
5. 用 Container Station 查看容器状态和日志

不要直接在 Container Station 的“创建应用程序”里粘贴网上随便找的 Harbor Compose。Harbor 官方生成的 docker-compose.yml 会引用安装目录下的相对路径，例如 ./common/config/...。如果只复制 YAML，不复制同一目录下的配置文件，容器大概率启动失败。

QNAP 前置检查

先确认 NAS 型号和资源。Harbor 更适合 x86_64 的 QNAP NAS，例如 Intel 或 AMD CPU 机型。很多 ARM NAS 不适合直接跑 Harbor，容易遇到镜像架构不匹配、性能不足或组件镜像不可用的问题。

通过 SSH 登录 QNAP 后检查架构：

uname -m

常见结果：

x86_64   适合继续部署
aarch64  ARM64，先不要按本文直接部署 Harbor
armv7l   ARM 32 位，不建议部署 Harbor

检查内存和磁盘：

free -h
df -h

建议至少：

CPU:    2 Core 起步，推荐 4 Core+
Memory: 4GB 起步，推荐 8GB+
Disk:   单独预留 160GB+ 更稳妥

如果 NAS 还运行 Plex、虚拟机、数据库、下载器等服务，建议给 Harbor 留出更高余量。

安装 Container Station

在 QNAP Web 管理页面操作：

1. 打开 App Center
2. 搜索 Container Station
3. 安装并启动 Container Station

Container Station 3 支持用 Docker Compose 创建多容器应用。Harbor 虽然最终也是 Compose 应用，但它需要官方安装脚本生成配置，所以本文不走纯 GUI 创建方式。

开启 SSH

在 QNAP Web 管理页面打开：

控制台与管理工具 -> Telnet / SSH -> 允许 SSH 连接

不同 QTS / QuTS hero 版本菜单名称可能略有差异。开启后从电脑连接 NAS：

ssh admin@<NAS_IP>

把 <NAS_IP> 替换成 NAS 的内网地址。

准备 QNAP 数据目录

QNAP 的数据卷路径可能是 /share/CACHEDEV1_DATA、/share/CACHEDEV2_DATA 或其他名称。可以先查看默认存储池挂载点：

getcfg SHARE_DEF defVolMP -f /etc/config/def_share.info

假设输出是：

/share/CACHEDEV1_DATA

创建 Harbor 目录：

export NAS_DATA_ROOT=/share/CACHEDEV2_DATA
mkdir -p ${NAS_DATA_ROOT}/DockerDatas/harbor/harbor-installer
mkdir -p ${NAS_DATA_ROOT}/DockerDatas/harbor/harbor-data
cd ${NAS_DATA_ROOT}/DockerDatas/harbor/harbor-installer

这里分成两个目录：

harbor-installer  放 Harbor 安装包、harbor.yml、docker-compose.yml 和 common/config
harbor-data       放 Harbor 数据，包括 registry、数据库、任务数据等

下载 Harbor 安装包

使用和前文一致的固定版本：

export HARBOR_VERSION=v2.14.4

curl -L -o harbor-online-installer-${HARBOR_VERSION}.tgz \
  https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz

tar xzf harbor-online-installer-${HARBOR_VERSION}.tgz --strip-components=1

如果 NAS 访问 GitHub 很慢，可以先在电脑下载同版本安装包，再通过 File Station、SCP 或 SMB 上传到 ${NAS_DATA_ROOT}/DockerDatas/harbor/harbor-installer。

让 SSH 识别 Docker 命令

QNAP 上经常会遇到这种情况：Container Station 已经安装，Web 页面里也能创建容器，但 SSH 登录后执行 Harbor 安装脚本却提示：

Need to install docker(20.10.10+) first and run this script again.

同时前面可能还有几行：

tput: command not found

tput 只是 Harbor 安装脚本用来输出彩色文字的命令，缺失时一般只影响显示。真正导致安装中断的是 SSH 环境找不到 docker 命令。

先检查当前 SSH 环境：

which docker
docker version

如果没有输出，查找 Container Station 自带的 Docker：

find /share -name docker -type f 2>/dev/null | grep -Ei 'container.*station|/\.qpkg/'
find /share -name docker-compose -type f 2>/dev/null | grep -Ei 'container.*station|/\.qpkg/'

常见路径类似：

/share/CACHEDEV2_DATA/.qpkg/container-station/bin/docker
/share/CACHEDEV2_DATA/.qpkg/container-station/bin/docker-compose

把这个目录临时加入 PATH：

export PATH=export PATH=/share/CACHEDEV1_DATA/.qpkg/container-station/usr/bin:$PATH

再次验证：

docker version
docker compose version

如果 docker compose version 不可用，但 docker-compose version 可用，说明这台 QNAP 提供的是老的 Compose 命令。Harbor 新版本更推荐 docker compose，如果安装脚本仍然识别失败，可以先升级 Container Station，或者用后面生成好的 docker-compose.yml 通过 docker-compose 管理。

确认路径没问题后，可以写入当前用户的 shell 配置，避免下次 SSH 登录又找不到 Docker：

echo 'export PATH=/share/CACHEDEV1_DATA/.qpkg/container-station/usr/bin:$PATH' >> ~/.profile
source ~/.profile

如果你的 Docker 实际路径不是 CACHEDEV2_DATA，要按 find 命令查到的结果修改上面的路径。

配置 harbor.yml

复制模板：

cp harbor.yml.tmpl harbor.yml

编辑：

vi harbor.yml

QNAP 内网测试可以先用 HTTP，并避免占用 QNAP 管理页面常用端口。示例：

hostname: harbor-nas.example.com

http:
  port: 8088

# https:
#   port: 8443
#   certificate: /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer/certs/harbor-nas.example.com.crt
#   private_key: /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer/certs/harbor-nas.example.com.key

harbor_admin_password: change-me-to-a-strong-admin-password

database:
  password: change-me-to-a-strong-db-password

data_volume: /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-data

几个要点：

  • hostname 建议写 NAS 的内网域名，例如 harbor-nas.example.com，并在 DNS 或客户端 hosts 中解析到 NAS IP。
  • 如果没有域名，也可以写 NAS IP，但后续换 IP 会比较麻烦。
  • http.port 不建议直接用 80，避免和 QNAP Web 服务冲突。
  • 如果启用 HTTPS，也不建议直接用 443，可以先用 8443，再按实际网络环境决定是否反向代理。
  • data_volume 必须写 QNAP 上真实存在的绝对路径。

如果执行安装时报错：

Error happened in config validation...
ERROR:root:Error: The protocol is https but attribute ssl_cert is not set

说明 Harbor 认为当前配置启用了 HTTPS，但没有找到证书配置。先检查 harbor.yml：

grep -nE '^(hostname|http:|https:|  port:|  certificate:|  private_key:)' harbor.yml

内网测试只用 HTTP 时，配置应该类似这样：

hostname: harbor-nas.example.com

http:
  port: 8088

# https:
#   port: 8443
#   certificate: /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer/certs/harbor-nas.example.com.crt
#   private_key: /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer/certs/harbor-nas.example.com.key

注意 hostname 只写域名或 IP，不要写成下面这样：

hostname: https://harbor-nas.example.com

如果确实要启用 HTTPS，就必须取消 https 小节注释，并填入真实存在的证书和私钥路径：

hostname: harbor-nas.example.com

https:
  port: 8443
  certificate: /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer/certs/harbor-nas.example.com.crt
  private_key: /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer/certs/harbor-nas.example.com.key

证书文件可以用下面命令确认：

ls -l /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer/certs/

没有证书时先不要启用 HTTPS，等 Harbor 能通过 HTTP 正常启动后，再补证书和 HTTPS 配置。

启动 Harbor

进入安装目录执行：

cd ${NAS_DATA_ROOT}/DockerDatas/harbor/harbor-installer
./install.sh --with-trivy

如果 NAS 内存只有 4GB，建议先不启用 Trivy：

./install.sh

启动完成后查看状态：

docker compose ps

如果 QNAP 的 Docker Compose 命令不可用，也可以试：

docker-compose ps

查看日志：

docker compose logs -f

或者在 Container Station 里打开应用和容器详情查看日志。通过 SSH 启动的容器通常也会显示在 Container Station 的容器列表中。

访问 Harbor

浏览器访问：

http://harbor-nas.example.com:8088

或直接使用 NAS IP：

http://<NAS_IP>:8088

默认用户名：

admin

密码是 harbor.yml 里的 harbor_admin_password。

使用 Nginx Proxy Manager 反代 Harbor

如果 Harbor 在 QNAP 上监听的是：

http://192.168.3.200:8088

想通过 Nginx Proxy Manager 访问：

https://harbor.jihw.top

先确认域名完全一致。比如 harbor.jihw.top 和 harbor.jiw.top 是两个不同域名，少一个字母就不会命中同一个代理规则。

Nginx Proxy Manager 代理服务建议这样配置：

Domain Names:    harbor.jihw.top
Scheme:          http
Forward Hostname/IP: 192.168.3.200
Forward Port:    8088
SSL:             Let's Encrypt
Force SSL:       开启
HTTP/2 Support:  可开启
Websockets Support: 可开启

然后检查 DNS 是否指向 Nginx Proxy Manager 所在机器，而不是指向 Harbor 所在的 QNAP：

nslookup harbor.jihw.top

如果 Nginx Proxy Manager 和 Harbor 都在内网，内网 DNS 或 hosts 应该让 harbor.jihw.top 解析到 Nginx Proxy Manager 的 IP。只有访问先到 Nginx Proxy Manager，它才有机会转发到 192.168.3.200:8088。

还要确认外部访问链路：

浏览器 -> https://harbor.jihw.top:443 -> Nginx Proxy Manager -> http://192.168.3.200:8088 -> Harbor

如果 Nginx Proxy Manager 本身不监听 443，或者路由器没有把 443 转发到 Nginx Proxy Manager，HTTPS 域名也会打不开。

如果 Nginx Proxy Manager 和 Harbor 都部署在同一台 QNAP NAS 上，要重点检查 NAS 宿主机的 80 和 443 端口。浏览器访问 https://harbor.jihw.top 时，默认会连到这台 NAS 的 443，只有这个端口被 Nginx Proxy Manager 监听，代理规则才会生效。

在 NAS SSH 中查看端口监听：

netstat -tlnp | grep -E ':(80|443|8088)\s'

如果系统支持 ss，也可以用：

ss -tlnp | grep -E ':(80|443|8088)\s'

再查看 Nginx Proxy Manager 容器端口映射：

docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep -Ei 'nginx|proxy|manager|npm'

正常情况下应该能看到类似：

0.0.0.0:80->80/tcp
0.0.0.0:443->443/tcp
0.0.0.0:81->81/tcp

如果只看到 81，没有 80 和 443，说明 Nginx Proxy Manager 只能打开管理页面，不能接收 HTTP/HTTPS 业务流量。需要回到 Container Station，把 Nginx Proxy Manager 容器的端口映射补上：

宿主机 80  -> 容器 80
宿主机 443 -> 容器 443
宿主机 81  -> 容器 81

如果 443 已经被 QNAP 管理页面或其他容器占用，Nginx Proxy Manager 就无法绑定宿主机 443。这时有三种处理方式：

1. 修改 QNAP 管理页面的 HTTPS 端口，让出 443 给 Nginx Proxy Manager
2. 停掉占用 443 的其他服务或容器
3. 把 Nginx Proxy Manager 映射到宿主机 8443，但访问时必须使用 https://harbor.jihw.top:8443

如果要使用标准地址 https://harbor.jihw.top，最终必须保证访问端能连到 Nginx Proxy Manager 的 443。

从任意客户端测试 443 是否通：

curl -vk https://harbor.jihw.top/

如果返回 Connection refused，一般是 NAS 的 443 没有服务在监听，或没有映射到 Nginx Proxy Manager。

如果返回超时，通常是 DNS 指错、路由不通、防火墙拦截，或者公网访问时路由器没有把 443 转发到 Nginx Proxy Manager。

如果能返回证书信息但页面不是 Harbor，说明请求到了别的服务，比如 QNAP 管理页面或另一条代理规则。

如果浏览器返回：

504 Gateway Time-out
openresty

这通常说明 443 已经能访问到 Nginx Proxy Manager，因为 OpenResty/Nginx 已经返回了错误页。问题不再是“443 没开”，而是 Nginx Proxy Manager 没有成功连到后端 Harbor。

先在 NAS 上确认 Harbor 宿主机端口可访问：

curl -I http://192.168.3.200:8088/

再找出 Nginx Proxy Manager 容器名：

docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep -Ei 'nginx|proxy|manager|npm'

从 Nginx Proxy Manager 容器内部访问 Harbor：

docker exec -it <npm容器名> sh -lc 'curl -I http://192.168.3.200:8088/ || wget -S -O- http://192.168.3.200:8088/'

把 <npm容器名> 替换成实际容器名。

如果 NAS 宿主机上能访问 http://192.168.3.200:8088/，但 Nginx Proxy Manager 容器里访问超时，说明是容器到宿主机 IP 的网络路径不通。可以在 Nginx Proxy Manager 的代理目标里尝试把后端地址改成 Docker 网关地址：

docker exec -it <npm容器名> sh -lc 'ip route | awk "/default/ {print \$3}"'

假设输出是：

172.17.0.1

则 Nginx Proxy Manager 代理服务可以改成：

Scheme: http
Forward Hostname/IP: 172.17.0.1
Forward Port: 8088

如果容器里能正常访问 http://192.168.3.200:8088/，但浏览器仍然是 504，继续检查 Nginx Proxy Manager 这条代理服务：

Domain Names 是否是 harbor.jihw.top
Scheme 是否是 http
Forward Hostname/IP 是否是 192.168.3.200
Forward Port 是否是 8088
是否误开了 Websocket 以外的特殊高级配置
SSL 证书是否绑定在这条代理服务上

然后查看 Nginx Proxy Manager 日志：

docker logs --tail=100 <npm容器名>

如果日志里是 upstream timed out，就是 Nginx Proxy Manager 连后端超时。如果是 connect() failed，通常是后端地址或端口不通。

如果 http://harbor.jihw.top:8088/ 能直接访问 Harbor，说明域名已经能解析到 NAS，Harbor 的 8088 端口也正常。此时 https://harbor.jihw.top 返回 504，通常还是 Nginx Proxy Manager 到后端的代理路径问题，不是 hostname 直接导致的。

不过 harbor.yml 里的 hostname 仍然要改成最终访问域名，因为它会影响 Harbor 页面里显示的仓库地址、镜像推送地址、Token 服务地址和部分跳转链接：

hostname: harbor.jihw.top

http:
  port: 8088

如果 Harbor 后面挂了 HTTPS 反向代理，而 Harbor 自己仍然只跑 HTTP，可以在 harbor.yml 里增加 external_url，让 Harbor 明确知道外部访问入口是 HTTPS：

hostname: harbor.jihw.top

http:
  port: 8088

external_url: https://harbor.jihw.top

external_url 要写完整 URL，包括 https://。hostname 仍然只写域名，不要带协议。

注意：一旦配置了：

external_url: https://harbor.jihw.top

就应该通过 https://harbor.jihw.top 登录 Harbor，不要再用 http://192.168.3.200:8088 或 http://harbor.jihw.top:8088 登录。否则浏览器里的 Cookie、Origin、CSRF Token 会和 Harbor 认为的外部地址不一致，可能出现：

FORBIDDEN
CSRF token invalid

如果 Nginx Proxy Manager 还没调通，需要继续用 8088 直连排查，就先不要配置 external_url，或者临时改成直连地址：

hostname: harbor.jihw.top

http:
  port: 8088

external_url: http://harbor.jihw.top:8088

等 https://harbor.jihw.top 反代确认可用后，再改回：

external_url: https://harbor.jihw.top

修改后重新生成配置并启动：

cd /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer
docker compose down
vi harbor.yml
./prepare
docker compose up -d

如果安装时启用了 Trivy，则使用：

./prepare --with-trivy
docker compose up -d

Harbor 后台的项目地址、镜像推送地址、重定向链接都会受 hostname 影响。反代后如果页面能打开但登录跳转、镜像推送或复制地址异常，优先检查这里。

如果 Nginx Proxy Manager 能打开页面但推送大镜像失败，可以在该代理服务的高级配置里增加：

client_max_body_size 0;
proxy_request_buffering off;

Docker 客户端配置

如果 QNAP Harbor 使用 HTTP，推送镜像的 Docker 客户端要配置 insecure registry：

{
  "insecure-registries": ["harbor-nas.example.com:8088"]
}

然后重启客户端机器上的 Docker：

sudo systemctl restart docker

登录验证：

docker login harbor-nas.example.com:8088
docker pull busybox:1.36.1
docker tag busybox:1.36.1 harbor-nas.example.com:8088/library/busybox:1.36.1
docker push harbor-nas.example.com:8088/library/busybox:1.36.1

注意：如果 Harbor 地址带端口，镜像标签里也必须带端口。

QNAP 上的维护命令

后续维护仍然建议通过 SSH 在安装目录里执行：

cd /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer
docker compose ps
docker compose logs -f
docker compose stop
docker compose start
docker compose restart

修改 harbor.yml 后重新生成配置：

cd /share/CACHEDEV2_DATA/DockerDatas/harbor/harbor-installer
docker compose down
vi harbor.yml
./prepare --with-trivy
docker compose up -d

没有启用 Trivy 时：

./prepare
docker compose up -d

QNAP 注意事项

在 NAS 上跑 Harbor 要特别注意这些点：

  • 不要把 Harbor 数据目录放到临时目录或系统分区，应该放到 QNAP 存储池里的共享目录。
  • 不要随手删除 ${NAS_DATA_ROOT}/DockerDatas/harbor/harbor-data，这里是镜像仓库和数据库数据。
  • 不要把 HTTP Harbor 直接暴露到公网，公网访问必须启用 HTTPS，并配合强密码、防火墙、反向代理或 VPN。
  • 如果 QNAP 自动休眠硬盘，Harbor 首次拉取或推送镜像时可能会变慢。
  • 如果 NAS 资源紧张，先不要启用 Trivy 扫描。
  • QNAP 系统升级、Container Station 升级前，建议先停止 Harbor 并备份 harbor.yml 和数据目录。

配置 Docker 客户端访问

浏览器打开：

http://harbor.example.com

默认管理员用户名：

admin

密码是 harbor.yml 里的 harbor_admin_password。第一次登录后建议马上修改密码。

如果 Harbor 使用 HTTP，Docker 客户端需要把它配置成 insecure registry。编辑客户端机器上的 Docker 配置：

sudo vim /etc/docker/daemon.json

示例：

{
  "insecure-registries": ["harbor.example.com"]
}

如果文件里已经有其他配置，不要直接覆盖，要把 insecure-registries 合并进去。

重启 Docker：

sudo systemctl restart docker

HTTPS 且证书可信时，不需要配置 insecure-registries。

推送镜像验证

先在 Harbor Web 页面创建一个项目，例如：

library

登录 Harbor：

docker login harbor.example.com

拉取一个固定版本测试镜像：

docker pull busybox:1.36.1

打标签：

docker tag busybox:1.36.1 harbor.example.com/library/busybox:1.36.1

推送：

docker push harbor.example.com/library/busybox:1.36.1

再从 Harbor 拉取验证：

docker rmi harbor.example.com/library/busybox:1.36.1
docker pull harbor.example.com/library/busybox:1.36.1

如果推送失败，优先检查：

docker compose ps
docker compose logs -f nginx
docker compose logs -f harbor-core
docker compose logs -f registry

常用维护命令

进入安装目录：

cd /opt/harbor-installer

停止 Harbor：

docker compose stop

启动 Harbor：

docker compose start

重启 Harbor：

docker compose restart

删除容器和网络，但保留数据：

docker compose down

重新创建并启动：

docker compose up -d

修改 harbor.yml 后，需要重新生成配置：

cd /opt/harbor-installer
docker compose down
vim harbor.yml
sudo ./prepare --with-trivy
docker compose up -d

如果没有安装 Trivy，则执行：

sudo ./prepare
docker compose up -d

备份和恢复注意事项

Harbor 的关键数据在：

/data/harbor
/opt/harbor-installer/harbor.yml

简单备份可以先停机，再打包数据目录和配置文件：

cd /opt/harbor-installer
docker compose stop

sudo tar czf /root/harbor-backup-$(date +%F).tgz \
  /data/harbor \
  /opt/harbor-installer/harbor.yml

docker compose start

这种方式会带来短暂停机。生产环境要结合数据库一致性、对象存储、镜像垃圾回收策略和定期恢复演练来设计备份方案。

恢复时要保证 Harbor 版本、harbor.yml、数据目录和证书路径一致。不要在没有备份的情况下直接删除 /data/harbor。

升级原则

升级前先备份：

cd /opt/harbor-installer
docker compose stop

然后阅读目标版本的官方 upgrade 文档和 release notes。Harbor 升级不是简单把镜像标签改成新版本，通常需要使用新版本安装包里的迁移和 prepare 流程。

建议原则：

1. 先备份 /data/harbor 和 harbor.yml
2. 阅读目标版本 release notes
3. 按官方支持的升级路径逐版本升级
4. 升级后验证登录、推送、拉取、扫描和项目权限

卸载 Harbor

只删除容器，保留镜像仓库数据：

cd /opt/harbor-installer
docker compose down

如果确认不再需要 Harbor，并且已经完成备份，再删除数据目录：

sudo rm -rf /data/harbor
sudo rm -rf /opt/harbor-installer

这一步会删除 Harbor 数据和安装配置，执行前一定要确认备份可用。

小结

Harbor 的正确打开方式不是手写一堆 docker run，而是使用官方安装包生成并管理 Docker Compose 配置。

docker run registry:2.8.3 适合临时测试普通镜像仓库；Harbor 适合需要 Web 管理、项目隔离、权限控制、审计、复制和漏洞扫描的场景。生产环境部署 Harbor 时，重点关注 HTTPS、管理员密码、数据目录、备份恢复和版本升级路径。