Harbor Docker Compose 部署指南

‍‍‌> 目标：以 Harbor 官方安装器生成的 docker-compose.yml 为基础，讲解如何用 Docker Compose 手动编排部署 Harbor 2.15.4 的 9 个平台服务组件（log/registry/registryctl/postgresql/core/portal/jobservice/redis/proxy），覆盖配置生成、数据持久化、常用环境变量、常用运维命令与等价部署方式。本文已在 Ubuntu 22.04 真实环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
系统架构：x86_64
Docker 版本：Docker Engine 29.8.1（含 Compose v2 插件 v5.5.1）
存储驱动：vfs（本机实测；常规服务器多使用 overlay2）
Harbor 版本：2.15.4（组件镜像 goharbor/*:v2.15.4、goharbor/valkey-photon:v2.15.4）
服务编排文件：/opt/harbor-installer/harbor/docker-compose.yml（由 ./prepare 从 harbor.yml 生成）
数据目录：/opt/data/harbor（组件数据、数据库、制品均落盘于此）
端口映射：宿主 80:8080、443:8443（proxy 对外入口）
管理账号：admin ／密码 q1w2e3r4
服务器地址：172.17.0.63（示例内网 IP，请替换为实际地址）

二、镜像选型说明

服务组件	镜像	作用
`log`	`goharbor/harbor-log:v2.15.4`	集中日志（rsyslog + logrotate）
`registry`	`goharbor/registry-photon:v2.15.4`	制品对象存储（registry 核心）
`registryctl`	`goharbor/harbor-registryctl:v2.15.4`	registry 控制台/GC
`postgresql`	`goharbor/harbor-db:v2.15.4`	元数据数据库（PostgreSQL）
`core`	`goharbor/harbor-core:v2.15.4`	核心业务 API
`portal`	`goharbor/harbor-portal:v2.15.4`	Web 控制台前端
`jobservice`	`goharbor/harbor-jobservice:v2.15.4`	异步任务（扫描/复制/GC）
`redis`	`goharbor/valkey-photon:v2.15.4`	缓存与队列（Valkey）
`proxy`	`goharbor/nginx-photon:v2.15.4`	反向代理与 TLS 终结（对外入口）

💡 说明：镜像仓库为 docker.io/goharbor/*。离线部署时这些镜像已打包在离线安装器的 harbor.v2.15.4.tar.gz，由 docker load 本地加载；在线部署则在 up -d 时从仓库拉取。

三、前置条件

已安装 Docker Engine 与 Compose 插件：docker --version && docker compose version
已下载 Harbor 安装器并解压（离线版含镜像 tar）：/opt/harbor-installer/harbor
已规划数据目录 /opt/data/harbor（放独立数据盘更佳）
已生成自签 HTTPS 证书到 /opt/data/harbor（server.crt / server.key / ca.crt，见《Ubuntu 22.04 安装 Harbor 指南》4.4）

四、部署步骤

4.1 编写 harbor.yml 并生成 compose 配置

手动编排的第一步是让官方配置生成器 prepare 依据 harbor.yml 产出整套 docker-compose.yml 与各组件运行配置（common/config/）：

mkdir -p /opt/data/harbor
cd /opt/harbor-installer/harbor
cp harbor.yml.tmpl harbor.yml
sed -i \
  -e "s|^hostname: .*|hostname: 172.17.0.63|" \
  -e "s|^  certificate: .*|  certificate: /opt/data/harbor/server.crt|" \
  -e "s|^  private_key: .*|  private_key: /opt/data/harbor/server.key|" \
  -e "s|^harbor_admin_password: .*|harbor_admin_password: q1w2e3r4|" \
  -e "s|^data_volume: .*|data_volume: /opt/data/harbor|" \
  harbor.yml
export TERM=xterm
./prepare

实测输出：

prepare base dir is set to /opt/harbor-installer/harbor

生成结果确认（实测）：

ls common/config/
docker compose config --services

实测输出：

core     db       jobservice   log     nginx   portal   registry   registryctl   shared
log
registry
registryctl
postgresql
core
portal
jobservice
redis
proxy

💡 说明：./prepare 会清空重建 common/config/，把 harbor.yml 的 hostname/证书/数据库/数据卷等参数散化到各组件配置（core/db/registry/nginx 等）。docker compose config --services 列出 9 个服务组件（service 名：log/registry/registryctl/postgresql/core/portal/jobservice/redis/proxy）。

4.2 docker-compose.yml 结构总览

由 prepare 生成的 /opt/harbor-installer/harbor/docker-compose.yml 是 Harbor 编排的骨架。其服务层级如下（节选关键配置，完整文件由 prepare 生成）：

services:
  log:            # 日志聚合
    image: goharbor/harbor-log:v2.15.4
    container_name: harbor-log
    restart: always
    ports:
      - 127.0.0.1:1514:10514
    networks: [harbor]
  registry:       # 制品存储
    image: goharbor/registry-photon:v2.15.4
    container_name: registry
    restart: always
    volumes:
      - /opt/data/harbor/registry:/storage:z
    networks: [harbor]
    depends_on: [log]
  registryctl:
    image: goharbor/harbor-registryctl:v2.15.4
    container_name: registryctl
    restart: always
    env_file: [./common/config/registryctl/env]
    networks: [harbor]
    depends_on: [log]
  postgresql:     # 元数据数据库
    image: goharbor/harbor-db:v2.15.4
    container_name: harbor-db
    restart: always
    volumes:
      - /opt/data/harbor/database:/var/lib/postgresql/data:z
    shm_size: '1gb'
    networks: [harbor]
    depends_on: [log]
  core:           # 核心 API
    image: goharbor/harbor-core:v2.15.4
    container_name: harbor-core
    restart: always
    env_file: [./common/config/core/env]
    volumes:
      - /opt/data/harbor/:/data/:z
    networks: [harbor]
    depends_on: [log, registry, redis, postgresql]
  portal:         # Web 控制台
    image: goharbor/harbor-portal:v2.15.4
    container_name: harbor-portal
    restart: always
    networks: [harbor]
  jobservice:     # 异步任务
    image: goharbor/harbor-jobservice:v2.15.4
    container_name: harbor-jobservice
    restart: always
    env_file: [./common/config/jobservice/env]
    volumes:
      - /opt/data/harbor/job_logs:/var/log/jobs:z
    networks: [harbor]
    depends_on: [core]
  redis:          # 缓存队列
    image: goharbor/valkey-photon:v2.15.4
    container_name: redis
    restart: always
    volumes:
      - /opt/data/harbor/redis:/var/lib/redis
    networks: [harbor]
  proxy:          # 反向代理 + TLS 终结（对外入口）
    image: goharbor/nginx-photon:v2.15.4
    container_name: nginx
    restart: always
    ports:
      - 80:8080
      - 443:8443
    networks: [harbor]
    depends_on: [registry, core, portal, log]
networks:
  harbor:
    external: false

⚠️ 注意：此 docker-compose.yml 由 ./prepare 严格按 harbor.yml 生成，不建议手工改动；若要调整组件参数，应改 harbor.yml 后重新 ./prepare（会重建 compose 文件与 common/config/）。

4.3 启动全部组件

cd /opt/harbor-installer/harbor
docker compose up -d

实测输出（节选）：

Network harbor_harbor Creating
Network harbor_harbor Created
Container harbor-log Creating
Container registryctl Creating
Container redis Creating
Container harbor-portal Creating
Container harbor-db Creating
Container registry Creating
Container nginx Creating
Container harbor-jobservice Creating
Container harbor-core Creating
Container harbor-log Creating ... Started
Container harbor-portal Starting ... Started
Container redis Starting ... Started
Container registry Starting ... Started
Container registryctl Starting ... Started
Container harbor-db Starting ... Started
Container harbor-jobservice Starting ... Started
Container nginx Starting ... Started

4.4 验证组件健康状态

docker compose ps

实测输出：

NAME                SERVICE        STATUS
harbor-core         core           Up 55 seconds (healthy)
harbor-db           postgresql     Up 55 seconds (healthy)
harbor-jobservice   jobservice     Up 55 seconds (healthy)
harbor-log          log            Up 55 seconds (healthy)
harbor-portal       portal         Up 55 seconds (healthy)
nginx               proxy          Up 55 seconds (healthy)
redis               redis          Up 55 seconds (healthy)
registry            registry       Up 55 seconds (healthy)
registryctl         registryctl    Up 55 seconds (healthy)

curl 探活（实测）：

curl -k -s -o /dev/null -w "https=%{http_code}\n" https://localhost/api/v2.0/ping
curl -k -s https://localhost/api/v2.0/ping; echo
curl -k -s -u admin:q1w2e3r4 https://localhost/api/v2.0/health; echo

实测输出：

https=200
Pong
{"components":[{"name":"core","status":"healthy"},{"name":"database","status":"healthy"},{"name":"jobservice","status":"healthy"},{"name":"portal","status":"healthy"},{"name":"redis","status":"healthy"},{"name":"registry","status":"healthy"},{"name":"registryctl","status":"healthy"}],"status":"healthy"}

💡 说明：/api/v2.0/ping 返回 Pong、/api/v2.0/health 返回 7 个组件全部 healthy，即手动编排部署成功。

五、数据持久化说明（重点）

9 个平台服务组件的数据统一落在 /opt/data/harbor（bind 挂载），目录划分如下：

宿主机目录	挂载到组件	内容
`/opt/data/harbor/database`	postgresql `/var/lib/postgresql/data`	PostgreSQL 元数据
`/opt/data/harbor/registry`	registry `/storage`	制品（镜像层）对象存储
`/opt/data/harbor/job_logs`	jobservice `/var/log/jobs`	异步任务日志
`/opt/data/harbor/redis`	redis `/var/lib/redis`	缓存 / 队列数据
`/opt/data/harbor/ca_download`	core `/etc/core/ca`	供下载的 CA 证书
`/opt/data/harbor/secret/*`	core/registry/proxy	私钥、secret 等敏感配置

docker compose restart / up -d / down 均不会删除 /opt/data/harbor 数据（bind 挂载）。
只有 docker compose down -v 才移除 Compose 的命名卷；bind 挂载的 /opt/data/harbor 需显式 rm -rf。
备份：对 /opt/data/harbor 做快照 / rsync 即可完成全量数据备份。

⚠️ 注意：数据目录属主、:z/:z 挂载标记与 SELinux 上下文相关；常规无 SELinux 环境可忽略 :z。

六、常用环境变量表

各核心组件的环境变量由 ./prepare 写入 common/config/<svc>/env，关键变量如下：

组件	变量	说明
core	`CORE_SECRET`	core 内部通信密钥（首次 prepare 自动生成）
core	`POSTGRESQL_HOST`	数据库地址（默认内部 postgresql）
core	`POSTGRESQL_PORT`	数据库端口（默认 5432）
core	`POSTGRESQL_USERNAME` / `_PASSWORD`	数据库账号 / 密码
core	`REGISTRY_URL`	内部 registry 地址
core	`JOB_SERVICE_URL`	内部 jobservice 地址
core	`REDIS_URL`	Redis / Valkey 连接串
core	`CORE_URL`	core 自身对外地址（对应 hostname）
registryctl	`CORE_SECRET`	与 core 一致
jobservice	`CORE_SECRET`	与 core 一致
jobservice	`REDIS_URL`	任务队列 Redis
proxy	（由 nginx.conf 读取）	证书路径 / 端口来自 harbor.yml

💡 说明：这些 env 文件在 ./prepare 时按 harbor.yml 生成。若要注入自定义环境变量（如代理、日志级别），应在 harbor.yml 对应段配置后重新 ./prepare，或在宿主机 export 全局变量让 prepare 读取。

七、常用配置参数说明（各组件 command / 挂载）

docker-compose.yml 中每个组件的启动命令与配置挂载均由 prepare 固定，示例：

log：挂载 common/config/log/logrotate.conf、rsyslog_docker.conf 到 /etc/...，端口 127.0.0.1:1514:10514 收集中间件 rsyslog。
registry：挂载 common/config/registry/ 到 /etc/registry/，并挂载 /opt/data/harbor/secret/registry/root.crt 供 TLS。
postgresql：设置 shm_size: '1gb'，通过 env_file: ./common/config/db/env 注入库名/密码。
proxy：挂载 common/config/nginx 到 /etc/nginx，/opt/data/harbor/secret/cert 到 /etc/cert（TLS 证书），映射 80:8080、443:8443。

所有组件都声明 cap_drop: - ALL 并最小化 cap_add（如 CHOWN、SETGID、SETUID、NET_BIND_SERVICE），采用最小权限原则。

八、配置文件持久化（挂载说明）

各组件运行配置位于 ./common/config/<svc>/（由 prepare 生成），通过 bind 挂载进组件：
- core：common/config/core/app.conf
- registry/registryctl：common/config/registry/
- jobservice：common/config/jobservice/config.yml
- proxy：common/config/nginx
- portal：common/config/portal/nginx.conf
这些配置在 prepare 每次执行时都会按 harbor.yml 重新生成，如需保留自定义，请写在 harbor.yml 中，避免直接改 common/config/。

九、等价 docker run 运行方式

若不用 Compose，可用 docker run 逐个启动（繁琐且需先建 Harbor 网络并处理好依赖顺序），此处以最外层 nginx（proxy）为例说明等价性：

docker network create harbor
docker run -d --name nginx --network harbor \
  --restart always \
  -v /opt/harbor-installer/harbor/common/config/nginx:/etc/nginx:z \
  -v /opt/data/harbor/secret/cert:/etc/cert:z \
  -p 80:8080 -p 443:8443 \
  --cap-drop ALL --cap-add CHOWN --cap-add SETGID --cap-add SETUID --cap-add NET_BIND_SERVICE \
  goharbor/nginx-photon:v2.15.4

参数对照：

Compose 写法	docker run 写法
`container_name: nginx`	`--name nginx`
`restart: always`	`--restart always`
`volumes: ./common/config/nginx:/etc/nginx`	`-v 目录:目录`
`ports: 80:8080, 443:8443`	`-p 80:8080 -p 443:8443`
`cap_drop/cap_add`	`--cap-drop ALL --cap-add ...`
`networks: harbor`	`--network harbor`

⚠️ 注意：手动 docker run 需要严格保证组件启动顺序（core 依赖 registry/redis/db，proxy 依赖 registry/core/portal/log）并共享统一的 harbor 网络与 secret，极易出错，生产强烈建议使用 prepare + docker compose 一键编排，而非逐条 docker run。

十、常用运维命令

cd /opt/harbor-installer/harbor

# 查看全部组件状态
docker compose ps

# 查看某一组件日志
docker logs -f harbor-core

# 重启全部组件（数据保留）
docker compose restart

# 停止全部组件
docker compose stop

# 停止并移除组件、网络与命名卷
docker compose down

# 停止并移除组件 + 命名卷（bind 挂载数据仍在）
docker compose down -v

# 重新生成配置后拉起（改过 harbor.yml 时使用）
./prepare && docker compose up -d

十一、常见问题（FAQ）

11.1 Docker 存储驱动导致组件反复 `Restarting`？

常见于 overlay 驱动在受限文件系统上运行（.wh whiteout 无法写入）。查看单组件日志确认为 whiteout 报错后，改 /etc/docker/daemon.json 为 "storage-driver": "vfs" 并重启 dockerd，再 ./compose up -d。

11.2 修改 harbor.yml 后 `up -d` 不生效？

harbor.yml 的改动必须经 ./prepare 重新生成 docker-compose.yml 与 common/config/，再 docker compose up -d 才生效；直接改 compose 文件不可取。

11.3 80/443 端口被占用？

确认宿主机的 80/443 未被其他服务占用，或调整 harbor.yml 的 http.port / https.port（会同步到 proxy 的端口映射）后重新 prepare。

11.4 组件日志里出现 `syslog` 循环（`tag: log`）？

Harbor 各组件统一把日志发给 log 组件（127.0.0.1:1514）聚合，属正常设计；查看整体日志用 docker logs -f harbor-log 而非逐个组件。

11.5 `docker compose ps` 显示 `(health: starting)` 不转 healthy？

属正常现象：个别组件（如 jobservice）首次启动健康检查需要数秒至数十秒，稍候 ps 即转 healthy。长期不 healthy 才需查日志。

十二、参考链接

本文档由 www.quzuo.net 平台开发

Harbor Docker Compose 部署指南

Harbor Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 编写 harbor.yml 并生成 compose 配置

4.2 docker-compose.yml 结构总览

4.3 启动全部组件

4.4 验证组件健康状态

五、数据持久化说明（重点）

六、常用环境变量表

七、常用配置参数说明（各组件 command / 挂载）

八、配置文件持久化（挂载说明）

九、等价 docker run 运行方式

十、常用运维命令

十一、常见问题（FAQ）

11.1 Docker 存储驱动导致组件反复 Restarting？

11.2 修改 harbor.yml 后 up -d 不生效？

11.3 80/443 端口被占用？

11.4 组件日志里出现 syslog 循环（tag: log）？

11.5 docker compose ps 显示 (health: starting) 不转 healthy？

十二、参考链接

11.1 Docker 存储驱动导致组件反复 `Restarting`？

11.2 修改 harbor.yml 后 `up -d` 不生效？

11.4 组件日志里出现 `syslog` 循环（`tag: log`）？

11.5 `docker compose ps` 显示 `(health: starting)` 不转 healthy？