• 启用或禁用 LFS
• 更改本地存储路径
• 在远程对象存储中存储 LFS 对象
  • 迁移到对象存储
  • 迁移回本地存储
• 纯 SSH 传输协议
• 存储统计
• 相关主题
• 故障排除
  • 缺少 LFS 对象
  • LFS 命令在 TLS v1.3 服务器上失败
  • Connection refused 错误
• 查看 PDF 文件时出错
  • Fork 操作卡在 Forking in progress 消息上
• 已知限制

极狐GitLab Git 大文件存储 (LFS) 管理

此页面包含有关在私有化部署实例中配置 Git LFS 的信息。 有关 Git LFS 的用户文档，请参阅 Git 大文件存储。

先决条件：

• 用户需要安装 Git LFS 客户端 1.0.1 或更高版本。

启用或禁用 LFS

默认情况下启用 LFS。要禁用它：

::Tabs

:::TabTitle Linux package (Omnibus)

1. 编辑 /etc/gitlab/gitlab.rb：

   # Change to true to enable lfs - enabled by default if not defined
   gitlab_rails['lfs_enabled'] = false
   

2. 保存文件并重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

:::TabTitle Helm chart (Kubernetes)

1. 导出 Helm values：

   helm get values gitlab > gitlab_values.yaml
   

2. 编辑 gitlab_values.yaml：

   global:
     appConfig:
       lfs:
         enabled: false
   

3. 保存文件并应用新值：

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

:::TabTitle Docker

1. 编辑 docker-compose.yml：

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           gitlab_rails['lfs_enabled'] = false
   

2. 保存文件并重启极狐GitLab：

   docker compose up -d
   

:::TabTitle Self-compiled (source)

1. 编辑 /home/git/gitlab/config/gitlab.yml：

   production: &base
     lfs:
       enabled: false
   

2. 保存文件并重启极狐GitLab：

   # For systems running systemd
   sudo systemctl restart gitlab.target
   
   # For systems running SysV init
   sudo service gitlab restart
   

::EndTabs

更改本地存储路径

Git LFS 对象可以很大。默认情况下，它们存储在安装极狐GitLab 的服务器上。

要更改默认的本地存储路径位置：

::Tabs

:::TabTitle Linux package (Omnibus)

1. 编辑 /etc/gitlab/gitlab.rb：

   # /var/opt/gitlab/gitlab-rails/shared/lfs-objects by default.
   gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"
   

2. 保存文件并重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

:::TabTitle Self-compiled (source)

1. 编辑 /home/git/gitlab/config/gitlab.yml：

   # /home/git/gitlab/shared/lfs-objects by default.
   production: &base
     lfs:
       storage_path: /mnt/storage/lfs-objects
   

2. 保存文件并重启极狐GitLab：

   # For systems running systemd
   sudo systemctl restart gitlab.target
   
   # For systems running SysV init
   sudo service gitlab restart
   

::EndTabs

在远程对象存储中存储 LFS 对象

您可以将 LFS 对象存储在远程对象存储中。这使您可以减少对本地磁盘的读取和写入，并释放磁盘空间。

迁移到对象存储

您可以将 LFS 对象从本地存储迁移到对象存储。处理在后台完成，不需要停机。

1. 配置对象存储。

2. 迁移 LFS 对象：

   ::Tabs

   :::TabTitle Linux package (Omnibus)

   sudo gitlab-rake gitlab:lfs:migrate
   

   :::TabTitle Docker

   sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate
   

   :::TabTitle Self-compiled (source)

   sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production
   

   ::EndTabs

3. 可选。追踪进度并验证所有的 LFS 对象都已经使用 PostgreSQL 控制台成功完成了迁移。

   1. 打开一个 PostgreSQL 控制台：

      ::Tabs

      :::TabTitle Linux package (Omnibus)

      sudo gitlab-psql
      

      :::TabTitle Docker

      sudo docker exec -it <container_name> /bin/bash
      gitlab-psql
      

      :::TabTitle Self-compiled (source)

      sudo -u git -H psql -d gitlabhq_production
      

      ::EndTabs

   2. 验证所有的 LFS 文件都用如下的 SQL 查询完成了迁移。objectstg 的值应该和 total 相同：

      gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM lfs_objects;
      
      total | filesystem | objectstg
      ------+------------+-----------
       2409 |          0 |      2409
      

4. 验证在 lfs-objects 目录下没有文件在磁盘上：

   ::Tabs

   :::TabTitle Linux package (Omnibus)

   sudo find /var/opt/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l
   

   :::TabTitle Docker

   Assuming you mounted /var/opt/gitlab to /srv/gitlab:

   sudo find /srv/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l
   

   :::TabTitle Self-compiled (source)

   sudo find /home/git/gitlab/shared/lfs-objects -type f | grep -v tmp | wc -l
   

   ::EndTabs

迁移回本地存储

要迁移回本地存储：

::Tabs

:::TabTitle Linux package (Omnibus)

1. 迁移 LFS 对象：

   sudo gitlab-rake gitlab:lfs:migrate_to_local
   

2. 编辑 /etc/gitlab/gitlab.rb 并禁用对象存储：

   gitlab_rails['object_store']['objects']['lfs']['enabled'] = false
   

3. 保存文件并重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

:::TabTitle Docker

1. 迁移 LFS 对象：

   sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate_to_local
   

2. 编辑 docker-compose.yml 并为 LFS 对象禁用对象存储：

   version: "3.6"
   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           gitlab_rails['object_store']['objects']['lfs']['enabled'] = false
   

3. 保存文件并重启极狐GitLab：

   docker compose up -d
   

:::TabTitle Self-compiled (source)

1. 迁移 LFS 对象：

   sudo -u git -H bundle exec rake gitlab:lfs:migrate_to_local RAILS_ENV=production
   

2. 编辑 /home/git/gitlab/config/gitlab.yml 并为 LFS 对象禁用对象存储：

   production: &base
     object_store:
       objects:
         lfs:
           enabled: false
   

3. 保存文件并重启极狐GitLab：

   # For systems running systemd
   sudo systemctl restart gitlab.target
   
   # For systems running SysV init
   sudo service gitlab restart
   

::EndTabs

纯 SSH 传输协议

• 引入于极狐GitLab 17.2。
• 对 Helm chart (Kubernetes) 的支持引入于极狐GitLab 17.3。

git-lfs 3.0.0 支持使用 SSH 作为传输协议，而不是 HTTP。SSH 通过 git-lfs 命令行工具来透明处理。

当启用纯 SSH 协议支持时，git 被配置为使用 SSH，所有的 LFS 操作都通过 SSH 进行。比如，当 Git 远端是 git@jihulab.com:gitlab-org/gitlab.git。您不能配置 git 和 git-lfs 使用不同的协议。从 3.0 版本开始，git-lfs 尝试使用纯 SSH 协议，如果支持不可用或未启用，则回退到使用 HTTP。

先决条件：

• git-lfs 版本必需为 v3.5.1 或更高。

要切换 Git LFS 以使用纯 SSH 协议：

::Tabs

:::TabTitle Linux package (Omnibus)

1. 编辑 /etc/gitlab/gitlab.rb：

   gitlab_shell['lfs_pure_ssh_protocol'] = true
   

2. 保存文件并重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

:::TabTitle Helm chart (Kubernetes)

1. 导出 Helm values：

   helm get values gitlab > gitlab_values.yaml
   

2. 编辑 gitlab_values.yaml：

   gitlab:
     gitlab-shell:
       config:
         lfs:
           pureSSHProtocol: true
   

3. 保存文件并应用新值：

   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
   

:::TabTitle Docker

1. 编辑 docker-compose.yml：

   services:
     gitlab:
       environment:
         GITLAB_OMNIBUS_CONFIG: |
           gitlab_shell['lfs_pure_ssh_protocol'] = true
   

2. 保存文件并重启极狐GitLab 及其服务：

   docker compose up -d
   

:::TabTitle Self-compiled (source)

1. 编辑 /home/git/gitlab-shell/config.yml：

   lfs:
      pure_ssh_protocol: true
   

2. 保存文件并重启极狐GitLab Shell：

   # For systems running systemd
   sudo systemctl restart gitlab-shell.target
   
   # For systems running SysV init
   sudo service gitlab-shell restart
   

::EndTabs

存储统计

您可以看到用于群组和项目上的 LFS 对象的总存储空间：

• 在管理员区域。
• 在群组和项目 APIs 中。

相关主题

• 用户文档：Git 大文件存储 (LFS)
• Git LFS 开发者信息

故障排除

缺少 LFS 对象

在以下任何一种情况下，都可能会出现有关丢失 LFS 对象的错误：

• 将 LFS 对象从磁盘迁移到对象存储时，出现以下错误消息：

  ERROR -- : Failed to transfer LFS object
  006622269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7
  with error: No such file or directory @ rb_sysopen -
  /var/opt/gitlab/gitlab-rails/shared/lfs-objects/00/66/22269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7
  

  （为了便于阅读，添加了换行符。）

• 使用 VERBOSE=1 参数运行 LFS 对象的完整性检查。

数据库可以有不在磁盘上的 LFS 对象的记录。数据库条目可能会阻止推送对象的新副本。要删除这些引用：

1. 启动 Rails 控制台。

2. 查询 rails 控制台报错的对象，返回文件路径：

   lfs_object = LfsObject.find_by(oid: '006622269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7')
   lfs_object.file.path
   

3. 检查磁盘或对象存储是否存在：

   ls -al /var/opt/gitlab/gitlab-rails/shared/lfs-objects/00/66/22269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7
   

4. 如果文件不存在，通过 rails 控制台删除数据库记录：

   # First delete the parent records and then destroy the record itself
   lfs_object.lfs_objects_projects.destroy_all
   lfs_object.destroy
   

LFS 命令在 TLS v1.3 服务器上失败

如果您将极狐GitLab 配置为禁用 TLS v1.2，并且仅启用 TLS v1.3 连接，则 LFS 操作需要 Git LFS 客户端 2.11.0 或更高版本。如果您使用低于 2.11.0 版本的 Git LFS 客户端，极狐GitLab 会显示错误：

batch response: Post https://username:***@gitlab.example.com/tool/releases.git/info/lfs/objects/batch: remote error: tls: protocol version not supported
error: failed to fetch some objects from 'https://username:[MASKED]@gitlab.example.com/tool/releases.git/info/lfs'

在 TLS v1.3 配置的极狐GitLab 服务器上使用 CI 时，您必须升级到极狐GitLab Runner 13.2.0 或更高版本才能接收更新 Git LFS 客户端版本通过包含的 Runner Helper 镜像。

要检查已安装的 Git LFS 客户端的版本，请运行以下命令：

git lfs version

Connection refused 错误

如果您推送或镜像 LFS 对象时收到如下错误：

• dial tcp <IP>:443: connect: connection refused
• Connection refused - connect(2) for \"<target-or-proxy-IP>\" port 443

防火墙或代理规则可能会终止连接。

如果使用标准的 Unix 工具来检查连接或手动的 Git 推送操作成功，那么该规则可能与请求的大小有关。

查看 PDF 文件时出错

当 LFS 配置了对象存储并将 proxy_download 设置为 false 时，您在从 Web 浏览器预览 PDF 文件时可能会看到错误：

An error occurred while loading the file. Please try again later.

这是由于跨源资源共享 (CORS) 限制造成的：浏览器尝试从对象存储加载 PDF，但对象存储提供程序拒绝请求，因为极狐GitLab 域名与对象存储域名不同。

要解决此问题，请将对象存储提供商的 CORS 设置配置为允许极狐GitLab 域名。有关详细信息，请参阅以下文档：

1. AWS S3
2. Google Cloud Storage
3. Azure Storage

Fork 操作卡在 Forking in progress 消息上

如果您在 fork 一个具有多个 LFS 文件的项目，操作可能会卡住，而且展示 Forking in progress 消息。如果您遇到了此问题，遵循以下步骤来诊断并解决问题：

1. 针对如下错误来检查您的 exceptions_json.log 文件：

   "error_message": "Unable to fork project 12345 for repository
   @hashed/11/22/encoded-path -> @hashed/33/44/encoded-new-path:
   Source project has too many LFS objects"
   

   此错误意味着您已经达到了 LFS 文件的 100,000 限制。

2. 增加 GITLAB_LFS_MAX_OID_TO_FETCH 变量的值：

   1. 打开配置文件 /etc/gitlab/gitlab.rb。

   2. 添加并更新变量：

      gitlab_rails['env'] = {
         "GITLAB_LFS_MAX_OID_TO_FETCH" => "NEW_VALUE"
      }
      

      用您实际所需的值替换 NEW_VALUE。

3. 应用变更。运行：

   sudo gitlab-ctl reconfigure
   

   更多信息，查看重新配置 Linux 软件包安装。

4. 重复 fork 操作。

已知限制

• 仅与 Git LFS 客户端版本 1.1.0 及更高版本或 1.0.2 兼容。
• 存储统计为每个链接到它的项目计算每个 LFS 对象。