[GitLab] Docker 환경에서 GitLab 백업/복원

GitLab 백업/복원

📌 개요

GitLab은 개발자 협업에 필수적인 도구다.
하지만 운영 중 장애나 실수로 인해 데이터를 잃을 수 있기 때문에, 정기적인 백업과 정확한 복원 절차를 알아두는 것이 중요하다.

이 글에서는 Docker 기반 GitLab에서 전체 데이터를 백업하고 복원하는 방법을 기록한다.

---

🐳 환경 정보

운영 방식: Docker Compose
컨테이너 이름: gitlab-17.10.1-ce
GitLab 이미지: gitlab/gitlab-ce:17.10.1-ce.0
볼륨 경로:
/etc/gitlab → 설정
/var/opt/gitlab → 데이터
/var/log/gitlab → 로그

 

#docker-compose.yaml
services:
  gitlab:
    shm_size: '20gb'  # 공유 메모리 크기 설정 (GitLab은 일부 프로세스에서 높은 shm 사용량이 필요함)
    container_name: gitlab-17.10.1-ce  # 컨테이너 이름
    image: "gitlab/gitlab-ce:17.10.1-ce.0"  # 사용할 GitLab CE 이미지
    hostname: "limfra.co.kr"  # GitLab 내부에서 사용할 호스트명
    environment:
      GITLAB_OMNIBUS_CONFIG: |
              external_url 'http://limfra.co.kr:6031'  # GitLab이 외부에 서비스할 URL (포트 포함)
    ports:
      - '6031:6031'  # GitLab 웹 인터페이스 포트 (HTTP)
      - '6032:6032'  # SSH 포트 (옵션, SSH over custom port 가능)
      - '6033:6033'  # 기타 서비스 포트 (예: 레지스트리용으로 사용 가능)
    volumes:
      - etc:/etc/gitlab              # GitLab 설정 파일 저장소 (gitlab.rb 등)
      - logs:/var/log/gitlab         # GitLab 로그 저장소
      - data:/var/opt/gitlab         # GitLab 데이터 (레포지토리, DB, CI 등 모든 데이터 포함)

volumes:
  etc:   # 설정 파일을 영속적으로 유지하기 위한 볼륨
  logs:  # 로그 파일을 영속적으로 유지하기 위한 볼륨
  data:  # GitLab 핵심 데이터를 저장하는 주요 볼륨 (백업 시 가장 중요한 부분)

---

📦 GitLab 백업 대상 목록 (gitlab-backup create 기준)

구분	백업 대상	설명
DB	PostgreSQL (기본 내장)	이슈, Merge Request, 사용자, 프로젝트 설정 등
Repository	프로젝트 .git 리포지토리	각 프로젝트의 코드 (모든 브랜치/커밋 이력 포함)
Wiki 저장소	프로젝트 .wiki.git 리포지토리	Git 기반 위키 (댓글 포함)
업로드 파일	/uploads/	이슈나 코멘트에 업로드된 첨부파일
사용자 아바타	/uploads/-/system/user/avatar	사용자 프로필 이미지 등
CI/CD 아티팩트	/artifacts/	CI/CD 실행 결과물 (job artifacts)
CI 캐시	/cache/	GitLab Runner 빌드 캐시
LFS 객체	/lfs-objects/	Git LFS로 저장된 대용량 파일

---

🧼 GitLab 전체 백업하기

GitLab은 모든 데이터(코드, DB, Wiki, 업로드 등)를 포함한 통합 백업을 제공한다.

 

1.백업 파일 생성하기

#백업
[root@]$ docker exec -t 컨테이너명 gitlab-backup create

 

#백업 파일 위치

#컨테이너 내부
/var/opt/gitlab/backups

#볼륨
/home/docker/volumes/gitlab_data/backups

#파일명(예시)
-rw-r--r--  1 1000 1000 456089600 Jul  3 08:28 1751530921_2025_07_03_17.10.1_gitlab_backup.tar

---

🔄 GitLab 복원하기

1.서비스 정지

docker exec -it 컨테이너명 gitlab-ctl stop unicorn
docker exec -it 컨테이너명 gitlab-ctl stop sidekiq

 

2.복원

docker exec -it 컨테이너명 gitlab-backup restore

 

3.서비스 재시작

docker exec -it 컨테이너명 gitlab-ctl reconfigure
docker restart 컨테이너명

---

🧠 주의할 점

1. GitLab 버전이 달라지면 복원 시 오류 발생할 수 있음 → 동일 버전 사용 권장
2. 외부 DB(PostgreSQL)를 사용하는 경우 추가 설정 필요 (gitlab.rb)
3. 도메인이 바뀔 경우 컨테이너를 새로 생성해야 함

---

📚 참고

GitLab 공식 문서: Backup and Restore