Git Large File Storage (LFS)

요약

문서화 및 자세한 내용은 Git LFS 사용자 가이드를 참조하세요. LFS는 기본적으로 GitLab에서 활성화되어 있습니다. Linux 패키지 (Omnibus): /etc/gitlab/gitlab.rb를 편집합니다: 파일을 저장하고 GitLab을 재구성합니다:

문서화 및 자세한 내용은 Git LFS 사용자 가이드를 참조하세요.

LFS 요구 사항#

GitLab에서 LFS를 사용하려면 Git LFS 클라이언트 버전 1.0.1 이상이 필요합니다.

LFS 활성화 또는 비활성화#

LFS는 기본적으로 GitLab에서 활성화되어 있습니다.

Linux 패키지 (Omnibus):

/etc/gitlab/gitlab.rb를 편집합니다:
```
gitlab_rails['lfs_enabled'] = false
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

직접 컴파일한 경우:

gitlab.yml을 편집합니다:

# GitLab LFS를 비활성화하려면 false로 변경
lfs:
  enabled: true

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

# GitLab systemd 서비스를 사용하는 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 경우
sudo service gitlab restart

Helm 차트 (쿠버네티스):

gitlab.yml 파일에서 global.appConfig.lfs 값을 내보냅니다:
```
helm get values gitlab -n <namespace> > gitlab.yaml
```

global.appConfig.lfs를 업데이트합니다:

global:
  appConfig:
    lfs:
      enabled: false

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

helm upgrade gitlab gitlab/gitlab \
  --namespace <namespace> \
  -f gitlab.yaml

Docker:

환경 변수를 설정합니다:

docker run ... \
  -e GITLAB_LFS_ENABLED=false \
  ...

LFS 로컬 스토리지 위치 변경#

기본적으로 LFS 오브젝트는 #{Gitlab.config.shared.path}/lfs-objects 디렉토리에 저장됩니다.

Linux 패키지 (Omnibus):

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

gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"

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

직접 컴파일한 경우:

gitlab.yml을 편집합니다:

lfs:
  enabled: true
  storage_path: /mnt/storage/lfs-objects

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

# GitLab systemd 서비스를 사용하는 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 경우
sudo service gitlab restart

원격 오브젝트 스토리지로 마이그레이션#

LFS 오브젝트를 원격 오브젝트 스토리지로 마이그레이션하는 방법에 대한 자세한 내용은 오브젝트 스토리지 마이그레이션을 참조하세요.

원격 오브젝트 스토리지로 마이그레이션#

LFS 오브젝트를 수동으로 마이그레이션하려면:

Linux 패키지 (Omnibus):

sudo gitlab-rake "gitlab:lfs:migrate"

직접 컴파일한 경우:

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

Helm 차트 (쿠버네티스):

kubectl exec -it <toolbox-pod-name> -- gitlab-rake "gitlab:lfs:migrate"

Docker:

docker exec -it <container> gitlab-rake "gitlab:lfs:migrate"

PostgreSQL에서 마이그레이션 상태를 확인하려면:

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 objectstorage FROM lfs_objects;

로컬 스토리지로 다시 마이그레이션#

LFS 오브젝트를 원격 오브젝트 스토리지에서 로컬 스토리지로 다시 마이그레이션하려면:

Linux 패키지 (Omnibus):

sudo gitlab-rake "gitlab:lfs:migrate_to_local"

직접 컴파일한 경우:

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

Helm 차트 (쿠버네티스):

kubectl exec -it <toolbox-pod-name> -- gitlab-rake "gitlab:lfs:migrate_to_local"

Docker:

docker exec -it <container> gitlab-rake "gitlab:lfs:migrate_to_local"

순수 SSH 프로토콜로 LFS 사용#

히스토리

GitLab 17.2에서 도입.

GitLab은 HTTPS를 사용하지 않고도 SSH를 통해 직접 LFS 오브젝트를 전송하는 방법을 지원합니다. 이는 클라이언트가 HTTP 또는 HTTPS에 액세스할 수 없고 SSH만 사용 가능한 경우에 유용합니다.

이 기능을 활성화하려면:

Linux 패키지 (Omnibus):

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

gitlab_rails['lfs_pure_ssh_protocol'] = true

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

직접 컴파일한 경우:

gitlab.yml을 편집합니다:

lfs:
  enabled: true
  pure_ssh_protocol: true

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

# GitLab systemd 서비스를 사용하는 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 경우
sudo service gitlab restart

Helm 차트 (쿠버네티스):

gitlab.yaml 파일에서 값을 내보냅니다:

helm get values gitlab -n <namespace> > gitlab.yaml

global.appConfig.lfs를 업데이트합니다:

global:
  appConfig:
    lfs:
      pureSshProtocol: true

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

helm upgrade gitlab gitlab/gitlab \
  --namespace <namespace> \
  -f gitlab.yaml

Docker:

환경 변수를 설정합니다:

docker run ... \
  -e GITLAB_LFS_PURE_SSH_PROTOCOL=true \
  ...

순수 SSH 프로토콜의 제한 사항#

순수 SSH 프로토콜은 SSH 키 인증이 있는 사용자에게만 작동합니다.
암호 인증은 지원되지 않습니다.
deploy token을 사용한 인증은 지원되지 않습니다.
순수 SSH 프로토콜은 Git LFS 클라이언트 버전 3.0 이상이 필요합니다.
--skip-smudge 없이 서브모듈을 사용하면 예기치 않게 실패할 수 있습니다.

스토리지 통계#

프로젝트의 LFS 파일 크기를 포함한 스토리지 통계는 프로젝트 페이지의 설정 탭에서 확인할 수 있습니다.

문제 해결#

누락된 LFS 오브젝트#

누락된 LFS 오브젝트를 확인하려면:

sudo gitlab-rake gitlab:lfs:check

데이터베이스의 LFS 오브젝트와 스토리지 파일 간의 불일치를 찾습니다. 참조가 없는 LFS 오브젝트를 제거하려면 Rails 콘솔에서 다음을 실행합니다:

# 스토리지에 파일이 없는 모든 LFS 오브젝트 찾기
LfsObject.find_each do |lfs_object|
  lfs_object.destroy unless lfs_object.file.exists?
end

여러 누락된 LFS 오브젝트 제거#

여러 누락된 LFS 오브젝트가 있는 경우 Rails 콘솔을 사용합니다:

# 파일이 없는 LFS 오브젝트 찾기 (배치로 처리)
deleted = 0
LfsObject.find_each do |lfs_object|
  unless lfs_object.file.file.exists?
    lfs_object.destroy
    deleted += 1
    puts "Deleted #{deleted}" if deleted % 100 == 0
  end
end
puts "Total deleted: #{deleted}"

이 명령은 데이터베이스에서 참조되는 오브젝트 수에 따라 시간이 걸릴 수 있습니다. 배치 모드로 실행하는 것이 좋습니다:

# Rails 콘솔에서 배치 처리
LfsObject.all.each_batch do |objects|
  objects.each do |object|
    begin
      object.file.file.exists?
    rescue Errno::ENOENT
      object.destroy
    end
  end
end

TLS v1.3 오류#

LFS에서 TLS v1.3을 사용할 때 문제가 발생하는 경우:

/etc/gitlab/gitlab.rb에 다음을 추가하여 TLS 버전을 조정합니다:
```
nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3"
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

연결 거부 오류#

LFS 연결 거부 오류가 발생하는 경우:

GitLab 서비스가 실행 중인지 확인합니다:
```
sudo gitlab-ctl status
```
GitLab 로그에서 오류를 확인합니다:
```
sudo gitlab-ctl tail gitlab-workhorse
```

PDF 파일에 대한 CORS 오류#

PDF 파일을 볼 때 CORS 오류가 발생하면:

LFS 오브젝트 스토리지에 CORS가 올바르게 구성되어 있는지 확인합니다.
오브젝트 스토리지 버킷에서 GitLab 도메인에 대한 CORS를 허용합니다.

포크가 LFS 오브젝트에 멈춤#

저장소 포크가 LFS 오브젝트 복사 시 멈추는 경우 GITLAB_LFS_MAX_OID_TO_FETCH 환경 변수로 제한을 조정할 수 있습니다:

Linux 패키지 (Omnibus):

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

gitlab_rails['env'] = { 'GITLAB_LFS_MAX_OID_TO_FETCH' => '100' }

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

기본값은 100이며, 이 값을 줄이면 더 작은 배치로 LFS 오브젝트를 가져옵니다.

Git Large File Storage (LFS)

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

원문 보기

번역일: 2026-05-22

요약

문서화 및 자세한 내용은 Git LFS 사용자 가이드를 참조하세요.

LFS 요구 사항#

GitLab에서 LFS를 사용하려면 Git LFS 클라이언트 버전 1.0.1 이상이 필요합니다.

LFS 활성화 또는 비활성화#

LFS는 기본적으로 GitLab에서 활성화되어 있습니다.

Linux 패키지 (Omnibus):

/etc/gitlab/gitlab.rb를 편집합니다:
```
gitlab_rails['lfs_enabled'] = false
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

직접 컴파일한 경우:

gitlab.yml을 편집합니다:

# GitLab LFS를 비활성화하려면 false로 변경
lfs:
  enabled: true

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

# GitLab systemd 서비스를 사용하는 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 경우
sudo service gitlab restart

Helm 차트 (쿠버네티스):

gitlab.yml 파일에서 global.appConfig.lfs 값을 내보냅니다:
```
helm get values gitlab -n <namespace> > gitlab.yaml
```

global.appConfig.lfs를 업데이트합니다:

global:
  appConfig:
    lfs:
      enabled: false

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

helm upgrade gitlab gitlab/gitlab \
  --namespace <namespace> \
  -f gitlab.yaml

Docker:

환경 변수를 설정합니다:

docker run ... \
  -e GITLAB_LFS_ENABLED=false \
  ...

LFS 로컬 스토리지 위치 변경#

기본적으로 LFS 오브젝트는 #{Gitlab.config.shared.path}/lfs-objects 디렉토리에 저장됩니다.

Linux 패키지 (Omnibus):

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

gitlab_rails['lfs_storage_path'] = "/mnt/storage/lfs-objects"

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

직접 컴파일한 경우:

gitlab.yml을 편집합니다:

lfs:
  enabled: true
  storage_path: /mnt/storage/lfs-objects

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

# GitLab systemd 서비스를 사용하는 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 경우
sudo service gitlab restart

원격 오브젝트 스토리지로 마이그레이션#

LFS 오브젝트를 원격 오브젝트 스토리지로 마이그레이션하는 방법에 대한 자세한 내용은 오브젝트 스토리지 마이그레이션을 참조하세요.

원격 오브젝트 스토리지로 마이그레이션#

LFS 오브젝트를 수동으로 마이그레이션하려면:

Linux 패키지 (Omnibus):

sudo gitlab-rake "gitlab:lfs:migrate"

직접 컴파일한 경우:

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

Helm 차트 (쿠버네티스):

kubectl exec -it <toolbox-pod-name> -- gitlab-rake "gitlab:lfs:migrate"

Docker:

docker exec -it <container> gitlab-rake "gitlab:lfs:migrate"

PostgreSQL에서 마이그레이션 상태를 확인하려면:

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 objectstorage FROM lfs_objects;

로컬 스토리지로 다시 마이그레이션#

LFS 오브젝트를 원격 오브젝트 스토리지에서 로컬 스토리지로 다시 마이그레이션하려면:

Linux 패키지 (Omnibus):

sudo gitlab-rake "gitlab:lfs:migrate_to_local"

직접 컴파일한 경우:

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

Helm 차트 (쿠버네티스):

kubectl exec -it <toolbox-pod-name> -- gitlab-rake "gitlab:lfs:migrate_to_local"

Docker:

docker exec -it <container> gitlab-rake "gitlab:lfs:migrate_to_local"

순수 SSH 프로토콜로 LFS 사용#

히스토리

GitLab 17.2에서 도입.

이 기능을 활성화하려면:

Linux 패키지 (Omnibus):

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

gitlab_rails['lfs_pure_ssh_protocol'] = true

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

직접 컴파일한 경우:

gitlab.yml을 편집합니다:

lfs:
  enabled: true
  pure_ssh_protocol: true

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

# GitLab systemd 서비스를 사용하는 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 경우
sudo service gitlab restart

Helm 차트 (쿠버네티스):

gitlab.yaml 파일에서 값을 내보냅니다:

helm get values gitlab -n <namespace> > gitlab.yaml

global.appConfig.lfs를 업데이트합니다:

global:
  appConfig:
    lfs:
      pureSshProtocol: true

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

helm upgrade gitlab gitlab/gitlab \
  --namespace <namespace> \
  -f gitlab.yaml

Docker:

환경 변수를 설정합니다:

docker run ... \
  -e GITLAB_LFS_PURE_SSH_PROTOCOL=true \
  ...

순수 SSH 프로토콜의 제한 사항#

순수 SSH 프로토콜은 SSH 키 인증이 있는 사용자에게만 작동합니다.
암호 인증은 지원되지 않습니다.
deploy token을 사용한 인증은 지원되지 않습니다.
순수 SSH 프로토콜은 Git LFS 클라이언트 버전 3.0 이상이 필요합니다.
--skip-smudge 없이 서브모듈을 사용하면 예기치 않게 실패할 수 있습니다.

스토리지 통계#

프로젝트의 LFS 파일 크기를 포함한 스토리지 통계는 프로젝트 페이지의 설정 탭에서 확인할 수 있습니다.

문제 해결#

누락된 LFS 오브젝트#

누락된 LFS 오브젝트를 확인하려면:

sudo gitlab-rake gitlab:lfs:check

데이터베이스의 LFS 오브젝트와 스토리지 파일 간의 불일치를 찾습니다. 참조가 없는 LFS 오브젝트를 제거하려면 Rails 콘솔에서 다음을 실행합니다:

# 스토리지에 파일이 없는 모든 LFS 오브젝트 찾기
LfsObject.find_each do |lfs_object|
  lfs_object.destroy unless lfs_object.file.exists?
end

여러 누락된 LFS 오브젝트 제거#

여러 누락된 LFS 오브젝트가 있는 경우 Rails 콘솔을 사용합니다:

# 파일이 없는 LFS 오브젝트 찾기 (배치로 처리)
deleted = 0
LfsObject.find_each do |lfs_object|
  unless lfs_object.file.file.exists?
    lfs_object.destroy
    deleted += 1
    puts "Deleted #{deleted}" if deleted % 100 == 0
  end
end
puts "Total deleted: #{deleted}"

이 명령은 데이터베이스에서 참조되는 오브젝트 수에 따라 시간이 걸릴 수 있습니다. 배치 모드로 실행하는 것이 좋습니다:

# Rails 콘솔에서 배치 처리
LfsObject.all.each_batch do |objects|
  objects.each do |object|
    begin
      object.file.file.exists?
    rescue Errno::ENOENT
      object.destroy
    end
  end
end

TLS v1.3 오류#

LFS에서 TLS v1.3을 사용할 때 문제가 발생하는 경우:

/etc/gitlab/gitlab.rb에 다음을 추가하여 TLS 버전을 조정합니다:
```
nginx['ssl_protocols'] = "TLSv1.2 TLSv1.3"
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

연결 거부 오류#

LFS 연결 거부 오류가 발생하는 경우:

GitLab 서비스가 실행 중인지 확인합니다:
```
sudo gitlab-ctl status
```
GitLab 로그에서 오류를 확인합니다:
```
sudo gitlab-ctl tail gitlab-workhorse
```

PDF 파일에 대한 CORS 오류#

PDF 파일을 볼 때 CORS 오류가 발생하면:

LFS 오브젝트 스토리지에 CORS가 올바르게 구성되어 있는지 확인합니다.
오브젝트 스토리지 버킷에서 GitLab 도메인에 대한 CORS를 허용합니다.

포크가 LFS 오브젝트에 멈춤#

저장소 포크가 LFS 오브젝트 복사 시 멈추는 경우 GITLAB_LFS_MAX_OID_TO_FETCH 환경 변수로 제한을 조정할 수 있습니다:

Linux 패키지 (Omnibus):

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

gitlab_rails['env'] = { 'GITLAB_LFS_MAX_OID_TO_FETCH' => '100' }

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

기본값은 100이며, 이 값을 줄이면 더 작은 배치로 LFS 오브젝트를 가져옵니다.

Git Large File Storage (LFS)

LFS 요구 사항#

LFS 활성화 또는 비활성화#

LFS 로컬 스토리지 위치 변경#

원격 오브젝트 스토리지로 마이그레이션#

원격 오브젝트 스토리지로 마이그레이션#

로컬 스토리지로 다시 마이그레이션#

순수 SSH 프로토콜로 LFS 사용#

순수 SSH 프로토콜의 제한 사항#

스토리지 통계#

관련 항목#

문제 해결#

누락된 LFS 오브젝트#

여러 누락된 LFS 오브젝트 제거#

TLS v1.3 오류#

연결 거부 오류#

PDF 파일에 대한 CORS 오류#

포크가 LFS 오브젝트에 멈춤#

Git Large File Storage (LFS)

LFS 요구 사항#

LFS 활성화 또는 비활성화#

LFS 로컬 스토리지 위치 변경#

원격 오브젝트 스토리지로 마이그레이션#

원격 오브젝트 스토리지로 마이그레이션#

로컬 스토리지로 다시 마이그레이션#

순수 SSH 프로토콜로 LFS 사용#

순수 SSH 프로토콜의 제한 사항#

스토리지 통계#

관련 항목#

문제 해결#

누락된 LFS 오브젝트#

여러 누락된 LFS 오브젝트 제거#

TLS v1.3 오류#

연결 거부 오류#

PDF 파일에 대한 CORS 오류#

포크가 LFS 오브젝트에 멈춤#