GitLab 복원

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

GitLab은 전체 설치를 복원하기 위한 명령줄 인터페이스를 제공하며, 사용자의 요구에 유연하게 대응할 수 있습니다.

복원 사전 요구 사항에는 중요한 정보가 포함되어 있습니다. 복원 프로세스를 완전히 읽고 시험한 후에, 프로덕션 환경에서 실행하기 전에 최소한 한 번은 시도해 보세요.

복원 사전 요구 사항

대상 GitLab 인스턴스는 이미 작동 중이어야 함

복원을 수행하기 전에 작동 중인 GitLab 설치본이 있어야 합니다. 이는 복원 작업을 수행하는 시스템 사용자인 git이 일반적으로 데이터를 가져올 SQL 데이터베이스를 생성하거나 삭제할 수 없기 때문입니다. 모든 기존 데이터(SQL)는 삭제되거나(데이터베이스) 별도의 디렉터리(예: 저장소 및 업로드)로 이동합니다. SQL 데이터의 복원은 PostgreSQL 확장에서 소유한 뷰를 건너뜁니다.

대상 GitLab 인스턴스는 정확히 동일한 버전이어야 함

백업은 만들어진 GitLab의 정확히 동일한 버전 및 유형(CE 또는 EE)에만 복원할 수 있습니다. 예를 들어 CE 15.1.4입니다.

백업이 현재 설치된 버전과 다른 버전인 경우, 복원하기 전에 다운그레이드 또는 업그레이드를 진행해야 합니다.

GitLab 비밀 정보를 복원해야 함

백업을 복원하려면 GitLab 비밀 정보도 복원해야 합니다. 이는 데이터베이스 암호화 키, CI/CD 변수 및 이중 인증용 변수를 포함합니다. 키가 없으면 여러 문제가 발생합니다, 이중 인증이 활성화된 사용자가 액세스 권한을 상실하고, GitLab 러너가 로그인할 수 없습니다.

복원:

특정 GitLab 구성이 원본 백업된 환경과 일치해야 함

일반적으로 이전의 /etc/gitlab/gitlab.rb (Linux 패키지 설치) 또는 /home/git/gitlab/config/gitlab.yml (자체 컴파일된 설치) 및 TLS 키, 인증서 (/etc/gitlab/ssl, /etc/gitlab/trusted-certs) 또는 SSH 호스트 키를 복원할 수 있어야 합니다.

일부 구성은 PostgreSQL의 데이터와 연결되어 있습니다. 예를 들어:

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

마운트 지점인 디렉터리 복원

마운트 지점인 디렉터리에 복원해야 하는 경우, 이러한 디렉터리가 복원하기 전에 비어 있어야 합니다. 그렇지 않으면 GitLab은 새 데이터를 복원하기 전에 이러한 디렉터리를 이동하려고 하기 때문에 오류가 발생합니다.

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

Linux 패키지 설치용 복원

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

  • 백업 생성 시 사용한 GitLab의 정확히 동일한 버전 및 유형(CE/EE)을 설치했음.
  • 적어도 한 번 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
# 확인
sudo gitlab-ctl status

다음으로 복원 사전 요구 사항을 완료했는지 확인하고, 원본 설치에서 GitLab 비밀 정보 파일을 복사한 후 gitlab-ctl reconfigure을 실행하세요.

그런 다음 복원을 수행하고 복원할 백업 ID를 지정하세요.

경고: 다음 명령은 GitLab 데이터베이스의 내용을 덮어쓸 수 있습니다! 

# 참고: "_gitlab_backup.tar"은 명령어에서 빠짐
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

백업된 백업 타 파일과 설치된 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 버전으로 설치한 후 다시 시도하세요.

경고: 복원 명령에는 추가 매개변수가 필요할 수 있습니다. PgBouncer를 사용중인 경우 설치하는 경우, 성능 문제 또는 Patroni 클러스터와 사용하는 경우.

다음으로 GitLab을 재시작하고 확인하세요: 

sudo gitlab-ctl restart
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 Helm 차트 설치를 위한 복원

도커 이미지나 Kubernetes 클러스터의 GitLab Helm 차트를 사용하여 GitLab을 설치하는 경우, 복원 작업은 복원 디렉토리가 비어 있어야 합니다. 그러나 도커 및 Kubernetes 볼륨 마운트에서는 Linux 운영 체제에서 발견되는 lost+found 디렉토리와 같은 시스템 레벨의 디렉토리가 볼륨 루트에 생성될 수 있습니다. 이러한 디렉토리들은 보통 root 소유이며, 이는 복원 Rake 작업이 git 사용자로 실행되기 때문에 액세스 권한 오류를 일으킬 수 있습니다. GitLab 설치를 복원하려면 사용자는 복원 대상 디렉토리가 비어 있는지 확인해야 합니다.

이러한 설치 유형의 경우, 백업 tarball은 백업 위치(default 위치는 /var/opt/gitlab/backups)에 있어야 합니다.

Helm 차트 설치를 위한 복원

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

도커 이미지 설치를 위한 복원

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

  1. docker-compose.yml 편집: 

    healthcheck:
  disable: true

  2. 스택 배포: 

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

더 많은 정보는 issue 6846를 참조하세요.

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

# 데이터베이스에 연결된 프로세스 중지
docker exec -it <컨테이너 이름> gitlab-ctl stop puma
docker exec -it <컨테이너 이름> gitlab-ctl stop sidekiq

# 계속하기 전에 모든 프로세스가 중지되었는지 확인
docker exec -it <컨테이너 이름> gitlab-ctl status

# 복원 실행. 참고: 이름에서 "_gitlab_backup.tar"는 생략됨
docker exec -it <컨테이너 이름> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

# GitLab 컨테이너 재시작
docker restart <컨테이너 이름>

# GitLab 확인
docker exec -it <컨테이너 이름> gitlab-rake gitlab:check SANITIZE=true

자체 컴파일 설치를 위한 복원

먼저, 백업 tar 파일이 gitlab.yml 구성에 설명된 백업 디렉터리에 있는지 확인하세요: 

## 백업 설정
backup:
  path: "tmp/backups"   # 상대적인 경로는 Rails.root에 대한 상대적인 경로입니다 (기본값: tmp/backups/)

기본값은 /home/git/gitlab/tmp/backups이며, 이는 git 사용자가 소유해야 합니다. 이제 백업 절차를 시작할 수 있습니다: 

# 데이터베이스에 연결된 프로세스 중지
sudo service gitlab stop

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

예시 출력: 

백업 풀기... [완료]
데이터베이스 테이블 복원:
-- create_table("events", {:force=>true})
   -> 0.2231초
[...]
- Loading fixture events...[완료]
- Loading fixture issues...[완료]
- Loading fixture keys...[스킵]
- Loading fixture merge_requests...[완료]
- Loading fixture milestones...[완료]
- Loading fixture namespaces...[완료]
- Loading fixture notes...[완료]
- Loading fixture projects...[완료]
- Loading fixture protected_branches...[스킵]
- Loading fixture schema_migrations...[완료]
- Loading fixture services...[스킵]
- Loading fixture snippets...[스킵]
- Loading fixture taggings...[스킵]
- Loading fixture tags...[스킵]
- Loading fixture users...[완료]
- Loading fixture users_projects...[완료]
- Loading fixture web_hooks...[스킵]
- Loading fixture wikis...[스킵]
저장소 복원:
- 저장소 복원 abcd... [완료]
- Object pool 1 ...
tmp 디렉터리 삭제...[완료]

그 다음, 필요한 경우 /home/git/gitlab/.secret를 복원하세요. 이전에 언급된 것.

GitLab 재시작: 

sudo service gitlab restart

백업에서 하나 또는 여러 프로젝트 또는 그룹만 복원

GitLab 인스턴스를 복원하는 데 사용되는 Rake 작업은 단일 프로젝트나 그룹을 복원하는 것을 지원하지 않지만, 복원을 위해 별도의 임시 GitLab 인스턴스로 백업을 복원하고, 거기에서 프로젝트나 그룹을 내보내는 작업으로 우회할 수 있습니다:

  1. 복원하려는 백업과 동일한 버전의 GitLab을 새로 설치하세요.
  2. 백업을 이러한 새 인스턴스로 복원하고, 그런 다음 여기서 프로젝트나 그룹을 내보내세요. 무엇을 내보내고, 내보내지 않는 지에 대한 자세한 내용은 내보내기 기능의 문서를 참조하세요.
  3. 내보내기가 완료되면 이를 이전 인스턴스로 가져가세요.
  4. 원하는 프로젝트나 그룹을 가져온 후, 새로운 임시 GitLab 인스턴스를 삭제할 수 있습니다.

개별 프로젝트나 그룹을 직접 복원하는 기능 요청은 issue #17517에서 논의 중입니다.

증분 저장소 백업 복원

각 백업 아카이브에는 증분 저장소 백업 절차를 통해 생성된 것을 포함하여 완전한 독립된 백업이 포함되어 있습니다. 증분 저장소 백업을 복원하려면 다른 정규 백업 아카이브를 복원하는 것과 동일한 지침을 사용하세요.

복원 옵션

GitLab에서 제공하는 명령줄 도구는 더 많은 옵션을 허용할 수 있습니다.

여러 개 있는 백업 중에서 복원할 백업 지정

백업 파일은 백업 ID로 시작하는 이름 체계를 사용합니다. 여러 개의 백업이 존재하는 경우, 환경 변수 BACKUP=<백업 ID>를 설정하여 복원할 <백업 ID>_gitlab_backup.tar 파일을 지정해야 합니다.

복원 중 프롬프트 비활성화

백업에서 복원 중에는 복원 스크립트가 확인을 요청합니다.

  • Write to authorized_keys 설정이 활성화된 경우, 복원 스크립트가 authorized_keys 파일을 삭제하고 다시 작성하기 전에
  • 데이터베이스를 복원할 때, 복원 스크립트가 모든 기존 테이블을 삭제하기 전에
  • 데이터베이스를 복원한 후, 스키마 복원 중 오류가 있었을 경우, 추가 문제가 발생할 가능성을 고려하여 진행하기 전에

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

  • 리눅스 패키지 설치: 

    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 (테라폼 상태)
  • registry (컨테이너 레지스트리 이미지)
  • pages (페이지 콘텐츠)
  • repositories (Git 저장소 데이터)
  • packages (패키지)

특정 작업을 제외하려면 다음과 같이합니다:

  • 리눅스 패키지 설치: 

    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

특정 저장소 저장소 복원

경고: GitLab 17.1 및 이전 버전에는 데이터 손실을 유발할 수 있는 경쟁 조건이 영향을 미칩니다. 이 문제는 분기되어 GitLab 오브젝트 풀을 사용하는 저장소에 영향을 미칩니다. 데이터 손실을 피하려면 GitLab 17.2 이상에서만 백업을 복원하세요.

다중 저장소 경로를 사용할 때, 특정 저장소 저장소에서 저장소를 별도로 복원할 수 있습니다. 이 옵션은 쉼표로 구분된 저장소 이름의 목록을 허용합니다.

예를들어:

  • 리눅스 패키지 설치: 

    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

특정 저장소 복원

경고: GitLab 17.1 및 이전 버전에는 데이터 손실을 유발할 수 있는 경쟁 조건이 영향을 미칩니다. 이 문제는 분기되어 GitLab 오브젝트 풀을 사용하는 저장소에 영향을 미칩니다. 데이터 손실을 피하려면 GitLab 17.2 이상에서만 백업을 복원하세요.

REPOSITORIES_PATHS 및 SKIP_REPOSITORIES_PATHS 옵션을 사용하여 특정 저장소를 복원하거나 제외할 수 있습니다. 이러한 옵션은 프로젝트 및 그룹 경로의 쉼표로 구분된 목록을 허용하며, 특정 백업에 있는 프로젝트 및 그룹의 모든 저장소가 포함되거나 제외됩니다.

참고: REPOSITORIES_PATHS 및 SKIP_REPOSITORIES_PATHS 옵션은 Git 저장소에만 적용됩니다. 이러한 옵션에 관계없이 모든 프로젝트 및 기타 데이터가 복원됩니다.

예를들어, 그룹 A (group-a)의 모든 프로젝트에 대한 모든 저장소, 그룹 B (group-b)의 프로젝트 C의 저장소를 복원하고, 그룹 A (group-a)의 프로젝트 D를 제외하려면:

  • 리눅스 패키지 설치: 

    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

압축 해제된 백업 복원

압축을 건너뛰고 만든 압축 해제된 백업이 있고 BACKUP=<backup-id>로 백업을 선택하지 않은 경우, 압축 해제된 백업이 사용됩니다.

예를들어:

  • 리눅스 패키지 설치: 

    sudo gitlab-backup restore

  • 자체 컴파일 설치: 

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

문제 해결

다음은 가능한 문제와 해결 방법입니다.

리눅스 패키지 설치에서의 데이터베이스 백업 복원 및 경고 메시지

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

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’ 사용자로 실행됩니다. 따라서 복원이 시작되면 ‘gitlab’ 사용자로 실행되며, 액세스할 수 없는 개체를 변경하려고합니다. 이러한 개체는 데이터베이스 백업이나 복원에 영향을주지 않지만 경고 메시지가 표시됩니다.

자세한 정보는 다음을 참조하세요:

Git 서버 후크로 인한 복원 실패

백업에서 복원하는 동안 다음 조건이 참일 때 오류가 발생할 수 있습니다.

  • GitLab 버전 15.10 이전을 사용하여 custom_hook이 구성된 경우
  • 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/<BackupID>_<GitLabVersion>-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 이상을 위해 서버 후크를 업데이트하고 새로운 백업을 생성할 수 있습니다.

fapolicyd를 사용할 때 빈 저장소로 표시된 복원 성공

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