使用 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 命令创建存储桶的方法如下：

# Set MinIO access address, access key, and secret key
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}

# Create git-lfs and gitlab-uploads buckets
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 # key in the secret
            secret: gitlab-rails-storage # name of the secret created in the previous step
          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 "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

GitLab 是 GitLab Inc. 的商标。

Alauda 是独立供应商。本产品与 GitLab Inc. 不存在关联，也未获得其认可或赞助。所有商标均归其各自所有者所有，本文使用这些商标仅用于标识目的。