GitLab 복원 작업은 시스템 연속성을 유지하고 데이터 손실에서 복구하기 위해 백업에서 데이터를 복구합니다. 복원 작업:

• 데이터베이스 레코드 및 구성 복구
• Git 저장소, 컨테이너 레지스트리 이미지 및 업로드된 콘텐츠 복원
• 패키지 레지스트리 데이터 및 CI/CD 아티팩트 복원
• 계정 및 그룹 설정 복원
• 프로젝트 및 그룹 위키 복구
• 프로젝트 수준 보안 파일 복원
• 외부 병합 요청 차이점 복구

복원 프로세스에는 백업과 동일한 버전의 기존 GitLab 설치가 필요합니다. 전제 조건을 따르고 프로덕션에서 사용하기 전에 전체 복원 프로세스를 테스트하세요.

복원 전제 조건#

대상 GitLab 인스턴스가 이미 작동 중이어야 합니다#

복원을 수행하기 전에 작동 중인 GitLab 설치가 있어야 합니다. 이는 복원 작업을 수행하는 시스템 사용자(git)가 일반적으로 데이터를 가져오는 데 필요한 SQL 데이터베이스(gitlabhq_production)를 만들거나 삭제할 수 없기 때문입니다.

대상 GitLab 인스턴스에 기존 데이터가 없어야 합니다#

복원 프로세스는 데이터 유형에 따라 기존 데이터를 다르게 처리합니다:

• PostgreSQL 데이터는 복원 프로세스 중에 자동으로 지워집니다.
• Git 저장소: 같은 이름의 저장소가 이미 존재하면 복원이 "저장소가 이미 존재합니다" 오류로 실패합니다. 자세한 내용은 이슈 118459를 참조하세요.
• 파일 시스템 데이터는 복원 전에 별도의 디렉토리로 이동하려고 시도됩니다.
• 개체 저장소 데이터는 자동으로 지워지지 않습니다. 고아 데이터가 남지 않도록 복원 전에 개체 저장소 버킷을 수동으로 지워야 합니다.

예를 들어 프로덕션에서 스테이징으로 복원을 자동화할 때 신뢰할 수 있는 복원 프로세스를 위해 백업과 동일한 버전에서 새 GitLab 설치를 사용하세요.

SQL 데이터 복원은 PostgreSQL 확장이 소유한 뷰를 건너뜁니다.

대상 GitLab 인스턴스는 정확히 동일한 버전이어야 합니다#

백업이 생성된 것과 정확히 동일한 버전 및 유형(CE 또는 EE)의 GitLab에만 백업을 복원할 수 있습니다. 예를 들어 CE 15.1.4.

백업이 현재 설치와 다른 버전인 경우 백업을 복원하기 전에 GitLab 설치를 다운그레이드하거나 업그레이드해야 합니다.

GitLab 시크릿을 복원해야 합니다#

백업을 복원하려면 GitLab 시크릿도 복원해야 합니다. 새 GitLab 인스턴스로 마이그레이션하는 경우 이전 서버에서 GitLab 시크릿 파일을 복사해야 합니다. 여기에는 데이터베이스 암호화 키, CI/CD 변수 및 이중 인증에 사용되는 변수가 포함됩니다. 키 없이는 이중 인증이 활성화된 사용자의 액세스 손실, GitLab Runner 로그인 불가 등 여러 문제가 발생합니다.

설치 방법에 따라 다음을 복원합니다:

/etc/gitlab/gitlab-secrets.json

/srv/gitlab/config/gitlab-secrets.json

/home/git/gitlab/.secret

참고:

• CI/CD 변수
• 이중 인증
• 시크릿 문제 해결

특정 GitLab 구성은 원본 백업 환경과 일치해야 합니다#

이전 /etc/gitlab/gitlab.rb(Linux 패키지 설치용) 또는 /home/git/gitlab/config/gitlab.yml(소스 설치용) 및 TLS 또는 SSH 키와 인증서를 별도로 복원하고 싶을 것입니다.

특정 구성은 PostgreSQL의 데이터와 결합됩니다. 예를 들어:

• 원본 환경에 세 개의 저장소 스토리지가 있는 경우(예: default, my-storage-1, my-storage-2), 대상 환경에도 구성에 해당 스토리지 이름이 정의되어 있어야 합니다.
• 로컬 저장소를 사용하는 환경의 백업을 복원하면 대상 환경이 개체 저장소를 사용하더라도 로컬 저장소로 복원됩니다. 개체 저장소로의 마이그레이션은 복원 전이나 후에 수행해야 합니다.

자세한 내용은 백업에 포함되지 않은 데이터를 참조하세요.

마운트 포인트인 디렉토리로 복원#

마운트 포인트인 디렉토리로 복원하는 경우 복원을 시도하기 전에 이 디렉토리가 비어 있는지 확인해야 합니다. 그렇지 않으면 GitLab이 새 데이터를 복원하기 전에 이 디렉토리를 이동하려고 시도하여 오류가 발생합니다.

NFS 마운트 구성에 대해 자세히 알아보세요.

Linux 패키지 설치의 복원#

이 절차는 다음을 가정합니다:

• 백업이 생성된 것과 정확히 동일한 버전 및 유형(CE/EE)의 GitLab을 설치했습니다.
• sudo gitlab-ctl reconfigure를 최소한 한 번 실행했습니다.
• GitLab이 실행 중입니다. 그렇지 않은 경우 sudo gitlab-ctl start를 사용하여 시작합니다.

먼저 백업 tar 파일이 gitlab.rb 구성 gitlab_rails['backup_path']에 설명된 백업 디렉토리에 있는지 확인합니다. 기본값은 /var/opt/gitlab/backups입니다. 백업 파일은 git 사용자가 소유해야 합니다.

sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/
sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar

데이터베이스에 연결된 프로세스를 중지합니다. 나머지 GitLab은 계속 실행합니다:

sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# Verify
sudo gitlab-ctl status

다음으로 복원 전제 조건 단계를 완료했는지 확인하고 원본 설치에서 GitLab 시크릿 파일을 복사한 후 gitlab-ctl reconfigure를 실행했는지 확인합니다.

다음으로 복원할 백업의 ID를 지정하여 백업을 복원합니다:

# NOTE: "_gitlab_backup.tar" is omitted from the name
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

백업 tar 파일과 설치된 GitLab 버전 사이에 GitLab 버전 불일치가 있는 경우 복원 명령이 오류 메시지와 함께 중단됩니다:

GitLab version mismatch:
  Your current GitLab version (16.5.0-ee) differs from the GitLab version in the backup!
  Please switch to the following version and try again:
  version: 16.4.3-ee

올바른 GitLab 버전을 설치한 후 다시 시도합니다.

PostgreSQL 노드에서 재구성을 실행합니다:

sudo gitlab-ctl reconfigure

다음으로 GitLab을 시작하고 확인합니다:

sudo gitlab-ctl start
sudo gitlab-rake gitlab:check SANITIZE=true

특히 /etc/gitlab/gitlab-secrets.json이 복원되었거나 다른 서버가 복원 대상인 경우 데이터베이스 값을 해독할 수 있는지 확인합니다.

sudo gitlab-rake gitlab:doctor:secrets

추가 보증을 위해 업로드된 파일의 무결성 검사를 수행할 수 있습니다:

sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check

복원이 완료된 후 데이터베이스 성능을 개선하고 UI에서 불일치를 방지하기 위해 데이터베이스 통계를 생성하는 것이 좋습니다:

1. 데이터베이스 콘솔로 이동합니다.

2. 다음을 실행합니다:

   SET STATEMENT_TIMEOUT=0 ; ANALYZE VERBOSE;
   

명령을 복원 명령에 통합하는 것에 대한 논의가 이슈 276184에서 진행 중입니다.

복원 후 검증 가이드:

• GitLab 구성 확인
• 현재 시크릿을 사용하여 데이터베이스 값을 해독할 수 있는지 확인
• 업로드된 파일 무결성 검사:

Docker 이미지 및 GitLab Helm 차트 설치의 복원#

Kubernetes 클러스터에서 Docker 이미지 또는 GitLab Helm 차트를 사용하는 GitLab 설치의 경우 복원 작업은 복원 디렉토리가 비어 있을 것으로 예상합니다. 그러나 Docker 및 Kubernetes 볼륨 마운트를 사용하면 Linux 운영 체제에서 발견되는 lost+found 디렉토리와 같은 일부 시스템 수준 디렉토리가 볼륨 루트에 생성될 수 있습니다. 이러한 디렉토리는 일반적으로 root가 소유하고 있어 복원 Rake 작업이 git 사용자로 실행되므로 액세스 권한 오류가 발생할 수 있습니다. GitLab 설치를 복원하려면 사용자가 복원 대상 디렉토리가 비어 있는지 확인해야 합니다.

두 설치 유형 모두에서 백업 tarball은 백업 위치(기본 위치는 /var/opt/gitlab/backups)에서 사용할 수 있어야 합니다.

Helm 차트 설치의 복원#

GitLab Helm 차트는 GitLab Helm 차트 설치 복원에 문서화된 프로세스를 사용합니다.

Docker 이미지 설치의 복원#

Docker Swarm을 사용하는 경우 Puma가 종료되어 컨테이너 헬스 체크가 실패하기 때문에 복원 프로세스 중에 컨테이너가 다시 시작될 수 있습니다. 이 문제를 해결하려면 헬스 체크 메커니즘을 일시적으로 비활성화합니다.

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

   healthcheck:
     disable: true
   

2. 스택을 배포합니다:

   docker stack deploy --compose-file docker-compose.yml mystack
   

자세한 내용은 이슈 6846을 참조하세요.

복원 작업은 호스트에서 실행할 수 있습니다:

# Stop the processes that are connected to the database
docker exec -it <name of container> gitlab-ctl stop puma
docker exec -it <name of container> gitlab-ctl stop sidekiq

# Verify that the processes are all down before continuing
docker exec -it <name of container> gitlab-ctl status

# Run the restore. NOTE: "_gitlab_backup.tar" is omitted from the name
docker exec -it <name of container> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

# Restart the GitLab container
docker restart <name of container>

# Check GitLab
docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true

소스 설치의 복원#

1. 먼저 백업 tar 파일이 gitlab.yml 구성에 설명된 백업 디렉토리에 있는지 확인합니다:

   ## Backup settings
   backup:
     path: "tmp/backups"   # Relative paths are relative to Rails.root (default: tmp/backups/)
   

   기본값은 /home/git/gitlab/tmp/backups이며 git 사용자가 소유해야 합니다.

2. 백업 절차를 시작합니다:

   # Stop processes that are connected to the database
   sudo service gitlab stop
   
   sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
   

   예시 출력:

   Unpacking backup... [DONE]
   Restoring database tables:
   -- create_table("events", {:force=>true})
     -> 0.2231s
   [...]
   - Loading fixture events...[DONE]
   - Loading fixture issues...[DONE]
   - Loading fixture keys...[SKIPPING]
   - Loading fixture merge_requests...[DONE]
   - Loading fixture milestones...[DONE]
   - Loading fixture namespaces...[DONE]
   - Loading fixture notes...[DONE]
   - Loading fixture projects...[DONE]
   - Loading fixture protected_branches...[SKIPPING]
   - Loading fixture schema_migrations...[DONE]
   - Loading fixture services...[SKIPPING]
   - Loading fixture snippets...[SKIPPING]
   - Loading fixture taggings...[SKIPPING]
   - Loading fixture tags...[SKIPPING]
   - Loading fixture users...[DONE]
   - Loading fixture users_projects...[DONE]
   - Loading fixture web_hooks...[SKIPPING]
   - Loading fixture wikis...[SKIPPING]
   Restoring repositories:
   - Restoring repository abcd... [DONE]
   - Object pool 1 ...
   Deleting tmp directories...[DONE]
   

3. 필요한 경우 /home/git/gitlab/.secret을 복원합니다.

4. GitLab을 재시작합니다:

   sudo service gitlab restart
   

백업에서 하나 또는 일부 프로젝트 또는 그룹만 복원#

GitLab 인스턴스 복원에 사용되는 Rake 작업은 단일 프로젝트 또는 그룹 복원을 지원하지 않지만 별도의 임시 GitLab 인스턴스에 백업을 복원한 다음 거기서 프로젝트 또는 그룹을 내보내는 방법을 사용할 수 있습니다:

1. 복원할 백업 인스턴스와 동일한 버전에서 새 GitLab을 설치합니다.
2. 이 새 인스턴스에 백업을 복원한 후 프로젝트 또는 그룹을 내보냅니다. 내보내는 내용 및 내보내지 않는 내용에 대한 자세한 내용은 내보내기 기능 문서를 참조하세요.
3. 내보내기가 완료된 후 이전 인스턴스로 이동하여 가져옵니다.
4. 원하는 프로젝트 또는 그룹 가져오기가 완료된 후 새 임시 GitLab 인스턴스를 삭제할 수 있습니다.

개별 프로젝트 또는 그룹의 직접 복원을 제공하는 기능 요청이 이슈 #17517에서 논의되고 있습니다.

증분 저장소 백업 복원#

gitlab-backup을 사용하여 증분 저장소 백업을 만들면 결과 백업 아카이브에는 완전한 복원에 필요한 모든 저장소 데이터가 포함됩니다. 복원하려면 다른 일반 백업 아카이브 복원과 동일한 지침을 사용합니다.

내부적으로 증분 저장소 백업은 이전 백업 이후 변경된 내용만 저장합니다. 증분 백업을 만들 때 gitlab-backup은 원본 전체 백업부터 모든 단계를 백업 아카이브에 번들로 묶습니다. 이는 개별 저장소 백업 번들이 서로 의존하더라도 아카이브가 자체 포함됨을 의미합니다.

서버 측 저장소 백업을 사용하면 백업 아카이브에 저장소 데이터가 포함되지 않습니다. 대신 저장소 데이터는 각 Gitaly 노드에 의해 개체 저장소에 저장되고 각 증분은 별도의 개체로 저장됩니다. 서버 측 복원에서 Gitaly는 백업 매니페스트를 읽고 각 증분을 순서대로 적용합니다.

복원 옵션#

GitLab이 백업에서 복원하기 위해 제공하는 명령줄 도구는 더 많은 옵션을 수락할 수 있습니다.

여러 백업이 있을 때 복원할 백업 지정#

백업 파일은 백업 ID로 시작하는 명명 체계를 사용합니다. 여러 백업이 있을 때 BACKUP=<backup-id> 환경 변수를 설정하여 복원할 <backup-id>_gitlab_backup.tar 파일을 지정해야 합니다.

복원 중 프롬프트 비활성화#

백업에서 복원하는 동안 복원 스크립트는 확인을 요청합니다:

• authorized_keys에 쓰기 설정이 활성화된 경우 복원 스크립트가 authorized_keys 파일을 삭제하고 다시 빌드하기 전에.

• 데이터베이스를 복원할 때 복원 스크립트가 기존 테이블을 모두 제거하기 전에.
• 데이터베이스 복원 후 스키마 복원에 오류가 있는 경우 추가 문제가 발생할 가능성이 있으므로 계속하기 전에.

이러한 프롬프트를 비활성화하려면 GITLAB_ASSUME_YES 환경 변수를 1로 설정합니다.

• Linux 패키지 설치:

  sudo GITLAB_ASSUME_YES=1 gitlab-backup restore
  

• 소스 설치:

  sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production
  

force=yes 환경 변수도 이러한 프롬프트를 비활성화합니다.

복원 시 작업 제외#

SKIP 환경 변수를 추가하여 복원 시 특정 작업을 제외할 수 있습니다. 값은 다음 옵션의 쉼표로 구분된 목록입니다:

• db (데이터베이스)
• uploads (첨부 파일)
• builds (CI 작업 출력 로그)
• artifacts (CI 작업 아티팩트)
• lfs (LFS 개체)
• terraform_state (Terraform 상태)
• registry (컨테이너 레지스트리 이미지)
• pages (Pages 콘텐츠)
• repositories (Git 저장소 데이터)
• packages (패키지)

특정 작업을 제외하려면:

• Linux 패키지 설치:

  sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads
  

• 소스 설치:

  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production
  

특정 저장소 스토리지 복원#

여러 저장소 스토리지를 사용할 때 REPOSITORIES_STORAGES 옵션을 사용하여 특정 저장소 스토리지의 저장소를 별도로 복원할 수 있습니다. 이 옵션은 스토리지 이름의 쉼표로 구분된 목록을 허용합니다.

예를 들어:

• Linux 패키지 설치:

  sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
  

• 소스 설치:

  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
  

특정 저장소 복원#

REPOSITORIES_PATHS 및 SKIP_REPOSITORIES_PATHS 옵션을 사용하여 특정 저장소를 복원할 수 있습니다. 두 옵션 모두 프로젝트 및 그룹 경로의 쉼표로 구분된 목록을 허용합니다. 그룹 경로를 지정하면 그룹 및 하위 그룹의 모든 프로젝트의 모든 저장소가 포함되거나 사용한 옵션에 따라 건너뜁니다. 그룹과 프로젝트 모두 지정된 백업 또는 대상 인스턴스에 존재해야 합니다.

예를 들어 그룹 A(group-a)의 모든 프로젝트에 대한 모든 저장소를 복원하고 그룹 B의 프로젝트 C(group-b/project-c)의 저장소를 복원하고 그룹 A의 프로젝트 D(group-a/project-d)를 건너뛰려면:

• Linux 패키지 설치:

  sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
  

• 소스 설치:

  sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
  

압축되지 않은 백업 복원#

압축되지 않은 백업(SKIP=tar로 만들어진)이 발견되고 BACKUP=<backup-id>로 백업이 선택되지 않은 경우 압축되지 않은 백업이 사용됩니다.

예를 들어:

• Linux 패키지 설치:

  sudo gitlab-backup restore
  

• 소스 설치:

  sudo -u git -H bundle exec rake gitlab:backup:restore
  

서버 측 저장소 백업을 사용한 복원#

서버 측 백업이 수집되면 복원 프로세스는 기본적으로 서버 측 저장소 백업 생성에 표시된 서버 측 복원 메커니즘을 사용합니다. 각 저장소를 호스팅하는 Gitaly 노드가 개체 저장소에서 직접 필요한 백업 데이터를 가져올 수 있도록 백업 복원을 구성할 수 있습니다.

1. Gitaly에서 서버 측 백업 대상 구성.
2. 서버 측 백업 복원 프로세스를 시작하고 복원할 백업의 ID를 지정합니다:

sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=11493107454_2018_04_25_10.6.4-ce

kubectl exec  -it -- backup-utility --restore -t <backup_ID> --repositories-server-side

문제 해결#

다음은 발생할 수 있는 문제와 잠재적 해결 방법입니다.

Linux 패키지 설치의 출력 경고를 사용하여 데이터베이스 백업 복원#

백업 복원 절차를 사용하는 경우 다음 경고 메시지가 표시될 수 있습니다:

ERROR: must be owner of extension pg_trgm
ERROR: must be owner of extension btree_gist
ERROR: must be owner of extension plpgsql
WARNING:  no privileges could be revoked for "public" (two occurrences)
WARNING:  no privileges were granted for "public" (two occurrences)

이러한 경고 메시지에도 불구하고 백업이 성공적으로 복원되었음을 알아두세요.

Rake 작업은 데이터베이스에 대한 수퍼유저 액세스가 없는 gitlab 사용자로 실행됩니다. 복원이 시작될 때도 gitlab 사용자로 실행되지만 액세스 권한이 없는 개체를 변경하려고 시도합니다. 이러한 개체는 데이터베이스 백업 또는 복원에 영향을 미치지 않지만 경고 메시지를 표시합니다.

자세한 내용은 다음을 참조하세요:

• PostgreSQL 이슈 트래커:
  • 수퍼유저가 아닌 경우.
  • 소유자가 다른 경우.
• Stack Overflow: 결과 오류.

Git 서버 훅으로 인한 복원 실패#

백업에서 복원하는 동안 다음 조건이 모두 충족되면 오류가 발생할 수 있습니다:

• Git 서버 훅(custom_hook)이 GitLab 버전 15.10 이하의 방법을 사용하여 구성됨
• GitLab 버전이 15.11 이상임
• GitLab 관리 위치 외부의 디렉토리에 심볼릭 링크를 만들었음

오류는 다음과 같습니다:

{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/_-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"}

이를 해결하려면 GitLab 버전 15.11 이상의 Git 서버 훅을 업데이트하고 새 백업을 만들 수 있습니다.

fapolicyd를 사용할 때 저장소가 비어 있는 것으로 표시되는 성공적인 복원#

보안 강화를 위해 fapolicyd를 사용할 때 GitLab이 복원이 성공적이라고 보고할 수 있지만 저장소는 비어 있는 것으로 표시됩니다. 자세한 문제 해결 도움말은 Gitaly 문제 해결 문서를 참조하세요.