LFS 활성화 또는 비활성화
로컬 저장소 경로 변경
원격 객체 저장소에 LFS 객체 저장하기
- 객체 저장소로 마이그레이션하기
- 로컬 저장소로 다시 마이그레이션하기
순수 SSH 전송 프로토콜
스토리지 통계
관련 주제
문제 해결
알려진 제한사항

GitLab Git Large File Storage (LFS) 관리

Tier: Free, Premium, Ultimate Offering: Self-managed

이 페이지는 self-managed GitLab 인스턴스에서 Git LFS를 구성하는 방법에 대한 정보를 포함합니다.
Git LFS에 대한 사용자 문서는 Git Large File Storage를 참조하세요.

사전 요구 사항:

사용자는 Git LFS client 버전 1.0.1 이상을 설치해야 합니다.

LFS 활성화 또는 비활성화

LFS는 기본적으로 활성화되어 있습니다. 비활성화하려면:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

# 정의되지 않은 경우 기본적으로 활성화됨 - true로 변경하여 lfs를 활성화합니다.  
gitlab_rails['lfs_enabled'] = false  

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure  
```

Helm 차트 (Kubernetes)

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집합니다:

global:  
  appConfig:  
    lfs:  
      enabled: false  

파일을 저장하고 새로운 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml를 편집합니다:

version: "3.6"  
services:  
  gitlab:  
    environment:  
      GITLAB_OMNIBUS_CONFIG: |  
        gitlab_rails['lfs_enabled'] = false  

파일을 저장하고 GitLab을 다시 시작합니다:
```
docker compose up -d  
```

소스에서 컴파일된 (Self-compiled)

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base  
  lfs:  
    enabled: false  

파일을 저장하고 GitLab을 다시 시작합니다:

# systemd를 사용하는 시스템의 경우  
sudo systemctl restart gitlab.target  

# SysV init을 사용하는 시스템의 경우  
sudo service gitlab restart  

로컬 저장소 경로 변경

Git LFS 객체는 크기가 클 수 있습니다. 기본적으로，它们은 GitLab이 설치된 서버에 저장됩니다.

Docker 설치의 경우, 데이터가 마운트되는 경로를 변경할 수 있습니다.
Helm 차트의 경우 객체 저장소를 사용하세요.

기본 로컬 저장소 경로 위치를 변경하려면:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

# 기본적으로 /var/opt/gitlab/gitlab-rails/shared/lfs-objects입니다.  
gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"  

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure  
```

소스에서 컴파일된 (Self-compiled)

/home/git/gitlab/config/gitlab.yml을 편집합니다:

# 기본적으로 /home/git/gitlab/shared/lfs-objects입니다.  
production: &base  
  lfs:  
    storage_path: /mnt/storage/lfs-objects  

파일을 저장하고 GitLab을 다시 시작합니다:

# systemd를 사용하는 시스템의 경우  
sudo systemctl restart gitlab.target  

# SysV init을 사용하는 시스템의 경우  
sudo service gitlab restart  

원격 객체 저장소에 LFS 객체 저장하기

LFS 객체를 원격 객체 저장소에 저장할 수 있습니다. 이를 통해 로컬 디스크의 읽기 및 쓰기를 줄이고 디스크 공간을 상당히 확보할 수 있습니다.

다음의 통합 객체 저장소 설정을 사용해야 합니다.

객체 저장소로 마이그레이션하기

로컬 저장소에서 객체 저장소로 LFS 객체를 마이그레이션할 수 있습니다. 처리는 백그라운드에서 이루어지며 다운타임 없이 수행됩니다.

객체 저장소 구성하기.

LFS 객체를 마이그레이션합니다:

Linux 패키지 (Omnibus)

sudo gitlab-rake gitlab:lfs:migrate

Docker

sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate

자기 컴파일 (소스)

sudo -u git -H bundle exec rake gitlab:lfs:migrate RAILS_ENV=production

선택 사항. PostgreSQL 콘솔을 사용하여 모든 작업 LFS 객체가 성공적으로 마이그레이션되었는지 진행 상황을 추적합니다.

PostgreSQL 콘솔을 엽니다:

Linux 패키지 (Omnibus)

sudo gitlab-psql

Docker

sudo docker exec -it <container_name> /bin/bash
gitlab-psql

자기 컴파일 (소스)

sudo -u git -H psql -d gitlabhq_production

다음 SQL 쿼리를 사용하여 모든 LFS 파일이 객체 저장소로 마이그레이션되었는지 확인합니다. objectstg의 수는 total과 같아야 합니다:

gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM lfs_objects;

total | filesystem | objectstg
------+------------+-----------
 2409 |          0 |      2409

lfs-objects 디렉토리에 디스크에 파일이 없는지 확인합니다:

Linux 패키지 (Omnibus)

sudo find /var/opt/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l

Docker

/var/opt/gitlab를 /srv/gitlab에 마운트했다고 가정합니다:

sudo find /srv/gitlab/gitlab-rails/shared/lfs-objects -type f | grep -v tmp | wc -l

자기 컴파일 (소스)

sudo find /home/git/gitlab/shared/lfs-objects -type f | grep -v tmp | wc -l

로컬 저장소로 다시 마이그레이션하기

참고:

Helm 차트를 위해서는 객체 저장소를 사용해야 합니다.

로컬 저장소로 다시 마이그레이션하려면:

Linux 패키지 (Omnibus)

LFS 객체를 마이그레이션합니다:

sudo gitlab-rake gitlab:lfs:migrate_to_local

/etc/gitlab/gitlab.rb 파일을 편집하고 LFS 객체에 대한 객체 저장소 비활성화를 설정합니다:
```
gitlab_rails['object_store']['objects']['lfs']['enabled'] = false
```
파일을 저장하고 GitLab을 다시 구성합니다:
```
sudo gitlab-ctl reconfigure
```

Docker

LFS 객체를 마이그레이션합니다:

sudo docker exec -t <container name> gitlab-rake gitlab:lfs:migrate_to_local

docker-compose.yml 파일을 편집하고 LFS 객체에 대한 객체 저장소를 비활성화합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['object_store']['objects']['lfs']['enabled'] = false

파일을 저장하고 GitLab을 다시 시작합니다:
```
docker compose up -d
```

자기 컴파일 (소스)

LFS 객체를 마이그레이션합니다:

sudo -u git -H bundle exec rake gitlab:lfs:migrate_to_local RAILS_ENV=production

/home/git/gitlab/config/gitlab.yml 파일을 편집하고 LFS 객체에 대한 객체 저장소를 비활성화합니다:
```
production: &base
  object_store:
    objects:
      lfs:
        enabled: false
```

파일을 저장하고 GitLab을 다시 시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

순수 SSH 전송 프로토콜

GitLab 17.2에서 소개됨.

GitLab 17.3에서 Helm 차트(Kubernetes)에 대해 소개됨.

git-lfs 3.0.0 는 전송 프로토콜로 HTTP 대신 SSH를 사용할 수 있도록 지원을 발표했습니다.

SSH는 git-lfs 명령줄 도구에 의해 투명하게 처리됩니다.

순수 SSH 프로토콜 지원이 활성화되고 git가 SSH를 사용하도록 구성되면,

모든 LFS 작업은 SSH를 통해 수행됩니다.

예를 들어, Git 원격이 git@gitlab.com:gitlab-org/gitlab.git인 경우입니다.

git와 git-lfs를 서로 다른 프로토콜을 사용하도록 구성할 수 없습니다.

버전 3.0부터 git-lfs는 처음에 순수 SSH 프로토콜을 사용하려고 시도하며,

지원이 활성화되지 않거나 사용 가능하지 않은 경우 HTTP를 사용으로 되돌립니다.

사전 요구 사항:

git-lfs 버전은 v3.5.1 이상이어야 합니다.

Git LFS를 순수 SSH 프로토콜을 사용하도록 전환하려면:

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 수정합니다:

gitlab_shell['lfs_pure_ssh_protocol'] = true

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 수정합니다:

gitlab:
  gitlab-shell:
    config:
      lfs:
        pureSSHProtocol: true

파일을 저장하고 새로운 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

도커

docker-compose.yml를 수정합니다:

services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_shell['lfs_pure_ssh_protocol'] = true

파일을 저장하고 GitLab 및 해당 서비스를 재시작합니다:
```
docker compose up -d
```

소스에서 직접 컴파일

/home/git/gitlab-shell/config.yml를 수정합니다:
```
lfs:
   pure_ssh_protocol: true
```

파일을 저장하고 GitLab Shell을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab-shell.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab-shell restart

스토리지 통계

LFS 객체에 사용된 총 저장 공간을 그룹 및 프로젝트에서 확인할 수 있습니다:

관리자 영역
그룹 및 프로젝트 API

문제 해결

누락된 LFS 객체

누락된 LFS 객체에 대한 오류는 다음 두 가지 상황에서 발생할 수 있습니다:

디스크에서 객체 저장소로 LFS 객체를 마이그레이션할 때, 다음과 같은 오류 메시지가 나타납니다:

ERROR -- : Failed to transfer LFS object
006622269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7
with error: No such file or directory @ rb_sysopen -
/var/opt/gitlab/gitlab-rails/shared/lfs-objects/00/66/22269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7

(가독성을 위해 줄 바꿈이 추가되었습니다.)

VERBOSE=1 매개변수를 사용하여 LFS 객체의 무결성 검사를 실행할 때.

데이터베이스에는 디스크에 없는 LFS 객체에 대한 레코드가 있을 수 있습니다. 데이터베이스 항목이 객체의 새 복사가 푸시되는 것을 방지할 수 있습니다. 이러한 참조를 삭제하려면:

Rails 콘솔 시작.

Rails 콘솔에서 누락된 것으로 보고된 객체를 조회하여 파일 경로를 반환합니다:

lfs_object = LfsObject.find_by(oid: '006622269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7')
lfs_object.file.path

디스크 또는 객체 저장소에서 존재하는지 확인합니다:

ls -al /var/opt/gitlab/gitlab-rails/shared/lfs-objects/00/66/22269c61b41bf14a22bbe0e43be3acf86a4a446afb4250c3794ea47541a7

파일이 없으면, Rails 콘솔을 사용하여 데이터베이스 레코드를 제거합니다:

# 먼저 부모 레코드를 삭제한 다음 그 레코드를 삭제합니다
lfs_object.lfs_objects_projects.destroy_all
lfs_object.destroy

LFS 명령이 TLS v1.3 서버에서 실패함

GitLab을 TLS v1.2를 비활성화하고 TLS v1.3 연결만 활성화하도록 구성하면, LFS 작업은 Git LFS 클라이언트 버전 2.11.0 이상이 필요합니다. 버전 2.11.0 이전의 Git LFS 클라이언트를 사용하는 경우, GitLab은 오류를 표시합니다:

batch response: Post https://username:***@gitlab.example.com/tool/releases.git/info/lfs/objects/batch: remote error: tls: protocol version not supported
error: failed to fetch some objects from 'https://username:[MASKED]@gitlab.example.com/tool/releases.git/info/lfs'

TLS v1.3으로 구성된 GitLab 서버에서 GitLab CI를 사용하는 경우, GitLab Runner 13.2.0 이상으로 업그레이드하여 포함된 GitLab Runner Helper 이미지와 함께 업데이트된 Git LFS 클라이언트 버전을 받아야 합니다.

설치된 Git LFS 클라이언트의 버전을 확인하려면, 다음 명령을 실행하십시오:

git lfs version

`Connection refused` 오류

LFS 객체를 푸시하거나 미러링할 때 다음과 같은 오류가 발생하는 경우:

dial tcp <IP>:443: connect: connection refused
Connection refused - connect(2) for \"<target-or-proxy-IP>\" port 443

방화벽 또는 프록시 규칙이 연결을 종료할 수 있습니다.

표준 Unix 도구 또는 수동 Git 푸시로 연결 확인이 성공하면,

규칙이 요청의 크기와 관련이 있을 수 있습니다.

PDF 파일 보기 오류

LFS가 객체 저장소와 함께 구성되고 proxy_download가

false로 설정된 경우, 웹 브라우저에서 PDF 파일 미리 보기를 시도할 때 오류가 발생할 수 있습니다:

파일을 로드하는 동안 오류가 발생했습니다. 나중에 다시 시도해 주세요.

이 오류는 교차 출처 리소스 공유(CORS) 제한으로 인해 발생합니다:

브라우저가 객체 저장소에서 PDF를 로드하려고 하지만, 객체

저장소 제공자가 GitLab 도메인과 객체 저장소 도메인이 다르기 때문에 요청을 거부합니다.

이 문제를 해결하려면, 객체 저장소 제공자의 CORS

설정을 구성하여 GitLab 도메인을 허용하십시오. 자세한 내용은 다음 문서를 참조하십시오:

`Forking in progress` 메시지에서 중단된 포크 작업

여러 LFS 파일이 있는 프로젝트를 포크하는 경우,

작업이 Forking in progress 메시지에서 중단될 수 있습니다.

이 경우 다음 단계를 따라 문제를 진단하고 해결하십시오:

exceptions_json.log 파일에서 다음 오류 메시지를 확인하십시오:
```
"error_message": "Unable to fork project 12345 for repository 
@hashed/11/22/encoded-path -> @hashed/33/44/encoded-new-path: 
Source project has too many LFS objects"
```
이 오류는 기본 한도인 100,000 LFS 파일에 도달했음을 나타냅니다.

문제 #476693에서 설명됩니다.
GITLAB_LFS_MAX_OID_TO_FETCH 변수의 값을 증가시킵니다:
1. 구성 파일 /etc/gitlab/gitlab.rb를 엽니다.
2. 변수를 추가하거나 업데이트합니다:
```
gitlab_rails['env'] = {
   "GITLAB_LFS_MAX_OID_TO_FETCH" => "NEW_VALUE"
}
```
  요구 사항에 따라 NEW_VALUE를 숫자로 교체하십시오.
변경 사항을 적용합니다. 실행하세요:
```
sudo gitlab-ctl reconfigure
```
추가 정보는 Linux 패키지 설치 다시 구성을 참조하십시오.
포크 작업을 반복합니다.

참고:

GitLab Helm Chart를 사용하는 경우, extraEnv를 사용하여 환경 변수를 구성합니다 GITLAB_LFS_MAX_OID_TO_FETCH.

알려진 제한사항

Git LFS 클라이언트 버전 1.1.0 이상 또는 1.0.2와만 호환됩니다.
저장소 통계는 링크된 모든 프로젝트의 각 LFS 객체를 계산합니다.

GitLab Git Large File Storage (LFS) 관리

LFS 활성화 또는 비활성화

로컬 저장소 경로 변경

원격 객체 저장소에 LFS 객체 저장하기

객체 저장소로 마이그레이션하기

로컬 저장소로 다시 마이그레이션하기

순수 SSH 전송 프로토콜

스토리지 통계

관련 주제

문제 해결

누락된 LFS 객체

LFS 명령이 TLS v1.3 서버에서 실패함

`Connection refused` 오류

PDF 파일 보기 오류

`Forking in progress` 메시지에서 중단된 포크 작업

알려진 제한사항

도움말

기능 사용 가능성과 제품 평가판

도움받기

GitLab Git Large File Storage (LFS) 관리

LFS 활성화 또는 비활성화

로컬 저장소 경로 변경

원격 객체 저장소에 LFS 객체 저장하기

객체 저장소로 마이그레이션하기

로컬 저장소로 다시 마이그레이션하기

순수 SSH 전송 프로토콜

스토리지 통계

관련 주제

문제 해결

누락된 LFS 객체

LFS 명령이 TLS v1.3 서버에서 실패함

Connection refused 오류

PDF 파일 보기 오류

Forking in progress 메시지에서 중단된 포크 작업

알려진 제한사항

도움말

기능 사용 가능성과 제품 평가판

도움받기

`Connection refused` 오류

`Forking in progress` 메시지에서 중단된 포크 작업