| GitLab Docs

Help us learn about your current experience with the documentation. Take the survey.

---
stage: Create
group: Source Code
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
description: 为 GitLab 自托管配置 Git LFS。
title: GitLab Git 大文件存储 (LFS) 管理
---


      Tier: Free, Premium, Ultimate

      Offering: GitLab Self-Managed



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

关于 Git LFS 的用户文档，请参阅 [Git 大文件存储](../../topics/git/lfs/_index.md)。

前提条件：

- 用户必须安装 [Git LFS 客户端](https://git-lfs.com/) 版本 1.1.0 或更高版本，或 1.0.2。

## 启用或禁用 LFS

LFS 默认启用。如需禁用：


  


  
  
  
    
    
    
    
    

编辑 /etc/gitlab/gitlab.rb：


  
# 改为 true 可启用 lfs - 若未定义则默认启用
gitlab_rails['lfs_enabled'] = false


保存文件并重新配置 GitLab：


  
sudo gitlab-ctl reconfigure



  




  
  
  
    
    
    
    
    

导出 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-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: &base
  lfs:
    enabled: false


保存文件并重启 GitLab：


  
# 对于使用 systemd 的系统
sudo systemctl restart gitlab.target

# 对于使用 SysV init 的系统
sudo service gitlab restart



  







## 更改本地存储路径

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


  
  
    对于 Docker 安装，您可以更改数据挂载的路径。对于 Helm 图表，请使用
对象存储。




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


  


  
  
  
    
    
    
    
    

编辑 /etc/gitlab/gitlab.rb：


  
# 默认路径为 /var/opt/gitlab/gitlab-rails/shared/lfs-objects
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
production: &base
  lfs:
    storage_path: /mnt/storage/lfs-objects


保存文件并重启 GitLab：


  
# 对于使用 systemd 的系统
sudo systemctl restart gitlab.target

# 对于使用 SysV init 的系统
sudo service gitlab restart



  







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

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

您应使用
[统一对象存储设置](../object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form)。

### 迁移到对象存储

您可以将 LFS 对象从本地存储迁移到对象存储。此过程在后台执行，无需停机。

1. [配置对象存储](../object_storage.md#configure-a-single-storage-connection-for-all-object-types-consolidated-form)。
1. 迁移 LFS 对象：

   
  

   
  
  
  
    
    
    
    
    

  
sudo gitlab-rake gitlab:lfs:migrate

  



   
  
  
  
    
    
    
    
    

  
sudo docker exec -t <容器名称> gitlab-rake gitlab:lfs:migrate

  



   
  
  
  
    
    
    
    
    

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

  



   



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

      
  

      
  
  
  
    
    
    
    
    

  
sudo gitlab-psql

  



      
  
  
  
    
    
    
    
    

  
sudo docker exec -it <容器名称> /bin/bash
gitlab-psql

  



      
  
  
  
    
    
    
    
    

  
sudo -u git -H psql -d gitlabhq_production

  



      



   1. 使用以下 SQL 查询验证所有 LFS 文件是否已迁移到对象存储。`objectstg` 的数量应与 `total` 相同：

      ```shell
      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
      ```

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

   
  

   
  
  
  
    
    
    
    
    

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

  



   
  
  
  
    
    
    
    
    假设您将 /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

  



   



### 迁移回本地存储


  
  
    对于 Helm 图表，您应使用
对象存储。




要迁移回本地存储：


  


  
  
  
    
    
    
    
    

迁移 LFS 对象：


  
sudo gitlab-rake gitlab:lfs:migrate_to_local


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


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


保存文件并重新配置 GitLab：


  
sudo gitlab-ctl reconfigure



  




  
  
  
    
    
    
    
    

迁移 LFS 对象：


  
sudo docker exec -t <容器名称> 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: &base
  object_store:
    objects:
      lfs:
        enabled: false


保存文件并重启 GitLab：


  
# 对于使用 systemd 的系统
sudo systemctl restart gitlab.target

# 对于使用 SysV init 的系统
sudo service gitlab restart



  







## 纯 SSH 传输协议


    
    
    
引入 于 GitLab 17.2。
引入 Helm 图表（Kubernetes）于 GitLab 17.3。






  
  
    此功能受已知问题影响
（已在 Git LFS 3.6.0 中解决）。
如果您使用纯 SSH 协议克隆包含多个 Git LFS 对象的仓库，客户端可能因空指针引用而崩溃。




[`git-lfs` 3.0.0](https://github.com/git-lfs/git-lfs/blob/main/CHANGELOG.md#300-24-sep-2021)
发布了对使用 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](https://github.com/git-lfs/git-lfs/releases/tag/v3.5.1) 或更高。

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


  


  
  
  
    
    
    
    
    

编辑 /etc/gitlab/gitlab.rb：


  
gitlab_shell['lfs_pure_ssh_protocol'] = true


保存文件并重新配置 GitLab：


  
sudo gitlab-ctl reconfigure



  




  
  
  
    
    
    
    
    

导出 Helm 值：


  
helm get values gitlab > gitlab_values.yaml


编辑 gitlab_values.yaml：


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


保存文件并应用新值：


  
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab



  




  
  
  
    
    
    
    
    

编辑 docker-compose.yml：


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


保存文件并重启 GitLab 及其服务：


  
docker compose up -d



  




  
  
  
    
    
    
    
    

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


  
lfs:
   pure_ssh_protocol: true


保存文件并重启 GitLab Shell：


  
# 对于使用 systemd 的系统
sudo systemctl restart gitlab-shell.target

# 对于使用 SysV init 的系统
sudo service gitlab-shell restart



  







## 存储统计信息

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

- **Admin** 区域
- [组](../../api/groups.md) 和 [项目](../../api/projects.md) API


  
  
    存储统计信息会统计每个项目引用的每个 LFS 对象。




## 相关主题

- 博客文章：[Git LFS 入门](https://about.gitlab.com/blog/2017/01/30/getting-started-with-git-lfs-tutorial/)
- 用户文档：[Git 大文件存储 (LFS)](../../topics/git/lfs/_index.md)

## 故障排除

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

启动 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 控制台删除数据库记录：

# 先删除父记录，再销毁记录本身
lfs_object.lfs_objects_projects.destroy_all
lfs_object.destroy

批量删除缺失的 LFS 对象

要一次性删除多个缺失 LFS 对象的引用：

打开 GitLab Rails 控制台。

运行以下脚本：

lfs_files_deleted = 0
LfsObject.find_each do |lfs_file|
  next if lfs_file.file.file.exists?
  lfs_files_deleted += 1
  p "LFS file with ID #{lfs_file.id} and path #{lfs_file.file.path} is missing."
  # lfs_file.lfs_objects_projects.destroy_all     # 取消注释以删除父记录
  # lfs_file.destroy                              # 取消注释以销毁 LFS 对象引用
end
p "Count of identified/destroyed invalid references: #{lfs_files_deleted}"

此脚本识别数据库中所有缺失的 LFS 对象。在删除任何记录之前：

它首先打印缺失文件的信息以供验证。
注释行可防止意外删除。如果取消注释，脚本将删除识别的记录。
脚本自动打印最终删除记录的数量以供比较。

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

要检查已安装的 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 域。有关更多详细信息，请参阅以下文档：

分叉操作卡在“正在分叉中”消息

如果您分叉包含多个 LFS 文件的项目，操作可能会卡在“正在分叉中”消息。如果遇到此问题，请按照以下步骤诊断和解决：

检查您的 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"
```
此错误表示您已达到默认的 100,000 个 LFS 文件限制，如问题 #476693 中所述。
增加 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 替换为基于您需求的数字。
应用更改。运行：
```
sudo gitlab-ctl reconfigure
```
有关更多信息，请参阅重新配置 Linux 包安装。
重复分叉操作。

对于 GitLab Helm 图表，使用 extraEnv 配置环境变量 GITLAB_LFS_MAX_OID_TO_FETCH。

批量删除缺失的 LFS 对象

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

Connection refused 错误

查看 PDF 文件时出错

分叉操作卡在“正在分叉中”消息

`Connection refused` 错误