머지 리퀘스트 diff 스토리지

요약

머지 리퀘스트 diff는 머지 리퀘스트에 연결된 diff를 크기 제한을 두고 복사해 둔 사본입니다. 기본적으로 GitLab은 머지 리퀘스트 diff를 데이터베이스의 merge_request_diff_files 테이블에 저장합니다.

머지 리퀘스트 diff는 머지 리퀘스트에 연결된 diff를 크기 제한을 두고 복사해 둔 사본입니다. 머지 리퀘스트를 볼 때는 성능 최적화를 위해 가능한 한 이 사본에서 diff를 가져옵니다.

기본적으로 GitLab은 머지 리퀘스트 diff를 데이터베이스의 merge_request_diff_files 테이블에 저장합니다. 규모가 큰 설치 환경에서는 이 테이블이 지나치게 커질 수 있으며, 그럴 때는 외부 스토리지로 전환합니다.

머지 리퀘스트 diff는 다음 방식으로 저장할 수 있습니다.

전부 디스크에 저장합니다.
전부 오브젝트 스토리지에 저장합니다.
현재 diff는 데이터베이스에, 오래된 diff는 오브젝트 스토리지에 저장합니다.

외부 스토리지 사용#

/etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_enabled'] = true
```
외부 diff는 /var/opt/gitlab/gitlab-rails/shared/external-diffs에 저장됩니다. 경로를 변경하려면, 예를 들어 /mnt/storage/external-diffs로 변경하려면 /etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs"
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다. 그러면 GitLab 이 기존 머지 리퀘스트 diff를 외부 스토리지로 마이그레이션합니다.

/home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
```
외부 diff는 /home/git/gitlab/shared/external-diffs에 저장됩니다. 경로를 변경하려면, 예를 들어 /mnt/storage/external-diffs로 변경하려면 /home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
  storage_path: /mnt/storage/external-diffs
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재시작합니다. 그러면 GitLab 이 기존 머지 리퀘스트 diff를 외부 스토리지로 마이그레이션합니다.

오브젝트 스토리지 사용#

Warning

오브젝트 스토리지로의 마이그레이션은 되돌릴 수 없습니다.

외부 diff를 디스크에 저장하는 대신 AWS S3 같은 오브젝트 스토어를 사용하는 편이 좋습니다. 이 구성은 미리 구성된 유효한 AWS 자격 증명을 전제로 합니다.

Note

통합 오브젝트 스토리지 설정에서 외부 diff 용 오브젝트 스토리지를 구성하더라도 머지 리퀘스트 diff의 외부 스토리지가 자동으로 활성화되지는 않습니다. external_diffs_enabled를 true로 명시적으로 설정해야 합니다.

외부 diff 용 오브젝트 스토리지를 구성하려면 다음 단계를 따릅니다.

/etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_enabled'] = true
```
통합 오브젝트 스토리지 설정을 구성합니다.
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

/home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
```
통합 오브젝트 스토리지 설정을 구성합니다.
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재시작합니다.

GitLab을 재구성하거나 재시작하면 기존 머지 리퀘스트 diff가 외부 스토리지로 마이그레이션됩니다.

자세한 내용은 오브젝트 스토리지를 참고합니다.

대안: 데이터베이스 내 저장#

외부 diff를 활성화하면 diff를 다른 데이터와 별도의 작업으로 가져와야 하므로 머지 리퀘스트 성능이 낮아질 수 있습니다. 현재 diff는 데이터베이스에 두고 오래된 diff만 외부에 저장하는 방식으로 절충할 수 있습니다.

이 기능을 활성화하려면 다음 단계를 수행합니다.

/etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_when'] = 'outdated'
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

/home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
  when: outdated
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재시작합니다.

이 기능을 활성화하면 diff는 외부가 아니라 먼저 데이터베이스에 저장됩니다. 그리고 다음 조건 중 하나가 충족되면 외부 스토리지로 이동합니다.

머지 리퀘스트 diff의 더 최신 버전이 존재합니다
머지 리퀘스트가 7일보다 전에 병합되었습니다
머지 리퀘스트가 7일보다 전에 닫혔습니다

이 규칙은 자주 조회되는 diff만 데이터베이스에 두어 공간과 성능 사이의 균형을 맞춥니다. 조회 가능성이 낮은 diff는 외부 스토리지로 이동합니다.

외부 스토리지에서 오브젝트 스토리지로 전환#

자동 마이그레이션은 데이터베이스에 저장된 diff를 옮기지만, 스토리지 유형 사이에서는 diff를 옮기지 않습니다. 외부 스토리지에서 오브젝트 스토리지로 전환하려면 다음 단계를 따릅니다.

로컬 또는 NFS 스토리지에 저장된 파일을 오브젝트 스토리지로 직접 옮깁니다.
다음 Rake 태스크를 실행해 데이터베이스상의 위치를 변경합니다.

Linux 패키지 설치의 경우:
```
sudo gitlab-rake gitlab:external_diffs:force_object_storage
```
자체 컴파일 설치의 경우:
```
sudo -u git -H bundle exec rake gitlab:external_diffs:force_object_storage RAILS_ENV=production
```
기본적으로 sudo는 기존 환경 변수를 유지하지 않습니다. 환경 변수는 앞이 아니라 뒤에 붙입니다.
```
sudo gitlab-rake gitlab:external_diffs:force_object_storage START_ID=59946109 END_ID=59946109 UPDATE_DELAY=5
```

다음 환경 변수가 Rake 태스크의 동작을 바꿉니다.

이름	기본값	목적
`ANSI`	`true`	ANSI 이스케이프 코드를 사용해 출력을 더 이해하기 쉽게 만듭니다.
`BATCH_SIZE`	`1000`	이 크기의 배치로 테이블을 순회합니다.
`START_ID`	`nil`	설정하면 이 ID부터 스캔을 시작합니다.
`END_ID`	`nil`	설정하면 이 ID에서 스캔을 중지합니다.
`UPDATE_DELAY`	`1`	업데이트 사이에 대기할 시간(초)입니다.

START_ID와 END_ID를 사용하면 테이블의 서로 다른 구간을 서로 다른 프로세스에 할당해 업데이트를 병렬로 실행할 수 있습니다.
BATCH와 UPDATE_DELAY로 마이그레이션 속도와 테이블 동시 접근 사이의 균형을 조절할 수 있습니다.
터미널이 ANSI 이스케이프 코드를 지원하지 않으면 ANSI를 false로 설정합니다.

오브젝트 스토리지와 로컬 스토리지 사이의 외부 diff 분포를 확인하려면 다음 SQL 쿼리를 사용합니다.

gitlabhq_production=# SELECT count(*) AS total,
  SUM(CASE
    WHEN external_diff_store = '1' THEN 1
    ELSE 0
  END) AS filesystem,
  SUM(CASE
    WHEN external_diff_store = '2' THEN 1
    ELSE 0
  END) AS objectstg
FROM merge_request_diffs;

머지 리퀘스트 diff 스토리지

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

머지 리퀘스트 diff는 다음 방식으로 저장할 수 있습니다.

전부 디스크에 저장합니다.
전부 오브젝트 스토리지에 저장합니다.
현재 diff는 데이터베이스에, 오래된 diff는 오브젝트 스토리지에 저장합니다.

외부 스토리지 사용#

/etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_enabled'] = true
```
외부 diff는 /var/opt/gitlab/gitlab-rails/shared/external-diffs에 저장됩니다. 경로를 변경하려면, 예를 들어 /mnt/storage/external-diffs로 변경하려면 /etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_storage_path'] = "/mnt/storage/external-diffs"
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다. 그러면 GitLab 이 기존 머지 리퀘스트 diff를 외부 스토리지로 마이그레이션합니다.

/home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
```
외부 diff는 /home/git/gitlab/shared/external-diffs에 저장됩니다. 경로를 변경하려면, 예를 들어 /mnt/storage/external-diffs로 변경하려면 /home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
  storage_path: /mnt/storage/external-diffs
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재시작합니다. 그러면 GitLab 이 기존 머지 리퀘스트 diff를 외부 스토리지로 마이그레이션합니다.

오브젝트 스토리지 사용#

Warning

오브젝트 스토리지로의 마이그레이션은 되돌릴 수 없습니다.

Note

외부 diff 용 오브젝트 스토리지를 구성하려면 다음 단계를 따릅니다.

/etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_enabled'] = true
```
통합 오브젝트 스토리지 설정을 구성합니다.
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

/home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
```
통합 오브젝트 스토리지 설정을 구성합니다.
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재시작합니다.

GitLab을 재구성하거나 재시작하면 기존 머지 리퀘스트 diff가 외부 스토리지로 마이그레이션됩니다.

자세한 내용은 오브젝트 스토리지를 참고합니다.

대안: 데이터베이스 내 저장#

이 기능을 활성화하려면 다음 단계를 수행합니다.

/etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['external_diffs_when'] = 'outdated'
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

/home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
external_diffs:
  enabled: true
  when: outdated
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재시작합니다.

이 기능을 활성화하면 diff는 외부가 아니라 먼저 데이터베이스에 저장됩니다. 그리고 다음 조건 중 하나가 충족되면 외부 스토리지로 이동합니다.

머지 리퀘스트 diff의 더 최신 버전이 존재합니다
머지 리퀘스트가 7일보다 전에 병합되었습니다
머지 리퀘스트가 7일보다 전에 닫혔습니다

이 규칙은 자주 조회되는 diff만 데이터베이스에 두어 공간과 성능 사이의 균형을 맞춥니다. 조회 가능성이 낮은 diff는 외부 스토리지로 이동합니다.

외부 스토리지에서 오브젝트 스토리지로 전환#

로컬 또는 NFS 스토리지에 저장된 파일을 오브젝트 스토리지로 직접 옮깁니다.
다음 Rake 태스크를 실행해 데이터베이스상의 위치를 변경합니다.

Linux 패키지 설치의 경우:
```
sudo gitlab-rake gitlab:external_diffs:force_object_storage
```
자체 컴파일 설치의 경우:
```
sudo -u git -H bundle exec rake gitlab:external_diffs:force_object_storage RAILS_ENV=production
```
기본적으로 sudo는 기존 환경 변수를 유지하지 않습니다. 환경 변수는 앞이 아니라 뒤에 붙입니다.
```
sudo gitlab-rake gitlab:external_diffs:force_object_storage START_ID=59946109 END_ID=59946109 UPDATE_DELAY=5
```

다음 환경 변수가 Rake 태스크의 동작을 바꿉니다.

이름	기본값	목적
`ANSI`	`true`	ANSI 이스케이프 코드를 사용해 출력을 더 이해하기 쉽게 만듭니다.
`BATCH_SIZE`	`1000`	이 크기의 배치로 테이블을 순회합니다.
`START_ID`	`nil`	설정하면 이 ID부터 스캔을 시작합니다.
`END_ID`	`nil`	설정하면 이 ID에서 스캔을 중지합니다.
`UPDATE_DELAY`	`1`	업데이트 사이에 대기할 시간(초)입니다.

START_ID와 END_ID를 사용하면 테이블의 서로 다른 구간을 서로 다른 프로세스에 할당해 업데이트를 병렬로 실행할 수 있습니다.
BATCH와 UPDATE_DELAY로 마이그레이션 속도와 테이블 동시 접근 사이의 균형을 조절할 수 있습니다.
터미널이 ANSI 이스케이프 코드를 지원하지 않으면 ANSI를 false로 설정합니다.

오브젝트 스토리지와 로컬 스토리지 사이의 외부 diff 분포를 확인하려면 다음 SQL 쿼리를 사용합니다.

gitlabhq_production=# SELECT count(*) AS total,
  SUM(CASE
    WHEN external_diff_store = '1' THEN 1
    ELSE 0
  END) AS filesystem,
  SUM(CASE
    WHEN external_diff_store = '2' THEN 1
    ELSE 0
  END) AS objectstg
FROM merge_request_diffs;