Git LFS 개발 가이드
이 페이지에는 GitLab 팀원을 위한 개발 중심 정보가 포함되어 있습니다. 사용자 문서에 관련된 내용은 Git Large File Storage를 참조하십시오.
컨트롤러 및 서비스
Repositories::GitHttpClientController
여기에 정의된 인증 방법은 다른 LFS 컨트롤러에서 상속됩니다.
Repositories::LfsApiController
#batch
인증 후 batch
액션은 Git LFS 클라이언트가 다운로드 및 업로드(풀, 푸시, 클론과 같은) 중에 호출하는 첫 번째 액션입니다.
Repositories::LfsStorageController
#upload_authorize
Workhorse에 파일을 저장할 경로를 포함하여 페이로드를 제공합니다. 원격 객체 리포지터리일 수 있습니다.
#upload_finalize
Workhorse로부터 요청을 처리하여, gitlab
에서 다음을 할 수 있도록 파일에 대한 정보가 포함된 요청을 처리합니다. (이 미들웨어 참조)
-
LfsObject
를 생성합니다. - 존재하는
LfsObject
를LfsObjectsProject
와 연결합니다.
LfsObject 및 LfsObjectsProject
- 특정
oid
(파일의 SHA256 체크섬)와 파일 크기를 가진 파일에 대해 하나의LfsObject
가 생성됩니다. -
LfsObjectsProject
는Project
에LfsObject
를 연결합니다. 이를 통해 프로젝트를 통해 파일에 액세스할 수 있는지 여부를 결정합니다. - 이러한 객체들은 또한 주어진 프로젝트가 사용 중인 LFS 리포지터리의 양을 계산하는 데 사용됩니다.
자세한 내용은
ProjectStatistics#update_lfs_objects_size
를 참조하세요.
Repositories::LfsLocksApiController
LFS의 락 API를 처리합니다. 대부분 해당 서비스에 위임합니다:
Lfs::LockFileService
Lfs::UnlockFileService
Lfs::LocksFinderService
이 엔드포인트는 다른 사용자에게 속한 락을 가진 파일을 푸시하는지 여부를 확인할 수 있는 페이로드로 응답합니다. 클라이언트 측 lfs.locksverify
구성을 설정하여, 다른 사용자에게 속한 락이 있으면 클라이언트가 푸시를 중단하도록 할 수 있습니다. 또한 다른 사용자에게 속한 락의 존재 여부는 서버 측에서도 확인됩니다.
예제 인증
- 클라이언트는 자격 증명을 몇 가지 다른 방법으로 저장하도록 구성할 수 있습니다. 자세한 내용은 Git LFS documentation on authentication을 참조하세요.
-
gitlab-lfs-authenticate
를gitlab-shell
에서 실행합니다.gitlab-lfs-authenticate
에 관한 Git LFS documentation 참조. -
gitlab-shell
은 GitLab API에 요청을 합니다. - 토큰으로 shell에 응답하는 방법. 이 토큰은 후속 요청에서 사용됩니다. 인증에 관한 Git LFS documentation을 참조하세요.
예제 클론
- Git LFS는 인증 헤더를 사용하여 파일을 다운로드할 수 있는 능력을 요청합니다.
-
gitlab
은 객체 디렉터리 및 해당 위치로 응답합니다. LfsApiController#batch 참조. - Git LFS는 이전 응답에서
href
에 대해 각 파일에 대한 요청을 수행합니다. 기본 전송 모드로 다운로드가 처리되는 방식 참조. - 원격 객체 리포지터리가 활성화되어 있으면,
gitlab
은 해당 URL로 리디렉션합니다. SendFileUpload 참조.
예제 푸시
- Git LFS는 파일을 업로드할 수 있는 능력을 요청합니다.
-
gitlab
은 객체 디렉터리 및 해당 업로드에 대한 위치로 응답합니다. LfsApiController#batch 참조. - Git LFS는 이전 응답에서
href
에 대해 각 파일에 대한 요청을 수행합니다. 기본 전송 모드로 업로드가 처리되는 방식 참조. -
gitlab
은 파일을 저장할 Workhorse의 경로를 포함하는 페이로드로 응답합니다. 원격 객체 리포지터리일 수 있습니다. LfsStorageController#upload_authorize 참조. - Workhorse는 파일을 저장하는 작업을 수행합니다.
- Workhorse는 업로드된 파일에 대한 정보를 포함한 요청을
gitlab
에 수행하여,gitlab
에서LfsObject
를 생성할 수 있도록 합니다. LfsStorageController#upload_finalize 참조.
심층 분석
2019년 4월, Francisco Javier López가 Deep Dive를 주최했는데(GitLab 팀 멤버 전용: https://gitlab.com/gitlab-org/create-stage/-/issues/1
) 여기서는 이후에 해당 부분에서 작업할 수 있는 누구에게나 도메인 특정 지식을 공유했습니다.
에서 녹화된 것을 찾을 수 있으며, Google 슬라이드와 PDF에서 슬라이드를 찾을 수 있습니다. 본 심층 분석은 GitLab 11.10 기준으로 정확했지만, 특정 세부 정보는 변경될 수 있지만 여전히 좋은 입문 자료로 제공될 것입니다.
프로젝트 아카이브에 LFS 블롭 포함
다음 다이어그램은 GitLab이 프로젝트 아카이브를 위해 LFS 파일을 해결하는 방법을 설명합니다:
- 사용자가 UI에서 프로젝트 아카이브를 요청합니다.
- Workhorse는 이 요청을 Rails로 전달합니다.
- 사용자가 아카이브를 다운로드할 권한이 있는 경우, Rails는 base64로 인코딩된 JSON 페이로드와 함께
git-archive
으로 앞에 두어진Gitlab-Workhorse-Send-Data
의 HTTP 헤더로 응답합니다. 이 페이로드에는SendArchiveRequest
이진 메시지가 포함되어 있습니다. 이 메시지는 다시 한 번 base64로 인코딩됩니다. - Workhorse는
Gitlab-Workhorse-Send-Data
페이로드를 디코딩합니다. 아카이브가 이미 아카이브 캐시에 존재하는 경우, Workhorse는 해당 파일을 보냅니다. 그렇지 않은 경우, Workhorse는SendArchiveRequest
를 적절한 Gitaly 서버로 보냅니다. - Gitaly 서버는 Git 아카이브를 동적으로 생성하기 시작하기 위해
git archive <ref>
를 호출합니다.include_lfs_blobs
플래그가 활성화된 경우, Gitaly은-c filter.lfs.smudge=/path/to/gitaly-lfs-smudge
Git 옵션을 사용하여 사용자 정의 LFS 스머지 필터를 활성화합니다. -
git
이.gitattributes
파일을 사용하여 가능한 LFS 포인터를 식별할 때,git
은gitaly-lfs-smudge
를 호출하고 표준 입력을 통해 LFS 포인터를 제공합니다. Gitaly는 LFS 객체 검색을 가능하게 하기 위해GL_PROJECT_PATH
와GL_INTERNAL_CONFIG
를 환경 변수로 제공합니다. - 유효한 LFS 포인터가 디코딩된 경우,
gitaly-lfs-smudge
은 GitLab에서 LFS 객체를 다운로드하기 위해 Workhorse로 내부 API 호출을 수행합니다. - Workhorse는 이 요청을 Rails로 전달합니다. LFS 객체가 존재하고 프로젝트와 연관되어 있는 경우, Rails은
send-url
로 앞에 두어진Gitlab-Workhorse-Send-Data
HTTP 헤더와 함께(로컬 디스크의 경우 LFS 객체가 있는 경로 또는 객체 리포지터리가 활성화된 경우 미리 서명된 URL)ArchivePath
를 보냅니다. - Workhorse는 파일을 검색하여
gitaly-lfs-smudge
프로세스로 보내어 내용을 표준 출력에 기록합니다. -
git
은 이 출력을 읽어 다시 Gitaly 프로세스로 보냅니다. - Gitaly은 데이터를 다시 Rails로 보냅니다.
- 아카이브 데이터가 클라이언트로 다시 전송됩니다.
7단계에서 gitaly-lfs-smudge
필터는 Workhorse로 이야기해야 하며, Rails로는 이야기해서는 안 됩니다. 그렇지 않으면 잘못된 LFS 블롭이 저장됩니다. 이를 지원하기 위해 GitLab은 기본 Omnibus 구성을 변경하여 Gitaly가 Rails 대신에 Workhorse와 대화하도록 기본 구성으로 변경했습니다.
이 변경의 부작용 중 하나는 Gitaly(또는 gitaly-lfs-smudge
)에 의해 내부 API 요청에서 원래 요청의 상관 ID가 보존되지 않는 점입니다. 이 Workhorse 이슈가 해결될 때까지 해당 API 요청의 상관 ID는 무작위 값입니다.
관련 주제
- 블로그 글: Git LFS 시작하기
- 사용자 문서: Git 대용량 파일 리포지터리 (LFS)
- GitLab Git 대용량 파일 리포지터리 (LFS) 관리 (Self-Managed형 인스턴스용)