Harbor 镜像仓库所在机器磁盘满了核心是先清理无用镜像并执行垃圾回收释放空间若清理后仍不够可迁移数据到更大磁盘。以下是分步骤恢复方案适配不同 Harbor 版本和场景请先通读全文再执行操作优先通过 UI 清理无用镜像软删除这一步是标记要删除的镜像为后续物理删除做准备操作简单且不易出错。如果是 Harbor v2.4 及以上版本可通过保留策略批量清理旧版本则手动删除冗余镜像。新版本配置保留策略登录 Harbor 控制台进入目标项目点击 “策略”→“添加规则”。比如设置 “保留最近 30 天镜像”“删除无标签镜像” 等规则设置后点击 “模拟运行” 预览清理结果确认无误后 “立即执行”。旧版本手动删除直接进入项目下的镜像仓库删除冗余的旧版本镜像、重复标签镜像等无用镜像。执行垃圾回收释放物理空间关键步骤通过 UI 删除镜像只是软删除仅移除元数据引用底层数据块仍占用磁盘必须执行垃圾回收GC才能真正释放空间操作时需停止 Harbor 避免镜像损坏步骤如下进入 Harbor 安装目录通常为/usr/local/harbor停止 Harbor 服务cd /usr/local/harbor docker-compose stop先预览清理内容避免误删--dry-run 参数仅预览不删除数据docker run -it --name gc --rm --volumes-from registry vmware/registry-photon:v2.6.2-v1.5.0 garbage-collect --dry-run /etc/registry/config.yml确认预览结果无误后执行实际垃圾回收docker run -it --name gc --rm --volumes-from registry vmware/registry-photon:v2.6.2-v1.5.0 garbage-collect /etc/registry/config.yml重启 Harbor 服务docker-compose up -d验证空间是否释放可对比数据目录大小du -sh /data/registry/docker/registry/v2/blobs清理 Docker 冗余资源除了 Harbor 本身Docker 的无用容器、镜像、卷也可能占用大量空间可执行以下命令清理# 清理未被使用的镜像、容器、网络和卷谨慎使用会删除所有无用资源 docker system prune -a --volumes迁移数据到更大磁盘清理后仍不足时若清理后磁盘空间依旧紧张可将 Harbor 数据迁移到更大容量的磁盘步骤如下停止 Harbor 服务docker-compose down复制 Harbor 数据到新磁盘目录假设新目录为/home/harbor-datacp -a /data /home/harbor-data编辑 Harbor 配置文件harbor.yml修改data_volume为新路径data_volume: /home/harbor-data重新生成配置并启动 Harbor./prepare docker-compose up -d若执行垃圾回收时失败比如提示 “object is not found”可能是清理任务超时被终止可修改common/config/jobservice/config.yml中max_update_hours为 168延长至 7 天重启 Harbor 后重新执行 GC 即可如出现Unable to find image vmware/registry-photon:v2.6.2-v1.5.0 locally核心原因是指定的 Harbor registry 镜像版本与你实际安装的 Harbor 版本不匹配或本地无该镜像。以下是分场景的解决方法优先适配你的 Harbor 实际版本第一步确认你的 Harbor 对应的 registry 镜像版本不同 Harbor 版本依赖的registry-photon镜像版本不同先通过以下命令查看本地已有的 registry 镜像Harbor 启动后会自动拉取对应版本# 列出本地所有registry相关镜像 docker images | grep registry-photon示例输出不同版本数值不同vmware/registry-photon v2.8.3-v1.10.1 xxxxxxxx 2 months ago复制输出中的版本号如v2.8.3-v1.10.1替换后续 GC 命令中的版本号即可。第二步通用垃圾回收命令适配所有 Harbor 版本如果上述命令没找到镜像或不想手动匹配版本直接用 Harbor 安装目录下的docker-compose.yml自动匹配版本执行 GC这是最稳妥的方式# 进入Harbor安装目录默认/usr/local/harbor cd /usr/local/harbor # 1. 停止Harbor避免GC时读写冲突 docker-compose stop # 2. 预览清理内容--dry-run仅预览不删除 docker-compose run --rm registry garbage-collect --dry-run /etc/registry/config.yml # 3. 确认无误后执行实际GC删除--dry-run docker-compose run --rm registry garbage-collect /etc/registry/config.yml # 4. 重启Harbor docker-compose up -d✅ 核心优势无需手动指定镜像版本docker-compose run会自动使用 Harbor 配置文件中定义的 registry 镜像版本彻底避免版本不匹配问题。第三步手动拉取对应版本镜像备用方案如果docker-compose run提示镜像不存在可先手动拉取 Harbor 官方镜像需匹配你的 Harbor 版本# 示例拉取Harbor 2.5.x对应的版本根据实际版本替换 docker pull vmware/registry-photon:v2.7.1-v1.9.1 # 或直接拉取最新兼容版本Harbor 2.4通用 docker pull vmware/registry-photon:latest拉取完成后再执行第一步的 GC 命令即可。补充常见 Harbor 版本与 registry-photon 版本对应表Harbor 版本对应的 registry-photon 版本Harbor 2.0.xv2.6.2-v1.5.0你原命令中的版本Harbor 2.3.xv2.7.1-v1.8.0Harbor 2.5.xv2.7.1-v1.9.1Harbor 2.8.xv2.8.3-v1.10.1Harbor 2.10.xv2.10.1-v1.11.0运行时长参考registry garbage-collect没有固定时间取决于blob 文件总数、磁盘 IO 性能SSD / 机械盘、待删除垃圾数量、服务器 CPU 内存。区分--dry-run模拟 ≠ 真实 GC删除文件真实 GC 会更慢。参考经验区间停机执行你当前方式小规模存储 200G几千个 blobdry-run110 分钟 真实 GC530 分钟中规模200G1TB几万 blobdry-run1040 分钟 真实 GC30 分钟2 小时大规模1TB、十万级 blob、大量待删除层dry-run30 分钟2h 真实 GC28 小时甚至更久验证 GC 是否成功执行完 GC 后通过以下命令查看磁盘空间是否释放# 查看Harbor数据目录默认/data/registry的大小 du -sh /data/registry/docker/registry/v2/blobs # 查看磁盘整体使用情况 df -h
