使用 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

将配置文件保存为集群中的 secret，注意命名空间需与 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 中的 key
            secret: gitlab-rails-storage # 上一步创建的 secret 名称
          enabled: true

#资源与参数配置

与普通 API 请求不同，上传和下载 LFS 文件时，workhorse 组件消耗更多 CPU 资源。workhorse 组件资源直接影响 push 和 pull 性能。

修改 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 客户端参数

执行以下命令保存克隆凭证，避免每次 pull 和 push 输入密码：

git config --global credential.helper store

执行以下命令设置 LFS 文件的并发传输数量，可有效提升 push 和 pull 的稳定性，尤其是一次推送大量文件时：

git config --global lfs.concurrenttransfers 2

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

git config --global lfs.activitytimeout 36000

#Git 项目配置

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

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 "Add LFS tracking for .safetensors files"
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