LFS 활성화 또는 비활성화
로컬 저장소 경로 변경
원격 객체 저장소에 LFS 객체 저장
- 객체 저장소로 마이그레이션
- 로컬 스토리지로의 마이그레이션
저장소 통계
관련 주제
문제 해결
PDF 파일 보기 오류
알려진 제한 사항

GitLab Git Large File Storage (LFS) Administration

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

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

전제 조건:

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

LFS 활성화 또는 비활성화

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

Linux 패키지 (Omnibus)

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

# Change to true to enable lfs - enabled by default if not defined
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

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

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 객체를 원격 객체 저장소에 저장할 수 있습니다. 이를 통해 로컬 디스크로의 읽기 및 쓰기를 줄이고 디스크 공간을 크게 절약할 수 있습니다.

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

직접 컴파일 (소스)

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

도커

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

sudo docker exec -t <컨테이너 이름> 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

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

LFS 객체의 무결성 검사를 VERBOSE=1 매개변수와 함께 실행하는 경우.

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

레일즈 콘솔을 시작합니다.

레일즈 콘솔에서 누락된 것으로 보고된 객체를 쿼리하여 파일 경로를 반환합니다:

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

디스크 또는 객체 스토리지에서 해당 파일이 있는지 확인합니다:

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

파일이 없는 경우, 레일즈 콘솔을 사용하여 데이터베이스 레코드를 제거합니다:

# 먼저 상위 레코드를 삭제한 다음 레코드 자체를 삭제합니다
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를 사용하는 경우, 업데이트된 Git LFS 클라이언트 버전을 받기 위해 GitLab Runner를 업그레이드하여야 합니다. 이를 위해 13.2.0 이상의 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을 사용하지 않도록 구성된 경우, 웹 브라우저에서 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 객체

LFS 명령이 TLS v1.3 서버에서 실패합니다

`Connection refused` 오류

PDF 파일 보기 오류

알려진 제한 사항

도움말

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

도움받기

GitLab Git Large File Storage (LFS) Administration

LFS 활성화 또는 비활성화

로컬 저장소 경로 변경

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

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

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

저장소 통계

관련 주제

문제 해결

누락된 LFS 객체

LFS 명령이 TLS v1.3 서버에서 실패합니다

Connection refused 오류

PDF 파일 보기 오류

알려진 제한 사항

도움말

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

도움받기

`Connection refused` 오류