当前位置：首页 > news >正文

极狐GitLab Git LFS（大文件存储）如何管理？

news 2026/2/8 18:35:50

GitLab 是一个全球知名的一体化 DevOps 平台，很多人都通过私有化部署 GitLab 来进行源代码托管。极狐GitLab ：https://gitlab.cn/install?channel=content&utm_source=csdn 是 GitLab 在中国的发行版，专门为中国程序员服务。可以一键式部署极狐GitLab。

极狐GitLab 在 5 月 28 日正式发布了 AI 产品驭码CodeRider。现已开启免费试用，登录官网：https://coderider.gitlab.cn/ 即可申请试用。

更多关于极狐GitLab ：https://gitlab.cn 或者 DevOps 的最佳实践，可以关注文末的极狐GitLab 公众号。

学习极狐GitLab 的相关资料：

极狐GitLab 官网：https://gitlab.cn
极狐GitLab 官网文档：https://docs.gitlab.cn
极狐GitLab 论坛：https://forum.gitlab.cn/
极狐GitLab 安装配置：https://gitlab.cn/install
极狐GitLab 资源中心：https://resources.gitlab.cn/
AI 产品驭码CodeRider：https://coderider.gitlab.cn/

搜索【极狐GitLab】公众号，后台输入加群，备注gitlab，即可加入官方微信技术交流群。

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

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

启用或禁用 LFS

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

Omnibus

编辑 /etc/gitlab/gitlab.rb：

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

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

sudo gitlab-ctl reconfigure

Kubernetes

导出 Helm 值：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:appConfig:lfs:enabled: false

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

编辑 docker-compose.yml：

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

保存文件并重启极狐GitLab：

docker compose up -d

源安装

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

production: &baselfs:enabled: false

保存文件并重启极狐GitLab：

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

更改本地存储路径

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

NOTE:对于 Docker 安装实例，您可以更改装载数据的路径。对于 Helm chart 安装实例，请使用对象存储。

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

Omnibus

编辑 /etc/gitlab/gitlab.rb：

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

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

sudo gitlab-ctl reconfigure

源安装

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

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

保存文件并重启极狐GitLab：

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

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

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

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

迁移到对象存储

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

配置对象存储。
迁移 LFS 对象：

Omnibus

sudo gitlab-rake gitlab:lfs:migrate

Docker

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

源安装

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

可选。使用 PostgreSQL 控制台跟踪进度并验证所有作业 LFS 对象是否已成功迁移。
1. 打开 PostgreSQL 控制台：

Omnibus

sudo gitlab-psql

Docker

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

源安装

sudo -u git -H psql -d gitlabhq_production

使用以下 SQL 查询验证所有 LFS 文件是否已迁移到对象存储。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

验证 lfs-objects 目录中的磁盘上没有文件：

Omnibus

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

Docker

假设您将 /var/opt/gitlab 挂载到 /srv/gitlab：

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

源安装

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

迁移回本地存储

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

要迁移回本地存储：

Omnibus

迁移 LFS 对象：

sudo gitlab-rake gitlab:lfs:migrate_to_local

编辑 LFS 对象的 /etc/gitlab/gitlab.rb 和禁用对象存储：

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

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

sudo gitlab-ctl reconfigure

Docker

1.迁移 LFS 对象：

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

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

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

保存文件并重启极狐GitLab：

docker compose up -d

源安装

迁移 LFS 对象：

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

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

production: &baseobject_store:objects:lfs:enabled: false

保存文件并重启极狐GitLab：

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

故障排除

缺少 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 对象的记录。数据库条目可能会阻止推送对象的新副本。要删除这些引用：

启动 Rails 控制台。
查询 rails 控制台报错的对象，返回文件路径：

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

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

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

如果文件不存在，通过 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

查看 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

已知限制

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

学习极狐GitLab 的相关资料：

启用或禁用 LFS

Omnibus

Kubernetes

Docker

源安装

更改本地存储路径

Omnibus

源安装

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

迁移到对象存储

Omnibus

Omnibus

Docker

源安装

Omnibus

Docker

源安装

迁移回本地存储

Omnibus

Docker

源安装

故障排除

缺少 LFS 对象

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

查看 PDF 文件时出错

已知限制

相关文章：