서버 운영에서 가장 중요한 능력 중 하나는 장애가 발생했을 때 빠르게 원인을 찾고 복구하는 것입니다.

Docker Compose 환경에서도 다양한 장애가 발생할 수 있습니다.

대표적인 문제:

• Container 실행 실패
• Application 오류
• Database 연결 실패
• Network 문제
• Volume 데이터 문제
• Port 충돌
• Resource 부족

장애 대응 기본 흐름:

장애 발생

↓

상태 확인

↓

로그 분석

↓

원인 파악

↓

복구

↓

재발 방지

Docker Compose는 Container 단위로 서비스를 관리하기 때문에 체계적인 분석 순서를 익히면 빠르게 문제를 해결할 수 있습니다.

이번 글에서는 Docker Compose 장애 발생 시 확인 순서부터 Container 오류 분석, Database 장애, Network 문제, 데이터 복구 방법까지 Production 서버 기준으로 알아보겠습니다.

Docker Compose 장애 대응 기본 순서

장애 발생 시 바로 Container를 삭제하거나 재시작하는 것은 좋은 방법이 아닙니다.

먼저 원인을 확인해야 합니다.

권장 순서:

1. Container 상태 확인

↓

2. Resource 확인

↓

3. Log 확인

↓

4. Network 확인

↓

5. Volume 확인

↓

6. 복구 진행

이 순서를 따르면 원인 분석이 쉬워집니다.

Docker Compose Container 상태 확인

첫 번째 확인:

docker compose ps

확인:

• 실행 상태
• 종료 여부
• Health 상태
• Port 연결

예:

정상:

app

running (healthy)

문제:

app

Exited (1)

Exited 상태는 Container 내부 오류가 발생했다는 의미입니다.

Docker Compose Container 로그 확인

가장 중요한 단계입니다.

전체 로그:

docker compose logs

특정 Service:

docker compose logs app

실시간 확인:

docker compose logs -f app

확인 내용:

• Error 메시지
• 연결 실패
• 설정 오류
• Application Crash

예:

Database connection failed

의미:

Application 문제가 아니라 Database 연결 문제일 가능성이 높습니다.

Docker Compose Container 재시작 문제 해결

Container가 계속 재시작하는 경우:

Restart Loop 발생

확인:

docker compose ps

로그:

docker compose logs --tail=100

주요 원인:

• 환경 변수 오류
• Port 충돌
• Memory 부족
• Application 오류

Docker Compose Resource 부족 장애

서버 장애의 흔한 원인은 Resource 부족입니다.

확인:

docker stats

확인 항목:

CPU 과부하

CPU 100%

원인:

• 무한 Loop
• Traffic 증가
• Query 문제

Memory 부족

Memory Limit 초과

결과:

Container 종료

Disk 부족

확인:

df -h

Docker 용량:

docker system df

Docker Compose Port 충돌 해결

Port 충돌도 자주 발생합니다.

오류:

port is already allocated

확인:

lsof -i :8080

해결 방법:

방법 1:

기존 Process 종료

방법 2:

Port 변경

docker-compose.yml:

ports:

  - "9090:8080"

Docker Compose Network 장애 해결

Application이 Database에 연결하지 못하는 경우 Network를 확인합니다.

확인:

docker network ls

상세:

docker network inspect 네트워크명

확인:

• Container 연결 여부
• Network 이름
• IP 정보

대표 오류:

Connection refused

확인:

DB_HOST

DB_PORT

Network

Docker Compose Database 장애 대응

Database 문제는 가장 신중하게 처리해야 합니다.

확인 순서:

1. Container 상태:

docker compose ps

2. Database 로그:

MySQL:

docker compose logs mysql

PostgreSQL:

docker compose logs postgres

3. Volume 확인:

docker volume ls

주의:

Database Container 삭제 전 반드시 Backup 확인

Docker Compose Volume 장애 대응

데이터가 보이지 않는 경우:

확인:

docker volume ls

상세:

docker volume inspect volume-name

확인:

• Volume 존재 여부
• Mount 경로
• 연결 Container

잘못된 Mount:

Source

↓

Destination

확인 필요

Docker Compose Image 문제 해결

Image 오류:

Image not found

확인:

docker images

다운로드:

docker compose pull

재생성:

docker compose up -d

Docker Compose 설정 파일 오류 해결

YAML 오류:

yaml parse error

확인:

docker compose config

기능:

• YAML 문법 확인
• 변수 확인
• 최종 설정 확인

Docker Compose 긴급 복구 방법

서비스 장애 발생 시:

방법 1. Container 재시작

docker compose restart

방법 2. Service 재생성

docker compose up -d --force-recreate

방법 3. 전체 재배포

docker compose down

docker compose up -d

주의:

Database Volume 삭제 옵션:

down -v

사용 금지

데이터 손실 가능

Docker Compose 장애 예방 전략

장애 대응보다 중요한 것은 예방입니다.

필수 구성:

• Healthcheck
• Monitoring
• Backup
• Log 관리
• Resource 제한
• Version 고정

운영 구조:

Monitoring

↓

장애 감지

↓

Alert

↓

빠른 대응

Docker Compose Production 장애 대응 체크리스트

장애 발생 시:

Container:

docker compose ps

Log:

docker compose logs

Resource:

docker stats

Disk:

df -h

Network:

docker network inspect

Volume:

docker volume inspect

자주 묻는 질문

Container를 재시작하면 문제가 해결되나요?

일시적인 문제는 해결될 수 있지만 원인 분석이 먼저 필요합니다.

Database Container를 삭제해도 되나요?

Volume Backup 확인 없이 삭제하면 데이터 손실 위험이 있습니다.

장애 원인을 가장 먼저 어디서 확인해야 하나요?

Container 상태와 Log를 먼저 확인하는 것이 일반적입니다.

Production 서버는 어떻게 장애를 줄이나요?

Monitoring, Backup, Healthcheck, 자동 복구 구조를 함께 구성합니다.

마무리

Docker Compose 장애 대응은 정해진 순서대로 확인하는 것이 중요합니다.

핵심 흐름:

상태 확인

↓

Log 분석

↓

Resource 확인

↓

Network 확인

↓

Volume 확인

↓

복구

이 과정을 익히면 Docker Compose 기반 서버에서 발생하는 대부분의 문제를 빠르게 분석하고 해결할 수 있습니다.

다음 글에서는 운영 서버 환경에서 성능과 안정성을 높이기 위한 Docker Compose Production 최적화 방법을 알아보겠습니다.