使用 LFS 管理大文件#

本文将介绍如何使用 LFS 管理大文件，包括 GitLab 实例配置和 Git 客户端配置。

适用场景：

• 使用 LFS 管理代码仓库中的可执行文件，例如编译后的 JAR 包
• 使用 LFS 管理代码仓库中的 AI 大模型文件

#GitLab 实例配置

#前提条件

• 已按照 GitLab 实例部署 文档完成 GitLab 实例的部署。

GitLab 支持 两种方法 来配置 LFS，主要区别在于 LFS 文件的存储位置。

1. 使用本地存储保存 LFS 文件
2. 使用对象存储保存 LFS 文件

由于 LFS 通常存储大文件，因此存储容量的使用可能会很大。因此，在部署之前，根据要求合理规划存储容量非常重要。

#使用本地存储保存 LFS 文件

默认情况下，已部署的 GitLab 实例已经启用 LFS 功能，并使用本地存储保存 LFS 文件。

本地存储的 LFS 文件保存在 attachment storage 中，路径为：shareds/lfs-objects。

附件存储因部署方式而异：

• 使用 HostPath 部署的 GitLab 实例使用节点存储。由于扩展节点存储的难度，此方法不推荐用于生产环境。
• 使用存储类或指定 PVC 方法部署的 GitLab 实例都使用 PVC 作为存储介质。

#使用对象存储保存 LFS 文件（推荐）

GitLab 官方推荐使用对象存储来保存 LFS 文件。

GitLab 支持多种类型的对象存储。以下示例使用 MinIO 演示如何配置 GitLab 使用对象存储。

在 MinIO 中创建以下存储桶：

1. git-lfs
2. gitlab-uploads

使用 mc cli 命令创建存储桶的方法如下：

# 设置 MinIO 访问地址、访问密钥和秘密密钥
export MINIO_HOST=minio.example.com
export MINIO_ACCESS_KEY=your-access-key
export MINIO_SECRET_KEY=your-secret-key
mc alias set minio http://${MINIO_HOST} ${MINIO_ACCESS_KEY} ${MINIO_SECRET_KEY}

# 创建 git-lfs 和 gitlab-uploads 存储桶
mc mb minio/git-lfs
mc mb minio/gitlab-uploads

准备一个名为 rails-storage.yaml 的 MinIO 配置文件，内容如下：

provider: AWS
region: us-east-1
aws_access_key_id: example
aws_secret_access_key: example
endpoint: "http://minio.example.com"
path_style: true

其中：

• provider 为对象存储的类型，MinIO 使用固定值 AWS
• region 为对象存储的区域，MinIO 使用固定值 us-east-1
• aws_access_key_id 为对象存储的访问密钥 ID
• aws_secret_access_key 为对象存储的访问密钥
• endpoint 为对象存储的访问地址
• path_style 为对象存储的访问方式，这里使用固定值 true

将配置文件作为机密保存到集群中，注意命名空间必须与 GitLab 实例相同：

export GITLAB_NS=<your-gitlab-namespace>
kubectl create secret generic gitlab-rails-storage \
    -n ${GITLAB_NS} \
    --from-file=connection=rails-storage.yaml

通过添加以下内容修改 GitLab 实例配置，以启用对象存储：

spec:
  helmValues:
    global:
      appConfig:
        object_store:
          connection:
            key: connection # 密钥在机密中
            secret: gitlab-rails-storage # 上一步中创建的机密名称
          enabled: true

#资源和参数配置

与常规 API 请求不同，上传和下载 LFS 文件时，workhorse 组件消耗更多的 CPU 资源。workhorse 组件的资源直接影响推送和拉取性能。

通过添加以下内容修改 GitLab 实例配置，以调整 workhorse 组件的资源：

spec:
  helmValues:
    gitlab:
      webservice:
        workhorse:
          resources:
            limits:
              cpu: 2
              memory: 500Mi
            requests:
              cpu: 200m
              memory: 200Mi

此外，您还需要增加 webservice 组件的超时时间。配置方法如下：

spec:
  helmValues:
    gitlab:
      webservice:
        extraEnv:
          GITLAB_RAILS_RACK_TIMEOUT: "300"
    global:
      webservice:
        workerTimeout: 300

#Git 客户端配置

#前提条件

• 安装了 Git 客户端，执行 git version 命令检查 Git 版本。
• 安装了 git-lfs 客户端，执行 git-lfs version 命令检查 git-lfs 版本。

#配置 Git 客户端参数

执行以下命令保存克隆凭据，避免每次拉取和推送时输入密码：

git config --global credential.helper store

执行以下命令设置 LFS 文件的并发传输数量，能够有效提高推送和拉取的稳定性，特别是在一次性推送大量文件时：

git config --global lfs.concurrenttransfers 2

执行以下命令设置 LFS 活动超时。如果 GitLab 使用的是对象存储，则必须添加此参数：

git config --global lfs.activitytimeout 36000

#Git 项目配置

执行以下命令将 Git 仓库克隆到本地，并运行 git lfs install 安装 LFS git hook：

git clone http://example.com/root/local-lfs.git
cd local-lfs
git lfs install

执行以下命令设置 LFS 文件的跟踪模式，例如，跟踪所有 .safetensors 文件：

git lfs track "*.safetensors"

上述操作将生成一个 .gitattributes 文件。执行以下命令将此文件先提交到远程仓库：

git add .gitattributes
git commit -m "为 .safetensors 文件添加 LFS 跟踪"
git push

之后，向仓库中添加或更新 .safetensors 文件将自动使用 LFS 保存。

若要验证文件是否使用 LFS 保存，可以在 GitLab 仓库中查看该文件。如果文件名旁边有一个小 LFS 图标，则表示该文件是使用 LFS 保存的。

#常见问题

#克隆非常大的仓库失败

在克隆非常大的仓库时，如果客户端资源不足，客户端可能会在运行一段时间后被系统杀掉。解决方案如下：

1. 克隆时添加 GIT_LFS_SKIP_SMUDGE=1 参数以跳过 LFS 文件的溢出处理
2. 进入本地代码目录并执行 git lfs pull 命令以将 LFS 文件拉取到本地

GIT_LFS_SKIP_SMUDGE=1 git clone http://example.com/root/local-lfs.git
cd local-lfs
git lfs pull