使用GitLab管理大文件

2022-12-12 约 1649 字预计阅读 4 分钟

参考资料

Git Large File Storage

Git 大文件存储 (LFS) | 极狐GitLab

git-lfs/git-lfs-migrate.adoc at main · git-lfs/git-lfs

极狐GitLab Git 大文件存储 (LFS) 管理 | 极狐GitLab

减少仓库大小 | 极狐GitLab

推送规则 | 极狐GitLab

修订记录

日期内容

2022.12.12 创建文档

2023.03.30 增加推送规则配合LFS使用

日期	内容
2022.12.12	创建文档
2023.03.30	增加推送规则配合LFS使用

1. Git LFS简介

管理音频、视频、图形文件、设计模型等大文件一直是原生 Git 的缺点之一。一般建议使用文件管理系统如NAS、文件服务器、FTP服务器，或使用专业的文档协同工具，如Conference、金山文档等。这些工具可以面向更广泛的用户群体（包括非技术人员）提供文件存储、版本控制、在线协同等功能。

而对于技术人员，如果想将上述文档与代码编写工作放在一起管理，可使用Git LFS，不要让Git仓库数据量过大以保持性能。

Git LFS存储原理图如下所示：
使用LFS上传的文件会在GitLab文件名右侧显示“LFS”标识。
使用LFS上传的文件默认存在:
- Omnibus：/var/opt/gitlab/gitlab-rails/shared/lfs-objects 目录下。
- HA：Rails节点下。
可修改LFS存储路径为低成本的对象存储，而非高成本的SSD，实现存储分离的同时降低存储成本。

在远程对象存储中存储 LFS 对象 | 极狐GitLab

2. 使用要求

管理员开启LFS。极狐GitLab Git 大文件存储 (LFS) 管理 | 极狐GitLab
在项目设置下启用 Git LFS。
Git LFS 客户端 1.0.1 及以上版本。

3. 使用限制

不支持 Git LFS v1 原始 API，因为它在 LFS 开发早期被弃用。
当通过 SSH 管理远程代码库时，Git LFS 对象仍然通过 HTTPS 进行通讯。
任何 Git LFS 请求都要求提供 HTTPS 凭据。
群组 wiki 不支持 Git LFS。

4. 使用Git LFS

4.1 对新添加的文件使用LFS

使用LFS上传并管理本次新添加的文件或文件类型。

1
2
3
4
5
6
7
8


 git clone git@gitlab.example.com:group/project.git
 git lfs install                       # initialize the Git LFS project
 git lfs track "*.iso"                 # select the file extensions that you want to treat as large files

 cp ~/tmp/debian.iso ./                # copy a large file into the current directory
 git add .                             # add the large file to the project
 git commit -am "Added Debian iso"     # commit the file meta data
 git push origin main                # sync the git repo and large file to the GitLab server

4.2 对已上传的文件使用LFS

将已经上传到GitLab中的文件、文件类型转换成LFS进行存储管理。注意该方式对该文件的历史提交不生效。如下图，对两个*.zip的已存在文件使用LFS后，该文件最新的提交使用LFS，而历史提交还是直接走Git。

4.3 对已上传的文件及其历史提交使用LFS

将已经上传到GitLab中的文件、文件类型转换成LFS进行存储，并将其历史提交也转换成LFS进行存储管理。需使用git-lfs-migrate工具：

由于对文件及历史提交进行LFS迁移可能会涉及较多的文件，建议先对代码仓库进行备份，以免出现异常错误。

建议对代码仓库的逐个分支进行迁移，以免任务超时。

1
2
3
4
5
6
7


# 对master分支进行迁移，将png格式文件及其历史提交通过LFS进行管理
git lfs migrate import --include-ref=master --include="*.png"
# 对dev分支进行迁移，将png格式文件及其历史提交通过LFS进行管理
git lfs migrate import --include-ref=dev --include="*.png"
# 迁移完成后将所有分支和tag推送到远端仓库
git push --all --force
git push --tags --force

如果仓库不大，需要一次性迁移所有分支。

1
2
3


git lfs migrate import --everything --include="*.png"
git push --all --force
git push --tags --force

4.4 使用LFS克隆代码

如果使用HTTP(s)协议Clone，Git 会自动检测 LFS 跟踪的文件并通过 HTTP 克隆它们。
如果使用SSH协议Clone，需输入凭据进行HTTP身份验证，随后Git 会自动检测 LFS 跟踪的文件并通过 HTTP 克隆它们。
如果已经克隆了仓库，并且想要获取远端仓库上的最新 LFS 对象，可以使用 git lfs fetch origin main。

4.5 删除LFS管理的文件

将LFS管理的某文件，恢复到Git进行管理，对该文件的历史提交不生效。

1
2
3
4
5


git lfs untrack '<file-type>'
git rm --cached '<file-type>'
git add '<file-type>'
git commit -m "restore '<file-type>' to git from lfs"
git push

将LFS管理的某文件及其历史提交，恢复到Git进行管理，需使用git-lfs-migrate :

1
2
3


git lfs migrate export --everything --include="*.png"
git push --all --force
git push --tags --force

5. GitLab推送规则配合LFS

建议使用GitLab专业版的推送规则功能，限制Git上传文件的大小，一般建议设置为10MB。当单个上传文件大小超过10MB时，会提示文件大小超过限制导致无法上传，从而引导开发人员使用LFS来上传管理这些大文件。

目录