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

使用 Git 大文件存储 (LFS)，您可以在 Git 仓库中存储大文件，而不会增加其大小或影响性能。您可以启用或禁用 LFS，配置 LFS 对象的本地或远程存储，并在不同的存储类型之间迁移对象。

有关 Git LFS 的用户文档，请参阅 Git 大文件存储。

先决条件：

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

启用或禁用 LFS#

LFS 默认启用。要禁用它：

更改本地存储路径#

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

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

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

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

您应该使用合并的对象存储设置。

迁移到对象存储#

您可以将 LFS 对象从本地存储迁移到对象存储。处理是在后台进行的，并且 无需停机。

1. 配置对象存储。

2. 迁移 LFS 对象：

shell
   sudo gitlab-rake gitlab:lfs:migrate

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

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

1. 可选。使用 PostgreSQL 控制台跟踪进度并验证所有 LFS 对象成功迁移。

   1. 打开 PostgreSQL 控制台：

shell
1      sudo gitlab-psql
2      ```
3
4</div>
5<!-- TAB_TITLE:Docker --><div class="gitlab-tab">
6
7```shell
8      sudo docker exec -it <container_name> /bin/bash
9      gitlab-psql
10      ```
11
12</div>
13<!-- TAB_TITLE:Self-compiled (source) --><div class="gitlab-tab">
14
15```shell
16      sudo -u git -H psql -d gitlabhq_production
17      ```
18
19</div>
20
21</div>
22
23   1. 使用以下 SQL 查询验证所有 LFS 文件是否迁移到对象存储。`objectstg` 的数量应与 `total` 相同：
24
25      ```shell
26      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;
27
28      total | filesystem | objectstg
29      ------+------------+-----------
30       2409 |          0 |      2409
31      ```
32
331. 验证 `lfs-objects` 目录中磁盘上没有文件：
34
35   <div class="gitlab-tabs">
36
37<!-- TAB_TITLE:Linux package (Omnibus) --><div class="gitlab-tab">
38
39```shell
40   sudo find /var/opt/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l

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

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

迁移回本地存储#

要迁移回本地存储：

纯 SSH 传输协议#

git-lfs 3.0.0 发布了使用 SSH 作为传输协议而不是 HTTP 的支持。SSH 由 git-lfs 命令行工具透明处理。

当启用纯 SSH 协议支持且 git 配置为使用 SSH 时，所有 LFS 操作均通过 SSH 进行。例如，当 Git 远程为 git@gitlab.com:gitlab-org/gitlab.git 时。您无法配置 git 和 git-lfs 使用不同的协议。从 3.0 版开始，git-lfs 尝试最初使用纯 SSH 协议，如果未启用或不可用，则回退到使用 HTTP。

先决条件：

• git-lfs 版本必须是 v3.5.1 或更高版本。

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

存储统计#

您可以在以下位置查看群组和项目中用于 LFS 对象的总存储：

• 管理员 区域
• 群组 和 项目 API

故障排除#

缺失的 LFS 对象#

在以下情况之一中可能会出现有关缺失的 LFS 对象的错误：

• 从磁盘迁移 LFS 对象到对象存储时，会出现类似以下的错误信息：

  plaintext
  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

  （已添加换行以提高可读性。）

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

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

1. 启动 Rails 控制台。

2. 在 Rails 控制台中查询报告缺失的对象，以返回文件路径：

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

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

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

4. 如果文件不存在，请使用 Rails 控制台删除数据库记录：

   ruby
   # 首先删除父记录，然后销毁记录本身
   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 会显示错误：

plaintext
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 服务器上使用极狐GitLab CI 时，您必须升级到极狐GitLab Runner 13.2.0 或更高版本，以接收包含极狐GitLab Runner Helper 镜像的更新 Git LFS 客户端版本。

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

shell
git lfs version

连接被拒绝 错误#

如果您推送或镜像 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 文件时看到错误：

plaintext
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 文件是否有以下错误消息：

   plaintext
   "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"

   此错误表示您已达到默认 100,000 个 LFS 文件的限制。

2. 增加 GITLAB_LFS_MAX_OID_TO_FETCH 变量的值：

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

   2. 添加或更新变量：

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

      根据您的需求替换 NEW_VALUE 为一个数字。

3. 应用更改。运行：

   shell
   sudo gitlab-ctl reconfigure

   有关更多信息，请参阅重新配置 Linux package 安装。

4. 重复 Fork 操作。

已知限制#

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