GitLab自托管：大量附件子目录引发文件系统性能问题解决方案咨询

官方推荐核心方案 #

1. 迁移至对象存储 #

这是GitLab官方针对大量附件存储场景的首选方案，彻底规避本地文件系统的目录数量限制：

• 在/etc/gitlab/gitlab.rb中配置S3兼容对象存储（以MinIO为例）：

  gitlab_rails['object_store']['enabled'] = true
  gitlab_rails['object_store']['uploads']['enabled'] = true
  gitlab_rails['object_store']['uploads']['remote_directory'] = 'gitlab-issues-uploads'
  gitlab_rails['object_store']['connection'] = {
    provider: 'AWS',
    region: 'us-east-1',
    aws_access_key_id: 'MINIO_ACCESS_KEY',
    aws_secret_access_key: 'MINIO_SECRET_KEY',
    endpoint: 'https://your-minio-instance:9000',
    path_style: true
  }
  

• 执行配置生效与迁移命令：

  gitlab-ctl reconfigure
  gitlab-rake gitlab:uploads:migrate:all
  

• 迁移完成后清理本地冗余文件：

  gitlab-rake gitlab:uploads:cleanup
  

2. 调整本地存储的哈希目录层级 #

若暂时无法迁移至对象存储，可通过配置拆分哈希目录层级，降低单目录下的子目录密度：

• 在/etc/gitlab/gitlab.rb中添加层级配置（以2级为例）：

  gitlab_rails['uploads_directory_hierarchy'] = 2
  

• 执行gitlab-ctl reconfigure生效，新上传的附件会按哈希前缀拆分到多级目录（如哈希a1b2c3d4会存入a1/b2/a1b2c3d4）
• 注意：该配置仅对新附件生效，已有附件需手动迁移或通过脚本调整结构

文件系统层面优化 #

• 更换高性能文件系统：将ext4替换为XFS，XFS在处理大量子目录和小文件时的索引、inode管理性能更优
• 优化文件系统参数：
  • 确认ext4已启用dir_index（默认启用），验证命令：tune2fs -l /dev/your-disk | grep dir_index
  • 格式化时提前规划inode数量，示例：mkfs.ext4 -i 4096 /dev/your-disk，避免inode耗尽无法创建新目录

定期清理冗余附件 #

• 通过GitLab API批量筛选并删除过时附件（如关闭超6个月的议题附件）：

  # 获取符合条件的议题ID
  curl --header "PRIVATE-TOKEN: your-token" "https://your-gitlab/api/v4/projects/123/issues?state=closed&updated_before=$(date -d '-6 months' +%Y-%m-%d)" | jq '.[] | .id'
  

• 运行官方清理任务移除未关联的孤立附件：

  gitlab-rake gitlab:uploads:cleanup
  

升级至最新稳定版 #

新版本GitLab会持续优化存储逻辑，包括调整附件哈希目录结构、修复文件系统性能相关问题，降低单目录子目录密度

内容的提问来源于stack exchange，提问作者Somarand