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를 참조하십시오.

Prerequisites:

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

LFS 활성화 또는 비활성화

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

Linux 패키지 (Omnibus)

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

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

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

Helm 차트 (Kubernetes)

Helm 값(values)을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml 파일을 편집합니다:

global:
  appConfig:
    lfs:
      enabled: false

새 값(values)을 적용하기 위해 파일을 저장합니다:
```
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 (source)

/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 (source)

/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 객체를 원격 객체 리포지터리에 저장할 수 있습니다. 이렇게 하면 로컬 디스크로의 읽기 및 쓰기를 줄이고 디스크 공간을 크게 절약할 수 있습니다.

GitLab 13.2 이상에서는 통합된 객체 리포지터리 설정을 사용해야 합니다.

객체 리포지터리로 마이그레이션

LFS 객체를 로컬 리포지터리에서 객체 리포지터리로 마이그레이션할 수 있습니다. 이 작업은 백그라운드에서 처리되며 다운타임이 필요하지 않습니다.

객체 리포지터리를 구성합니다.

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

Linux 패키지 (Omnibus)

sudo gitlab-rake gitlab:lfs:migrate

Docker

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

Self-compiled (source)

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

Self-compiled (source)

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

Self-compiled (source)

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

로컬 스토리지로의 마이그레이션

Helm 차트를 사용하려면 객체 리포지터리를 사용해야 합니다.

로컬 스토리지로 다시 마이그레이션하려면:

리눅스 패키지 (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
```

도커

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 객체가 디스크에서 객체 리포지터리로 마이그레이션 중에 다음과 같은 오류가 발생할 수 있습니다:

  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

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

LFS 객체의 무결성을 확인하는 integrity check for LFS objects를 VERBOSE=1 매개변수와 함께 실행할 때도 수반할 수 있습니다.

데이터베이스에는 디스크에 없는 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

TLS v1.3 서버에서 LFS 명령이 실패하는 문제

GitLab을 TLS v1.2를 비활성화하고 TLS v1.3 연결만 활성화하는 경우, LFS 작업에는 Git LFS client 버전 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를 사용하는 경우, 업데이트된 Git LFS 클라이언트 버전을 포함된 GitLab Runner Helper image를 통해 받기 위해 GitLab Runner 버전 13.2.0 이상으로 업그레이드해야 합니다.

설치된 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 파일을 미리 보는 중에 오류가 발생할 수 있습니다:

파일을 불러오는 중 오류가 발생했습니다. 나중에 다시 시도하세요.

이는 Cross-Origin Resource Sharing (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` 오류