DevOps·인프라·클라우드 · 빠른 참조 · 2026-05-05 · 조회 185

Docker 컨테이너 문제 해결 가이드 (Docker Container Troubleshooting Guide)

Docker 컨테이너가 예상대로 동작하지 않을 때, 컨테이너 즉시 종료, 포트 충돌 등 일반적인 문제 해결 방법을 알아봅니다.

안녕하세요, 주니어 개발자 여러분! 오늘은 개발 환경에서 필수적인 Docker 컨테이너 (Docker Container) 사용 중 발생할 수 있는 흔한 문제들과 그 해결 방법에 대해 알아보겠습니다. 컨테이너가 예상대로 동작하지 않을 때 당황하지 않고 문제를 진단하는 능력을 키우는 것이 중요합니다.

### 1. 컨테이너가 즉시 종료되는 경우 (Container Exits Immediately)

Docker 컨테이너를 실행했는데 `docker ps` 명령으로 확인했을 때 보이지 않거나, `Exited` 상태로 바로 바뀌는 경우가 있습니다. 이는 컨테이너 내부의 애플리케이션이 시작되지 못했거나, 실행할 작업이 없어서 종료된 경우입니다.

**원인:**
*   컨테이너 내부 애플리케이션 오류 (예: 설정 파일 오류, 의존성 누락)
*   `Dockerfile`의 `CMD` 또는 `ENTRYPOINT`가 백그라운드 프로세스가 아닌 단일 명령을 실행하고 바로 종료되는 경우
*   필수 서비스 (예: 웹 서버)가 제대로 시작되지 않음

**해결 방법:**
가장 먼저 `docker ps -a` 명령으로 종료된 컨테이너까지 확인하고, 해당 컨테이너의 로그를 확인해야 합니다.

```bash
# 모든 컨테이너 상태 확인 (종료된 컨테이너 포함)
docker ps -a

# 특정 컨테이너의 로그 확인
docker logs <컨테이너_이름_또는_ID>
```

**예제:**
```bash
docker run --name my-nginx -p 80:80 nginx
# 만약 my-nginx가 바로 종료된다면 (이 경우는 nginx가 정상 실행되므로 발생하지 않음)
docker logs my-nginx
```
로그를 통해 `Error`, `Failed to start`, `permission denied` 등의 메시지를 찾아 원인을 파악할 수 있습니다. 예를 들어, `nginx` 컨테이너가 바로 종료된다면 `nginx` 설정 파일에 문제가 있을 가능성이 큽니다.

### 2. 포트 충돌 (Port Conflict)

컨테이너를 특정 포트에 바인딩하여 실행하려 할 때, `Error response from daemon: driver failed programming external connectivity: Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use`와 같은 오류 메시지를 만날 수 있습니다. 이는 호스트 머신의 해당 포트가 이미 다른 프로세스나 컨테이너에 의해 사용 중이기 때문입니다.

**원인:**
*   호스트 머신의 다른 애플리케이션이 해당 포트를 사용 중
*   다른 Docker 컨테이너가 이미 해당 포트를 사용 중

**해결 방법:**
어떤 프로세스가 해당 포트를 사용 중인지 확인하고, 해당 프로세스를 종료하거나 다른 포트를 사용하도록 컨테이너를 실행해야 합니다.

```bash
# 호스트 머신에서 특정 포트를 사용하는 프로세스 확인 (Linux/macOS)
sudo netstat -tulnp | grep <포트_번호>
# 또는
sudo lsof -i :<포트_번호>

# 현재 실행 중인 Docker 컨테이너들이 사용하는 포트 확인
docker ps
```

**예제:**
`8080` 포트가 이미 사용 중일 때:

```bash
# 8080 포트를 사용하는 프로세스 확인
sudo netstat -tulnp | grep 8080

# 다른 포트(예: 8081)로 컨테이너 실행
docker run -d --name my-app -p 8081:80 my-image
```

### 마무리하며

Docker 컨테이너 문제 해결의 핵심은 **로그와 상태를 꼼꼼히 확인하는 것**입니다. 대부분의 문제는 `docker logs`와 `docker ps -a` 명령을 통해 단서를 찾을 수 있습니다. 익숙해지면 어떤 문제가 발생하더라도 침착하게 해결할 수 있을 거예요. 꾸준히 연습하여 능숙한 Docker 사용자가 되시길 바랍니다!

참고 출처

같은 카테고리 자료

Vercel + Next.js 배포 SSL/TLS + Let's Encrypt 자동화 Nginx Reverse Proxy 구성 GitHub Actions 워크플로우

← DevOps·인프라·클라우드 목록 기술 자료 전체

Docker 컨테이너 문제 해결 가이드 (Docker Container Troubleshooting Guide)

같은 카테고리 자료

이런 기술을 우리 회사에 적용하려면?

회원 전용 기능입니다