LFS 활성화 또는 비활성화
로컬 리포지터리 경로 변경
원격 객체 리포지터리에 LFS 오브젝트 스토리지
- 객체 리포지터리로 이전
- 로컬 리포지터리로 마이그레이션
리포지터리 통계
관련 주제
문제 해결
PDF 파일을 보는 중에 오류가 발생함
알려진 제한 사항

GitLab Git Large File Storage (LFS) Administration

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

이 페이지에는 Self-Managed형 GitLab 인스턴스에서 Git LFS를 구성하는 정보가 포함되어 있습니다. Git LFS에 대한 사용자 설명서는 Git Large File Storage를 참조하십시오.

필수 조건:

사용자는 버전 1.0.1 이상의 Git LFS 클라이언트를 설치해야 합니다.

LFS 활성화 또는 비활성화

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

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집합니다.

# lfs를 활성화하려면 true로 변경합니다. 정의되지 않은 경우 기본적으로 활성화됩니다.
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
```

자체 컴파일(소스)

/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
```

자체 컴파일(소스)

/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

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

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

리포지터리 통계

그룹 및 프로젝트의 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 객체에 대한 레코드가 있을 수 있습니다. 데이터베이스 항목은 새로운 객체의 복사가 밀거나(push)되는 것을 방지할 수 있습니다. 이러한 참조를 삭제하려면:

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

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

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를 업그레이드하여 포함된 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 도메인을 허용하도록 설정하세요. 자세한 내용은 다음 문서를 참조하세요:

알려진 제한 사항

Git LFS 클라이언트 버전 1.1.0 이상 또는 1.0.2와만 호환됩니다.
리포지터리 통계는 해당 리포지터리에 연결된 모든 프로젝트의 각 LFS 객체를 카운트합니다.

GitLab Git Large File Storage (LFS) Administration

LFS 활성화 또는 비활성화

로컬 리포지터리 경로 변경

원격 객체 리포지터리에 LFS 오브젝트 스토리지

객체 리포지터리로 이전

로컬 리포지터리로 마이그레이션

리포지터리 통계

관련 주제

문제 해결

누락된 LFS 객체

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

`Connection refused` 오류

PDF 파일을 보는 중에 오류가 발생함

알려진 제한 사항

도움말

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

도움받기

GitLab Git Large File Storage (LFS) Administration

LFS 활성화 또는 비활성화

로컬 리포지터리 경로 변경

원격 객체 리포지터리에 LFS 오브젝트 스토리지

객체 리포지터리로 이전

로컬 리포지터리로 마이그레이션

리포지터리 통계

관련 주제

문제 해결

누락된 LFS 객체

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

Connection refused 오류

PDF 파일을 보는 중에 오류가 발생함

알려진 제한 사항

도움말

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

도움받기

`Connection refused` 오류