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

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

전제 조건:

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

LFS 활성화 또는 비활성화

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

Linux package (Omnibus)

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

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

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

Helm chart (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 (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 package (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 객체를 원격 객체 저장소에 저장할 수 있습니다. 이를 통해 로컬 디스크에 대한 읽기 및 쓰기를 줄일 수 있으며 디스크 공간을 크게 절약할 수 있습니다.

객체 저장소 설정를 사용해야 합니다.

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

LFS 객체를 로컬 저장소에서 객체 저장소로 마이그레이션할 수 있습니다. 이 처리는 백그라운드에서 수행되며 다운타임이 필요하지 않습니다.

객체 저장소를 구성합니다.

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

Linux package (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 콘솔을 사용하여 성공적으로 마이그레이션되었는지 확인합니다.
1. PostgreSQL 콘솔을 엽니다:
  Linux package (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
2. 다음 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 package (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 차트의 경우 객체 저장소를 사용해야 합니다.

로컬 저장소로 마이그레이션하기 위해:

Linux package (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
```

Self-compiled (source)

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 프로토콜을 사용하도록 전환하려면:

Linux package (Omnibus)

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

gitlab_shell['lfs_pure_ssh_protocol'] = true

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

Helm chart (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

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

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

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

Self-compiled (source)

/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 객체에 대한 레코드가 있을 수 있습니다. 데이터베이스 항목은 새 객체 복사가 밀려 나가는 것을 방지할 수 있습니다. 이러한 참조를 제거하려면:

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

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

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를 사용할 때, 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

방화벽이나 프록시 규칙이 연결을 종료하고 있을 수 있습니다.

유닉스 툴이나 수동 Git 푸시로 연결 확인이 성공하는 경우, 규칙이 요청 크기와 관련이 있을 수 있습니다.

PDF 파일 보기 오류

LFS가 객체 저장소와 함께 구성되어 있고 proxy_download이 false로 설정된 경우, 웹 브라우저에서 PDF 파일을 미리 보는 동안 에러가 발생할 수 있습니다:

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

이는 Cross-Origin Resource Sharing (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"
```
이 오류는 이슈 #476693에 설명된 대로 기본 제한인 100,000개의 LFS 파일에 도달했음을 나타냅니다.
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
```
추가 정보는 리눅스 패키지 설치 다시 구성를 참조하세요.
포크 작업을 다시 수행하세요.

참고: 만약 GitLab Helm Chart를 사용한다면, 환경 변수 GITLAB_LFS_MAX_OID_TO_FETCH를 구성하기 위해 extraEnv를 사용하세요.

알려진 제한 사항

Git LFS 클라이언트 버전 1.1.0 이상 또는 1.0.2와 호환됨
저장 공간 통계는 해당 LFS 객체에 링크된 모든 프로젝트에서 각 LFS 객체를 기준으로 함.

GitLab Git Large File Storage (LFS) Administration

LFS 활성화 또는 비활성화

로컬 저장소 경로 변경

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

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

로컬 저장소로의 마이그레이션

순수 SSH 전송 프로토콜

저장소 통계

관련 주제

문제 해결

LFS 객체 누락

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

`Connection refused` 오류

PDF 파일 보기 오류

`Forking in progress` 메시지에서 멈춘 포크 작업

알려진 제한 사항

도움말

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

도움받기

GitLab Git Large File Storage (LFS) Administration

LFS 활성화 또는 비활성화

로컬 저장소 경로 변경

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

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

로컬 저장소로의 마이그레이션

순수 SSH 전송 프로토콜

저장소 통계

관련 주제

문제 해결

LFS 객체 누락

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

Connection refused 오류

PDF 파일 보기 오류

Forking in progress 메시지에서 멈춘 포크 작업

알려진 제한 사항

도움말

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

도움받기

`Connection refused` 오류

`Forking in progress` 메시지에서 멈춘 포크 작업