Harbor项目中GC成功但文件系统持续增长的问题分析

问题背景

在使用Harbor v2.11.1版本时，遇到了一个关于垃圾回收(GC)功能的异常现象：虽然GC任务能够成功执行并报告删除了无引用的blob和数据库条目，但实际检查文件系统时发现这些blob仍然存在，导致存储空间无法被有效释放。

问题现象

Harbor实例采用docker compose方式部署，数据直接存储在主机文件系统上。GC任务配置为每小时运行一次，并启用了"删除未标记的制品"选项。从日志中可以观察到以下关键现象：

1. GC日志显示blob和数据库条目被正确删除
2. 但文件系统中对应的blob文件仍然存在
3. registryctl服务日志中频繁出现"Path not found"错误
4. 文件系统存储路径不一致：registry服务挂载到/registry目录，而registryctl服务挂载到/data/registry目录

技术分析

根本原因

问题的核心在于Harbor的两个关键组件——registry和registryctl服务使用了不同的存储挂载路径。这种不一致导致：

1. GC任务通过registryctl服务尝试删除blob时，由于路径不匹配而失败
2. 虽然数据库记录被删除，但实际文件未被移除
3. 后续GC运行认为这些blob已被删除，不再处理

文件系统路径机制

Harbor的存储架构中：

• registry服务负责实际存储操作
• registryctl服务负责执行GC等管理任务
• 两者必须访问相同的物理存储路径才能协同工作

解决方案验证

通过统一两个服务的挂载路径后：

1. 确认两个服务现在可以访问相同的物理文件
2. 但之前标记为删除的blob未被新GC任务处理
3. 需要额外的清理机制来处理这些"孤儿"blob

深入技术细节

Harbor GC工作机制

Harbor的垃圾回收分为两个阶段：

1. 标记阶段：识别不再被任何manifest引用的blob
2. 删除阶段：实际移除这些blob文件

当路径不一致时，虽然标记阶段能完成，但删除阶段会失败。

存储路径配置

正确的配置要求：

• registry服务的storage.filesystem.rootdirectory必须与registryctl访问的路径一致
• 在docker compose中，volume挂载必须指向主机同一目录

解决方案

对于遇到此问题的用户，建议采取以下步骤：

1. 统一存储路径：确保registry和registryctl服务使用完全相同的volume挂载配置
2. 手动清理孤儿blob：对于已经标记但未删除的blob，可以考虑：
   • 停止Harbor服务
   • 手动比对数据库记录和实际文件
   • 谨慎删除无引用的blob文件
3. 验证GC功能：
   • 创建测试镜像并删除
   • 观察GC执行后文件是否被正确删除
4. 监控存储增长：建立定期检查机制，确认GC效果

最佳实践建议

1. 部署时仔细检查所有服务的volume配置
2. 定期验证GC功能是否正常工作
3. 考虑使用更可靠的存储后端（如S3）替代本地文件系统
4. 对于生产环境，建议：
   • 实施存储使用监控
   • 建立定期维护窗口处理潜在问题
   • 保持Harbor版本更新

总结

Harbor的垃圾回收机制依赖于多个组件的协同工作，任何配置不一致都可能导致功能异常。通过理解其内部工作机制，正确配置存储路径，并建立适当的监控机制，可以确保GC功能按预期工作，有效管理存储空间。对于已经出现的问题，需要结合手动干预和系统配置调整来解决。