GitLab 502 오류 해결 가이드: PostgreSQL 잠금 파일 문제

GitLab 서비스에 접속했을 때 갑자기 502 Bad Gateway^[1] 에러가 발생하며 페이지가 열리지 않는 경우가 있습니다. 이 문서는 그중에서도 PostgreSQL의 잠금 파일(lock file)로 인해 발생하는 문제를 진단하고 해결하는 방법을 설명합니다.

1. 증상 확인 및 로그 분석

먼저 GitLab의 상태를 확인하기 위해 Docker Compose가 설치된 경로로 이동하여 로그를 실시간으로 모니터링해야 합니다.

# GitLab 설치 경로로 이동
cd /services/gitlab

아래 명령어를 입력하여 컨테이너 로그를 확인합니다.

docker compose logs -f

오류 메시지 예시

로그를 살펴보다가 아래와 같은 FATAL 메시지가 발견된다면 이 가이드에 기술된 문제일 가능성이 매우 높습니다.

gitlab  | 2024-05-21_00:07:23.61937 FATAL:  lock file "/var/opt/gitlab/postgresql/.s.PGSQL.5432.lock" already exists

2. 원인 파악

이 문제는 주로 다음과 같은 상황에서 발생합니다.

• 서버의 갑작스러운 전원 종료 (정전 등)
• Docker 컨테이너의 비정상적인 강제 종료
• 운영체제(OS) 오류로 인한 시스템 재시작

이때 PostgreSQL이 정상적으로 종료되지 못하면서, 실행 중임을 표시하는 잠금 파일(.lock)^[2]이 삭제되지 않고 남아있게 됩니다. 이후 시스템이 다시 켜졌을 때 이 파일 때문에 DB가 중복 실행으로 판단하여 기동을 거부하게 되는 것입니다.

3. 해결 방법: 잠금 파일 제거 및 재시작

해결 방법은 간단합니다. 남아있는 잠금 파일을 수동으로 제거한 뒤 컨테이너를 다시 시작하면 됩니다. 아래 순서대로 작업을 진행해 주세요.

해결 프로세스

실행 명령어

# 1. PostgreSQL 잠금 파일 제거
rm /services/gitlab/data/postgresql/*.lock

# 2. 컨테이너 중지
docker compose down

# 3. 컨테이너 백그라운드 재실행
docker compose up -d