在群晖 NAS 上部署 Harbor 镜像仓库（避坑全指南）

在普通的 Linux 服务器上部署 VMware Harbor 私有镜像仓库，通常只需要下载、改配置、执行安装脚本三步。但是，如果你想在群晖（Synology DSM）上部署 Harbor，由于群晖底层系统的特殊性，直接按官方文档操作绝对会踩到连环大坑，甚至可能导致你的群晖系统彻底崩溃（DSM 无法登录）！

本文将手把手带你在群晖上完美部署 Harbor，并解决跨服务器的数据迁移问题。

⚠️ 核心预警：群晖部署的致命陷阱

群晖的系统分区（根目录 /）通常只有 2GB 左右的空间。而 Harbor 默认会将所有的镜像数据存放在 /data，日志存放在 /var/log/harbor。
如果不加修改直接安装，你推几个镜像上去，群晖的系统盘就会瞬间被撑爆，导致整个 NAS 服务停摆！ 下面我们会教你如何避开这个大坑。

准备工作

在群晖的“套件中心”安装 Container Manager（老版本叫 Docker）。
在控制面板开启 SSH 功能，并使用终端（如 PuTTY、Xshell）以管理员账号连接群晖。
下载 Harbor 的离线安装包（Offline Installer）并解压到群晖的共享文件夹中，例如：/volume2/docker/harbor。

填坑第一步：解决 `tput: command not found` 报错

进入解压好的 harbor 目录，切换到 root 用户并执行安装脚本：

sudo -i
cd /volume2/docker/harbor
./install.sh

症状： 此时你会立刻看到满屏的报错 common.sh: line 13: tput: command not found。
原因： 群晖是精简版 Linux，没有安装用于控制终端字体颜色的 tput 命令。
解法： 写一个“假”的 tput 命令骗过脚本即可。执行以下命令：

echo -e '#!/bin/shnexit 0' > /usr/local/bin/tput
chmod +x /usr/local/bin/tput

填坑第二步：修改 `harbor.yml`（保卫系统盘与反代配置）

这是最关键的一步！复制一份配置文件：

cp harbor.yml.tmpl harbor.yml
vim harbor.yml

我们需要做以下 三处核心修改：

1. 拯救系统盘：修改数据和日志路径

找到 data_volume:（约 45 行），将其从默认的 /data 改到你的群晖硬盘上：

data_volume: /volume2/docker/harbor/data  # 路径请根据你的实际情况修改

往下翻，找到 log: 下面的 location:（约 90 行），将其从 /var/log/harbor 改掉：

log:
  level: info
  local:
    location: /volume2/docker/harbor/logs # 坚决不能放在 /var/log 下！

2. 反向代理架构设置（使用前置 Nginx）

如果你打算用外部的 Nginx（或群晖自带的反代）来处理 HTTPS，Harbor 内部只需要跑纯 HTTP 即可。
找到 https: 配置段，把这一整段（包括 port、certificate、private_key）全部用 # 注释掉。

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

3. 配置对外 URL（防止 Docker 客户端拉取失败）

找到 external_url:，取消注释，并填写你最终对外提供服务的真实 HTTPS 域名：

external_url: https://harbor.你的域名.com:你的端口

保存并退出 (:wq)。

填坑第三步：解决挂载目录不存在的报错

症状： 如果你现在执行安装脚本，会在 Step 4 报错：Bind mount failed: '/volume2/docker/harbor/common/config' does not exist.
原因： 在标准 Linux 下，Docker 挂载本地不存在的目录时会自动创建。但群晖的安全机制禁用了“自动创建挂载目录”的功能！
解法： 我们需要把 Harbor 用到的所有目录，提前手动创建出来：

mkdir -p /volume2/docker/harbor/common/config
mkdir -p /volume2/docker/harbor/data
mkdir -p /volume2/docker/harbor/logs
chmod -R 777 /volume2/docker/harbor/common

第四步：执行安装！

现在，所有的坑都已经填平，执行：

./install.sh

稍等片刻，看到 ✔ ----Harbor has been installed and started successfully.----，说明 Harbor 的容器已经全部成功启动！

填坑终极篇：解决反代登录 `CSRF token invalid` 报错

如果你迫不及待地用 Nginx 配置了反向代理，打开网页输入账号 admin 登录，你大概率会遇到提示密码错误，抓包一看报错是：
{"errors":[{"code":"FORBIDDEN","message":"CSRF token invalid"}]}

原因： 你的架构是 外网(HTTPS) -> Nginx -> 内网Harbor(HTTP)。Nginx 在转发时没有告诉 Harbor 前端用的是 HTTPS，Harbor 的安全机制判定协议不匹配，认为这是一次跨站伪造请求（CSRF）攻击，从而拒绝登录。

解法： 修改你前置 Nginx 的配置，务必加上以下代理头：

location / {
    proxy_pass http://群晖IP:Harbor的HTTP端口;
    
    # 核心：强制告诉 Harbor 前端使用的是 HTTPS协议
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # 常规头部
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    
    # 顺手解除上传文件大小限制，否则以后 docker push 大镜像会报 413 错误！
    client_max_body_size 0; 
}

注意： 改完 Nginx 重启后，务必清理浏览器缓存或使用无痕模式重新打开页面，因为之前失败的 Cookie 还在浏览器里！此时登录，完美进入后台！

💡 进阶彩蛋：如何把老 Harbor 的数据无缝迁移到新 Harbor？

部署完新 Harbor，如何把老服务器上的镜像和项目搬过来？千万别去底层拷数据，直接用 Harbor 自带的**“复制（Replication）”**功能，优雅搬家：

登录新 Harbor 网页后台。
左侧菜单前往 系统管理 -> 仓库管理 (Registries)，点击 新建目标。
- 提供者选 Harbor，填入老 Harbor 的 URL、账号、密码。
- （如果老 Harbor 是自签证书，记得取消勾选“验证远程证书”），测试连接并保存。
左侧菜单前往 系统管理 -> 复制管理 (Replications)，点击 新建规则。
- 复制模式选 Pull-based (从远端拉取)。
- 源资源选择刚才建好的老 Harbor。
- 资源过滤器留空（代表全量同步）。
- 触发模式选 Manual (手动)，勾选覆盖，保存。
选中建好的规则，点击上方的 执行 (Replicate)。

喝杯咖啡，新 Harbor 会自动把老 Harbor 里的项目名称、所有镜像和 Tag 全部原封不动地拉取过来（注意：账号权限不会同步，需重新创建分配）。因为我们的数据放在了群晖的大容量硬盘里，随意拉取，根本不用担心爆盘！

总结： 在群晖上跑 Docker 服务，一定要时刻留意“路径映射”和“权限/网络限制”。搞定了这套流程，你的群晖就拥有了一个企业级的私有镜像仓库，尽情折腾吧！