GitLab 복원

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

GitLab은 전체 설치를 복원하기 위한 명령줄 인터페이스를 제공하며, 사용자의 필요에 맞게 유연하게 작동합니다.

복원 사전 조건 섹션에는 중요한 정보가 포함되어 있습니다. 프로덕션 환경에서 진행하기 전에 반드시 전체 복원 프로세스를 한 번 이상 읽고 테스트해야 합니다.

복원 사전 조건

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

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

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

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

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

GitLab 비밀 정보를 복원해야 함

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

복원하려면:

일부 GitLab 구성은 원본 백업 환경과 일치해야 함

이전에 사용했던 /etc/gitlab/gitlab.rb(리눅스 패키지 설치용) 또는 /home/git/gitlab/config/gitlab.yml(자체 컴파일 설치용) 및 TLS 키, 인증서(/etc/gitlab/ssl, /etc/gitlab/trusted-certs) 또는 SSH 호스트 키를 복원해야 합니다.

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

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

마운트 포인트인 디렉터리의 복원

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

NFS 마운트 구성에 대한 자세한 내용을 확인하세요.

리눅스 패키지 설치용 복원

이 절차는 다음을 전제로 합니다:

  • 백업이 생성된 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

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

GitLab 버전 불일치:
  현재 GitLab 버전(16.5.0-ee)이 백업 파일의 GitLab 버전과 다릅니다!
  다음 버전으로 전환한 후 다시 시도하세요:
  버전: 16.4.3-ee

올바른 GitLab 버전을 설치한 다음 다시 시도하세요.

경고: 복원 명령은 PgBouncer를 사용하는 설치에 대해 추가 매개변수가 필요합니다(성능상의 이유 또는 Patroni 클러스터와 함께 사용하는 경우).

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

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

GitLab 13.1 이상에서는 데이터베이스 값이 현재 비밀 정보를 사용하여 복호화될 수 있는지 특히 확인하세요. 특히 /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

Docker 이미지 및 GitLab Helm 차트 설치를 위한 복원

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

이러한 설치 유형에 대해, 백업 tarball은 백업 위치(default 위치는 /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

자세한 내용은 issue 6846를 참조하세요.

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

# 데이터베이스에 연결된 프로세스를 중지합니다
docker exec -it <container 이름> gitlab-ctl stop puma
docker exec -it <container 이름> gitlab-ctl stop sidekiq

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

# 복원을 실행합니다. 참고: 백업 이름에 "_gitlab_backup.tar"은 생략됩니다
docker exec -it <container 이름> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce

# GitLab 컨테이너를 재시작합니다
docker restart <container 이름>

# GitLab을 확인합니다
docker exec -it <container 이름> 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초
[...]
- Fixture events 불러오는 중...[완료]
- Fixture issues 불러오는 중...[완료]
- Fixture keys 불러오는 중...[스킵]
- Fixture merge_requests 불러오는 중...[완료]
- Fixture milestones 불러오는 중...[완료]
- Fixture namespaces 불러오는 중...[완료]
- Fixture notes 불러오는 중...[완료]
- Fixture projects 불러오는 중...[완료]
- Fixture protected_branches 불러오는 중...[스킵]
- Fixture schema_migrations 불러오는 중...[완료]
- Fixture services 불러오는 중...[스킵]
- Fixture snippets 불러오는 중...[스킵]
- Fixture taggings 불러오는 중...[스킵]
- Fixture tags 불러오는 중...[스킵]
- Fixture users 불러오는 중...[완료]
- Fixture users_projects 불러오는 중...[완료]
- Fixture web_hooks 불러오는 중...[스킵]
- 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로 시작하는 네이밍 스키마를 사용합니다. 여러 개의 백업이 존재할 때는 복원할 <백업-id>_gitlab_backup.tar 파일을 환경 변수 BACKUP=<백업-id>를 설정하여 지정해야 합니다.

복원하는 동안 프롬프트 비활성화

백업으로부터 복원하는 동안 복원 스크립트는 확인을 요청합니다:

  • 권한 있는 키에 쓰기 설정이 활성화된 경우, 복원 스크립트가 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 (테라폼 상태)
  • registry (컨테이너 레지스트리 이미지)
  • pages (페이지 콘텐츠)
  • repositories (Git 저장소 데이터)
  • packages (패키지)

특정 작업을 제외하려면:

  • Linux 패키지 설치: 

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

  • 자체 컴파일한 설치: 

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

특정 저장소 스토리지 복원

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

예를 들어:

  • Linux 패키지 설치: 

    sudo gitlab-backup restore BACKUP=<백업-id> REPOSITORIES_STORAGES=저장소1,저장소2

  • 자체 컴파일한 설치: 

    sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<백업-id> REPOSITORIES_STORAGES=저장소1,저장소2

특정 저장소 복원

REPOSITORIES_PATHS 및 SKIP_REPOSITORIES_PATHS 옵션을 사용하여 특정 저장소를 복원할 수 있습니다. 두 옵션은 프로젝트 및 그룹 경로의 쉼표로 구분된 목록을 받습니다. 그룹 경로를 지정하면 그 그룹과 하위 그룹의 모든 프로젝트의 모든 저장소가 해당 옵션에 따라 포함되거나 제외됩니다. 프로젝트 및 그룹 저장소는 지정된 백업 내에 존재해야 합니다.

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

  • Linux 패키지 설치: 

    sudo gitlab-backup restore 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=<백업-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d

압축 해제된 백업 복원

압축 해제된 백업(SKIP=tar로 만든)이 발견되고 BACKUP=<백업-id>로 백업을 선택하지 않은 경우, 압축 해제된 백업이 사용됩니다.

예를 들어:

  • Linux 패키지 설치: 

    sudo gitlab-backup restore

  • 자체 컴파일한 설치: 

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

문제 해결

다음은 가능한 문제들과 그에 대한 잠재적인 해결책들입니다.

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

더 많은 정보는 다음을 참조하십시오:

Git 서버 후크로 복원 실패

백업에서 복원하는 동안, 다음이 사실인 경우 오류가 발생할 수 있습니다:

  • GitLab 버전 15.10 및 그 이전을 사용하여 Git 서버 후크(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 이상에 대해 Git 서버 후크를 업데이트하고 새로운 백업을 만들 수 있습니다.

fapolicyd를 사용하여 복원 후 저장소가 비어 있는 것으로 보이는 성공적인 복원

보안을 강화하기 위해 fapolicyd를 사용하는 경우, GitLab은 복원이 성공했지만 저장소가 비어 있는 것으로 보고할 수 있습니다. 더 많은 문제 해결 도움말은 Gitaly 문제 해결 문서를 참조하십시오.