GitLab Architecture¶

GitLab의 전체 아키텍처와 구성 요소, 그리고 다양한 배포 방식에 따른 구조를 정의함.
특정 인프라 환경에 종속되지 않으며, 단일 서버부터 분산 환경까지 공통적으로 적용 가능한 기준을 제공함.

1. 전체 구조 개요¶

GitLab은 단일 프로세스가 아니라 여러 구성요소가 결합된 시스템임.

기본 구성:

Web Server (Nginx)
GitLab Workhorse
Application Server (Puma)
PostgreSQL
Redis
Gitaly

요청 처리 흐름:

1.1 단일 서버 환경¶

Client → Nginx → Workhorse → Puma → DB/Redis/Gitaly

1.2 Reverse Proxy 환경¶

Client → Reverse Proxy → GitLab Nginx → Workhorse → Puma → DB/Redis/Gitaly

2. 구성 요소 역할¶

2-1. Nginx¶

GitLab 내부에 포함된 웹 서버
HTTP/HTTPS 요청 수신
Workhorse로 reverse proxy 역할 수행

※ 외부 Reverse Proxy를 사용하는 경우, GitLab Nginx는 백엔드 웹 서버로 동작함

2-2. GitLab Workhorse¶

Git HTTP 요청 처리
파일 업로드/다운로드 처리
장시간 요청 처리

2-3. Puma¶

Rails 애플리케이션 실행
API 및 Web 요청 처리

2-4. PostgreSQL¶

사용자, 프로젝트, 설정 등 데이터 저장

2-5. Redis¶

캐시
세션 관리
Sidekiq 작업 큐

2-6. Gitaly¶

Git 저장소 접근 및 처리
clone / fetch / push 처리

3. 배포 구조 유형¶

GitLab은 다양한 방식으로 배포 가능함.

3-1. 단일 서버 구조¶

Client → GitLab (All-in-One)

구성:

모든 구성요소가 하나의 서버에 존재

특징:

가장 단순한 구조
설치 및 운영이 쉬움
소규모 환경에 적합

3-2. Reverse Proxy 구조¶

Client → Reverse Proxy → GitLab

구성:

앞단 Reverse Proxy (Nginx, HAProxy 등)
GitLab 서버

역할 분리:

Reverse Proxy:
- TLS 종료
- 도메인 기반 라우팅
- 보안 정책 적용
- GitLab 서버를 외부로 직접 노출하지 않음
- 내부 서비스 보호 (Gateway 패턴)
GitLab:
- 애플리케이션 처리

특징:

실무에서 가장 일반적인 구조
다중 서비스 환경에 적합

3-3. 분산 구조 (HA)¶

Client
  ↓
Load Balancer
  ↓
GitLab Web Nodes
  ↓
DB / Redis / Gitaly (별도)

구성:

Web/App 서버 다중화
DB, Redis, Gitaly 분리

특징:

고가용성 (High Availability)
대규모 트래픽 처리
복잡한 운영 필요

4. 네트워크 구성 고려사항¶

4-1. external_url¶

GitLab은 external_url 기준으로 동작함
GitLab 내부 URL 생성(redirect, clone URL 등)에 사용됨
반드시 사용자 접근 URL과 일치해야 함

4-2. Reverse Proxy 환경¶

Reverse Proxy 사용 시:

Host 헤더 유지 필요
X-Forwarded-For
X-Forwarded-Proto
GitLab에서 trusted proxy 설정 필요

설정이 필요함

4-3. HTTPS 처리¶

다음 두 가지 방식 존재:

1) GitLab 내부 TLS 처리¶

Client (HTTPS)
  ↓
GitLab (HTTPS)

2) Reverse Proxy에서 TLS 종료¶

Client (HTTPS)
  ↓
Reverse Proxy (TLS 종료)
  ↓
GitLab (HTTP)

👉 일반적으로는 Reverse Proxy에서 TLS 종료를 권장함

4-4. 네트워크 접근 통제¶

GitLab 서버는 내부망에서만 접근 가능해야 함
외부 접근은 반드시 Reverse Proxy를 통해서만 허용
내부 서비스 포트는 방화벽으로 제한해야 함

5. SSH 아키텍처¶

GitLab은 HTTP와 별도로 SSH를 통해 Git 작업을 수행함.

Client → SSH → GitLab

구성 방식:

5-1. 기본 SSH¶

OpenSSH 사용
시스템 SSH 포트 사용

5-2. GitLab SSH 분리¶

GitLab 전용 SSH 포트 사용
gitlab-sshd 사용 가능

특징:

관리자 SSH와 분리 가능
보안 정책 적용이 쉬움

운영 정책:

개발자 접근: 내부망 대역 허용 (/24) ex) 192.168.0.0/24
관리자 SSH: 특정 IP만 허용 (/32) ex) 192.168.0.54/32
필요 시 HTTPS-only 운영 가능

6. 데이터 흐름¶

GitLab에서 주요 데이터 흐름은 다음과 같음.

6-1. Git Push¶

Client → SSH → GitLab Shell → Gitaly → Repository 저장

6-2. Web 요청¶

Client → Nginx → Workhorse → Puma → DB

6-3. CI/CD¶

Runner → GitLab API → Redis → Sidekiq → 처리

7. 스토리지 구조¶

영역	실제 저장 경로	GitLab 기준 경로
기본 데이터	`/gitlab/data`	`/var/opt/gitlab`
로그	`/gitlab/logs`	`/var/log/gitlab`
Package Registry	`/gitlab/packages`	`/var/opt/gitlab/gitlab-rails/shared/packages`
CI/CD artifacts	`/gitlab/artifacts`	`/var/opt/gitlab/gitlab-rails/shared/artifacts`
사용자 업로드	`/gitlab/uploads`	`/var/opt/gitlab/gitlab-rails/uploads`
Git LFS	`/gitlab/lfs`	`/var/opt/gitlab/gitlab-rails/shared/lfs-objects`
백업	`/gitlab/backups`	`/var/opt/gitlab/backups`, `backup_path`

8. 확장 전략¶

GitLab은 사용량 증가에 따라 확장이 필요함.

단계별 확장:

8-1. 단일 서버¶

모든 구성요소 포함

8-2. DB / Redis 분리¶

성능 향상
부하 분산

8-3. Gitaly 분리¶

Repository 처리 분산

8-4. Full HA 구성¶

Load Balancer
다중 Web Node
다중 DB 구성

9. 아키텍처 선택 기준¶

환경에 따라 적절한 구조를 선택해야 함.

규모	권장 구조
소규모	단일 서버
중규모	Reverse Proxy + GitLab (서비스 분리 구조)
대규모	HA 분산 구조

10. 핵심 원칙¶

GitLab은 단일 서비스가 아닌 복합 시스템임
external_url은 반드시 정확히 설정해야 함
Reverse Proxy 환경에서는 헤더 전달이 필수임
SSH와 HTTP는 별도 경로로 동작함
데이터는 반드시 분리 및 백업 가능하게 구성해야 함
초기에는 단순하게 시작하고 점진적으로 확장하는 것이 바람직함