백업 아카이브 프로세스

요약

백업 명령을 실행하면 백업 스크립트가 GitLab 데이터를 저장할 백업 아카이브 파일을 생성합니다. 아카이브 파일을 생성하기 위해 백업 스크립트는 다음 작업을 수행합니다. 데이터베이스를 백업하기 위해 db 하위 작업은 다음 작업을 수행합니다.

백업 명령을 실행하면 백업 스크립트가 GitLab 데이터를 저장할 백업 아카이브 파일을 생성합니다.

아카이브 파일을 생성하기 위해 백업 스크립트는 다음 작업을 수행합니다.

증분 백업을 수행하는 경우 이전 백업 아카이브 파일의 압축을 풉니다.
백업 아카이브 파일을 업데이트하거나 새로 생성합니다.
다음 백업 하위 작업을 모두 실행합니다.
백업 스테이징 영역을 tar 파일로 아카이브합니다.
구성되어 있다면 새 백업 아카이브를 오브젝트 스토리지에 업로드합니다.
아카이브한 백업 스테이징 디렉터리의 파일을 정리합니다.

데이터베이스 백업#

데이터베이스를 백업하기 위해 db 하위 작업은 다음 작업을 수행합니다.

pg_dump로 SQL 덤프를 생성합니다.
pg_dump의 출력을 gzip으로 파이프해 압축된 SQL 파일을 만듭니다.
파일을 백업 스테이징 디렉터리에 저장합니다.

Git 리포지터리 백업#

Git 리포지터리를 백업하기 위해 repositories 하위 작업은 다음 작업을 수행합니다.

백업할 리포지터리를 gitaly-backup에 알립니다.
gitaly-backup을 실행해 다음 작업을 수행합니다.
- Gitaly에서 일련의 원격 프로시저 호출(RPC)을 수행합니다.
- 각 리포지터리의 백업 데이터를 수집합니다.
수집한 데이터를 백업 스테이징 디렉터리의 디렉터리 구조로 스트리밍합니다.

다음 다이어그램은 이 과정을 나타냅니다.

Mermaid 다이어그램 (24줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: Git repository backup workflow
    accDescr: Sequence diagram showing the repositories sub-task calling gitaly-backup with a list of repositories. For each repository, gitaly-backup uses RPCs to collect refs, create a bundle, and retrieve custom hooks. It then returns success or failure.
box Backup host
    participant Repositories sub-task
    participant gitaly-backup
end

Repositories sub-task-&gt;&gt;+gitaly-backup: List of repositories

loop Each repository
    gitaly-backup-&gt;&gt;+Gitaly: ListRefs request
    Gitaly-&gt;&gt;-gitaly-backup: List of Git references

    gitaly-backup-&gt;&gt;+Gitaly: CreateBundleFromRefList request
    Gitaly-&gt;&gt;-gitaly-backup: Git bundle file

    gitaly-backup-&gt;&gt;+Gitaly: GetCustomHooks request
    Gitaly-&gt;&gt;-gitaly-backup: Custom hooks archive
end

gitaly-backup-&gt;&gt;-Repositories sub-task: Success/failure</code></pre></details></div>

Gitaly Cluster(Praefect)로 구성한 스토리지는 독립 실행형 Gitaly 인스턴스와 동일한 방식으로 백업합니다.

Gitaly Cluster(Praefect)는 gitaly-backup에서 RPC 호출을 받으면 자체 데이터베이스를 다시 구축합니다.

Gitaly Cluster(Praefect) 데이터베이스를 별도로 백업할 필요는 없습니다.


백업은 RPC를 통해 동작하므로 복제 계수와 관계없이 각 리포지터리는 한 번만 백업됩니다.

서버 측 백업#
서버 측 리포지터리 백업은 Git 리포지터리를 효율적으로 백업하는 방법입니다.
이 방식의 장점은 다음과 같습니다.

Gitaly에서 RPC로 데이터를 전송하지 않습니다.
서버 측 백업은 네트워크 전송량이 더 적습니다.
백업 Rake 태스크를 실행하는 머신에 디스크 스토리지가 필요하지 않습니다.

서버 측에서 Gitaly를 백업하기 위해 repositories 하위 작업은 다음 작업을 수행합니다.

gitaly-backup을 실행해 리포지터리마다 RPC를 한 번씩 호출합니다.
물리적 리포지터리를 저장하는 Gitaly 노드가 백업 데이터를 오브젝트 스토리지에 업로드하도록 트리거합니다.
백업 ID를 사용해 오브젝트 스토리지에 저장된 백업을 생성된 백업 아카이브에 연결합니다.

다음 다이어그램은 이 과정을 나타냅니다.
Mermaid 다이어그램 (31줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: Server-side repository backup workflow
    accDescr: Sequence diagram showing server-side backups where the repositories sub-task calls gitaly-backup, which issues a BackupRepository request for each repository. Gitaly uploads files directly to object storage, then reports success or failure for that repository.
box Backup host
    participant Repositories sub-task
    participant gitaly-backup
end

Repositories sub-task-&gt;&gt;+gitaly-backup: List of repositories

loop Each repository
    gitaly-backup-&gt;&gt;+Gitaly: BackupRepository request

    Gitaly-&gt;&gt;+Object-storage: Git references file
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;+Object-storage: Git bundle file
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;+Object-storage: Custom hooks archive
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;+Object-storage: Backup manifest file
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;-gitaly-backup: Success/failure
end

gitaly-backup-&gt;&gt;-Repositories sub-task: Success/failure</code></pre></details></div>

파일 백업#
다음 하위 작업이 파일을 백업합니다.

uploads: 첨부 파일
builds: CI/CD job 출력 로그
artifacts: CI/CD job 아티팩트
pages: 페이지 콘텐츠
lfs: LFS 오브젝트
terraform_state: Terraform 상태
registry: 컨테이너 레지스트리 이미지
packages: 패키지
ci_secure_files: 프로젝트 수준 보안 파일
external_diffs: 머지 리퀘스트 diff(외부에 저장된 경우)

각 하위 작업은 작업별 디렉터리에서 파일 집합을 식별한 뒤 다음 작업을 수행합니다.

tar 유틸리티로 식별한 파일의 아카이브를 생성합니다.
디스크에 저장하지 않고 gzip으로 아카이브를 압축합니다.
tar 파일을 백업 스테이징 디렉터리에 저장합니다.

백업은 운영 중인 인스턴스에서 생성하므로 백업 과정에서 파일이 변경될 수 있습니다.
이 경우 대체 전략으로 파일을 백업할 수 있습니다. rsync 유틸리티가 백업 대상 파일의 사본을
만들어 tar에 전달해 아카이브합니다.
Note
이 전략을 사용한다면 백업 Rake 태스크를 실행하는 머신에 복사한 파일과 압축 아카이브를
모두 담을 수 있는 충분한 스토리지가 있어야 합니다.

백업 ID#
백업 ID는 백업 아카이브의 고유 식별자입니다. 여러 백업 아카이브가 있는 상태에서 GitLab을
복원해야 할 때 이 ID가 핵심 역할을 합니다.
백업 아카이브는 config/gitlab.yml 파일의 backup_path 설정으로 지정한 디렉터리에 저장됩니다.
기본 위치는 /var/opt/gitlab/backups 입니다.
백업 ID는 다음 요소로 구성됩니다.

백업 생성 타임스탬프
날짜(YYYY_MM_DD)
GitLab 버전
GitLab 에디션

백업 ID 예시는 다음과 같습니다. 1493107454_2018_04_25_10.6.4-ce
백업 파일명#
기본적으로 파일명은 <backup-id>_gitlab_backup.tar 구조를 따릅니다. 예를 들면 1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar 입니다.
백업 정보 파일#
백업 정보 파일 backup_information.yml은 백업에 포함되지 않는 모든 백업 입력값을
저장합니다. 이 파일은 백업 스테이징 디렉터리에 저장됩니다.
하위 작업은 이 파일로 데이터를 복원하는 방법과 서버 측 리포지터리 백업 같은
외부 서비스와 백업 데이터를 연결하는 방법을 판단합니다.
백업 정보 파일에는 다음 내용이 포함됩니다.

백업을 생성한 시각.
백업을 생성한 GitLab 버전.
그 밖에 지정한 옵션. 예를 들면 건너뛴 하위 작업입니다.

백업 스테이징 디렉터리#
백업 스테이징 디렉터리는 백업과 복원 과정에서 사용하는 임시 저장 위치입니다.
이 디렉터리는 다음 용도로 사용합니다.

GitLab 백업 아카이브를 생성하기 전에 백업 아티팩트를 저장합니다.
백업을 복원하거나 증분 백업을 생성하기 전에 백업 아카이브의 압축을 풉니다.

백업 스테이징 디렉터리는 완성된 백업 아카이브가 생성되는 디렉터리와 동일합니다.
tar로 묶지 않는 백업을 생성하면 백업 아티팩트가 이 디렉터리에 남고 아카이브는 생성되지 않습니다.
다음은 tar로 묶지 않은 백업이 들어 있는 백업 스테이징 디렉터리의 예시입니다.
backups/
├── 1701728344_2023_12_04_16.7.0-pre_gitlab_backup.tar
├── 1701728447_2023_12_04_16.7.0-pre_gitlab_backup.tar
├── artifacts.tar.gz
├── backup_information.yml
├── builds.tar.gz
├── ci_secure_files.tar.gz
├── db
│   ├── ci_database.sql.gz
│   └── database.sql.gz
├── lfs.tar.gz
├── packages.tar.gz
├── pages.tar.gz
├── repositories
│   ├── manifests/
│   ├── @hashed/
│   └── @snippets/
├── terraform_state.tar.gz
└── uploads.tar.gz

홈/GitLab/관리/Backup restore/Backup archive process

`백업 아카이브 프로세스`

GitLab v19.4

원문 보기
번역일: 2026-09-18

요약
백업 명령을 실행하면 백업 스크립트가 GitLab 데이터를 저장할 백업 아카이브 파일을 생성합니다. 아카이브 파일을 생성하기 위해 백업 스크립트는 다음 작업을 수행합니다. 데이터베이스를 백업하기 위해 db 하위 작업은 다음 작업을 수행합니다.

백업 명령을 실행하면 백업 스크립트가 GitLab 데이터를 저장할 백업 아카이브 파일을 생성합니다.


아카이브 파일을 생성하기 위해 백업 스크립트는 다음 작업을 수행합니다.

증분 백업을 수행하는 경우 이전 백업 아카이브 파일의 압축을 풉니다.
백업 아카이브 파일을 업데이트하거나 새로 생성합니다.
다음 백업 하위 작업을 모두 실행합니다.

데이터베이스 백업.
Git 리포지터리 백업.
파일 백업.


백업 스테이징 영역을 tar 파일로 아카이브합니다.
구성되어 있다면 새 백업 아카이브를 오브젝트 스토리지에 업로드합니다.
아카이브한 백업 스테이징 디렉터리의 파일을 정리합니다.

데이터베이스 백업#
데이터베이스를 백업하기 위해 db 하위 작업은 다음 작업을 수행합니다.

pg_dump로 SQL 덤프를 생성합니다.
pg_dump의 출력을 gzip으로 파이프해 압축된 SQL 파일을 만듭니다.
파일을 백업 스테이징 디렉터리에 저장합니다.

Git 리포지터리 백업#
Git 리포지터리를 백업하기 위해 repositories 하위 작업은 다음 작업을 수행합니다.


백업할 리포지터리를 gitaly-backup에 알립니다.


gitaly-backup을 실행해 다음 작업을 수행합니다.

Gitaly에서 일련의 원격 프로시저 호출(RPC)을 수행합니다.
각 리포지터리의 백업 데이터를 수집합니다.



수집한 데이터를 백업 스테이징 디렉터리의 디렉터리 구조로 스트리밍합니다.


다음 다이어그램은 이 과정을 나타냅니다.
Mermaid 다이어그램 (24줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: Git repository backup workflow
    accDescr: Sequence diagram showing the repositories sub-task calling gitaly-backup with a list of repositories. For each repository, gitaly-backup uses RPCs to collect refs, create a bundle, and retrieve custom hooks. It then returns success or failure.
box Backup host
    participant Repositories sub-task
    participant gitaly-backup
end

Repositories sub-task-&gt;&gt;+gitaly-backup: List of repositories

loop Each repository
    gitaly-backup-&gt;&gt;+Gitaly: ListRefs request
    Gitaly-&gt;&gt;-gitaly-backup: List of Git references

    gitaly-backup-&gt;&gt;+Gitaly: CreateBundleFromRefList request
    Gitaly-&gt;&gt;-gitaly-backup: Git bundle file

    gitaly-backup-&gt;&gt;+Gitaly: GetCustomHooks request
    Gitaly-&gt;&gt;-gitaly-backup: Custom hooks archive
end

gitaly-backup-&gt;&gt;-Repositories sub-task: Success/failure</code></pre></details></div>

Gitaly Cluster(Praefect)로 구성한 스토리지는 독립 실행형 Gitaly 인스턴스와 동일한 방식으로 백업합니다.

Gitaly Cluster(Praefect)는 gitaly-backup에서 RPC 호출을 받으면 자체 데이터베이스를 다시 구축합니다.

Gitaly Cluster(Praefect) 데이터베이스를 별도로 백업할 필요는 없습니다.


백업은 RPC를 통해 동작하므로 복제 계수와 관계없이 각 리포지터리는 한 번만 백업됩니다.

서버 측 백업#
서버 측 리포지터리 백업은 Git 리포지터리를 효율적으로 백업하는 방법입니다.
이 방식의 장점은 다음과 같습니다.

Gitaly에서 RPC로 데이터를 전송하지 않습니다.
서버 측 백업은 네트워크 전송량이 더 적습니다.
백업 Rake 태스크를 실행하는 머신에 디스크 스토리지가 필요하지 않습니다.

서버 측에서 Gitaly를 백업하기 위해 repositories 하위 작업은 다음 작업을 수행합니다.

gitaly-backup을 실행해 리포지터리마다 RPC를 한 번씩 호출합니다.
물리적 리포지터리를 저장하는 Gitaly 노드가 백업 데이터를 오브젝트 스토리지에 업로드하도록 트리거합니다.
백업 ID를 사용해 오브젝트 스토리지에 저장된 백업을 생성된 백업 아카이브에 연결합니다.

다음 다이어그램은 이 과정을 나타냅니다.
Mermaid 다이어그램 (31줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: Server-side repository backup workflow
    accDescr: Sequence diagram showing server-side backups where the repositories sub-task calls gitaly-backup, which issues a BackupRepository request for each repository. Gitaly uploads files directly to object storage, then reports success or failure for that repository.
box Backup host
    participant Repositories sub-task
    participant gitaly-backup
end

Repositories sub-task-&gt;&gt;+gitaly-backup: List of repositories

loop Each repository
    gitaly-backup-&gt;&gt;+Gitaly: BackupRepository request

    Gitaly-&gt;&gt;+Object-storage: Git references file
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;+Object-storage: Git bundle file
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;+Object-storage: Custom hooks archive
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;+Object-storage: Backup manifest file
    Object-storage-&gt;&gt;-Gitaly: Success/failure

    Gitaly-&gt;&gt;-gitaly-backup: Success/failure
end

gitaly-backup-&gt;&gt;-Repositories sub-task: Success/failure</code></pre></details></div>

파일 백업#
다음 하위 작업이 파일을 백업합니다.

uploads: 첨부 파일
builds: CI/CD job 출력 로그
artifacts: CI/CD job 아티팩트
pages: 페이지 콘텐츠
lfs: LFS 오브젝트
terraform_state: Terraform 상태
registry: 컨테이너 레지스트리 이미지
packages: 패키지
ci_secure_files: 프로젝트 수준 보안 파일
external_diffs: 머지 리퀘스트 diff(외부에 저장된 경우)

각 하위 작업은 작업별 디렉터리에서 파일 집합을 식별한 뒤 다음 작업을 수행합니다.

tar 유틸리티로 식별한 파일의 아카이브를 생성합니다.
디스크에 저장하지 않고 gzip으로 아카이브를 압축합니다.
tar 파일을 백업 스테이징 디렉터리에 저장합니다.

백업은 운영 중인 인스턴스에서 생성하므로 백업 과정에서 파일이 변경될 수 있습니다.
이 경우 대체 전략으로 파일을 백업할 수 있습니다. rsync 유틸리티가 백업 대상 파일의 사본을
만들어 tar에 전달해 아카이브합니다.
Note
이 전략을 사용한다면 백업 Rake 태스크를 실행하는 머신에 복사한 파일과 압축 아카이브를
모두 담을 수 있는 충분한 스토리지가 있어야 합니다.

백업 ID#
백업 ID는 백업 아카이브의 고유 식별자입니다. 여러 백업 아카이브가 있는 상태에서 GitLab을
복원해야 할 때 이 ID가 핵심 역할을 합니다.
백업 아카이브는 config/gitlab.yml 파일의 backup_path 설정으로 지정한 디렉터리에 저장됩니다.
기본 위치는 /var/opt/gitlab/backups 입니다.
백업 ID는 다음 요소로 구성됩니다.

백업 생성 타임스탬프
날짜(YYYY_MM_DD)
GitLab 버전
GitLab 에디션

백업 ID 예시는 다음과 같습니다. 1493107454_2018_04_25_10.6.4-ce
백업 파일명#
기본적으로 파일명은 <backup-id>_gitlab_backup.tar 구조를 따릅니다. 예를 들면 1493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar 입니다.
백업 정보 파일#
백업 정보 파일 backup_information.yml은 백업에 포함되지 않는 모든 백업 입력값을
저장합니다. 이 파일은 백업 스테이징 디렉터리에 저장됩니다.
하위 작업은 이 파일로 데이터를 복원하는 방법과 서버 측 리포지터리 백업 같은
외부 서비스와 백업 데이터를 연결하는 방법을 판단합니다.
백업 정보 파일에는 다음 내용이 포함됩니다.

백업을 생성한 시각.
백업을 생성한 GitLab 버전.
그 밖에 지정한 옵션. 예를 들면 건너뛴 하위 작업입니다.

백업 스테이징 디렉터리#
백업 스테이징 디렉터리는 백업과 복원 과정에서 사용하는 임시 저장 위치입니다.
이 디렉터리는 다음 용도로 사용합니다.

GitLab 백업 아카이브를 생성하기 전에 백업 아티팩트를 저장합니다.
백업을 복원하거나 증분 백업을 생성하기 전에 백업 아카이브의 압축을 풉니다.

백업 스테이징 디렉터리는 완성된 백업 아카이브가 생성되는 디렉터리와 동일합니다.
tar로 묶지 않는 백업을 생성하면 백업 아티팩트가 이 디렉터리에 남고 아카이브는 생성되지 않습니다.
다음은 tar로 묶지 않은 백업이 들어 있는 백업 스테이징 디렉터리의 예시입니다.
backups/
├── 1701728344_2023_12_04_16.7.0-pre_gitlab_backup.tar
├── 1701728447_2023_12_04_16.7.0-pre_gitlab_backup.tar
├── artifacts.tar.gz
├── backup_information.yml
├── builds.tar.gz
├── ci_secure_files.tar.gz
├── db
│   ├── ci_database.sql.gz
│   └── database.sql.gz
├── lfs.tar.gz
├── packages.tar.gz
├── pages.tar.gz
├── repositories
│   ├── manifests/
│   ├── @hashed/
│   └── @snippets/
├── terraform_state.tar.gz
└── uploads.tar.gz