极狐GitLab 是 GitLab 在中国的发行版，关于中文参考文档和资料有：

• 极狐GitLab 中文文档
• 极狐GitLab 中文论坛
• 极狐GitLab 官网

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

此页面包含有关在私有化部署实例中配置 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 的服务器上。

NOTE:对于 Docker 安装实例，您可以更改装载数据的路径。 对于 Helm chart 安装实例，请使用对象存储。
要更改默认的本地存储路径位置：
::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 对象存储在远程对象存储中。这使您可以减少对本地磁盘的读取和写入，并释放磁盘空间。

NOTE:在 13.2 及更高版本，您应该使用整合对象存储设置。

迁移到对象存储

您可以将 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

迁移回本地存储

NOTE:对于 Helm chart，您应该使用对象存储。

要迁移回本地存储：
::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。

WARNING:此功能受一个已知问题的影响。如果您使用 pure SSH 协议，克隆包含多个 Git LFS 对象的存储库时，客户端可能会崩溃，因为 nil 指针引用。

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 :443: connect: connection refused
• Connection refused - connect(2) for “” 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 域名。有关详细信息，请参阅以下文档：

• AWS S3
• Google Cloud Storage
• 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 对象。