Docker: 흔한 문제 해결
컨테이너가 계속 재시작됨, 포트가 사용 중, 공간 부족, “permission denied”, 서비스가 이웃을 보지 못함 — 증상 표와 문제 해결 절차를 알아봐요.
업데이트 2026년 8월 23일
컨테이너 문제는 거의 대부분 열두 가지 정도의 흔한 원인으로 정리돼요. 진단은 항상 같은 세 가지 명령으로 시작해요.
처음 세 가지 명령
docker compose ps
docker compose logs --tail 100 <service>
docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}' <container>
상태, 로그의 마지막 줄, 종료 코드만 봐도 대부분의 질문에 답이 나와요. 그다음부터는 증상에 따라 접근해요.
증상 표
| 증상 | 유력한 원인 | 해야 할 일 |
|---|---|---|
계속 Restarting | 애플리케이션이 시작할 때 크래시함 | docker compose logs --tail 200으로 마지막이 아니라 첫 번째 오류를 읽어요 |
종료 코드 137, OOMKilled: true | 메모리 부족 | 한도를 올리거나 누수를 찾아요, 리소스 한도 참고 |
| 시작 직후 종료 코드 1 | 설정이나 변수의 오류 | docker compose config — 치환을 확인해요 |
port is already allocated | 다른 프로세스가 포트를 점유함 | sudo ss -tulpn | grep :<port> |
no space left on device | 디스크 공간이나 inode 부족 | df -h와 df -i, 디스크 공간 참고 |
볼륨 파일에서 permission denied | UID 불일치 | docker compose exec app id 실행 후 chown 또는 PUID/PGID |
| 애플리케이션이 데이터베이스를 보지 못함 | 네트워크가 다르거나 localhost로 요청함 | Docker 네트워크 참고 |
Cannot connect to the Docker daemon | 서비스가 실행 중이 아니거나 권한이 없음 | sudo systemctl status docker, docker 그룹 |
| 모든 게 느리고 부하는 낮음 | 디스크 병목 | iostat -x 2, 디스크 속도 참고 |
컨테이너는 크래시하는데 로그가 비어 있음
프로세스가 아무것도 출력하지 못하고 죽을 때 이렇게 돼요. 기본 명령 대신 셸로 이미지를 직접 실행해요:
docker run --rm -it --entrypoint sh <image>
안에서 시작 명령을 직접 실행하면 오류가 화면에 나타나요. 겸사겸사 설정 파일이 제자리에 있는지도 확인해요:
docker compose run --rm app cat /app/config.yaml
변경 사항이 적용되지 않음
전형적인 상황이에요: 파일을 고치고 재시작했는데 아무것도 바뀌지 않아요.
docker compose config # does Compose see your changes
docker compose up -d --force-recreate app
docker compose exec app cat /etc/app/config.yaml
보통 원인은 두 가지예요: 파일이 생각하는 위치가 아닌 다른 곳에 마운트됐거나, 컨테이너가 빌드 중 이미지에 들어간 복사본을 보고 있거나요.
docker system prune -a로 문제를 해결하지 마세요. 사용하지 않는 이미지, 네트워크, 빌드 캐시를 지우고,--volumes플래그를 붙이면 데이터가 든 볼륨까지 지워요. 볼륨은 컨테이너가 중지되는 순간 “사용하지 않는” 상태가 돼요. 먼저 원인을 파악하고, 그다음에 정리하세요.
그래도 정리해야 할 때
docker system df
docker image prune
docker builder prune
docker container prune
docker system df는 무엇이 공간을 차지하는지 정확히 보여줘요: 이미지, 빌드 캐시, 볼륨, 컨테이너 로그 중에서요. 보통은 빌드 캐시가 원인이고, 이건 지워도 안전해요.
머신이 응답하지 않을 때
SSH가 연결되지 않고 사이트도 열리지 않아요 — 보통 컨테이너가 메모리를 다 먹어서 시스템이 스왑으로 넘어간 거예요. 머신 패널의 콘솔로 로그인해요. htop과 btop에는 “Screen” 모드가 필요해요: 텍스트 라인으로는 창 크기가 전달되지 않아서 항상 80×24로 표시돼요.
free -h
sudo dmesg -T | tail -40
sudo systemctl restart docker
시스템이 아예 부팅되지 않으면 “Access” 탭에서 부팅 모드를 SystemRescue 복구 디스크로 바꿔요: 머신이 그 디스크로 재부팅되고, 비밀번호 없이 root로 로그인할 수 있으며, 디스크는 /dev/sda로 보여요. 거기서 파티션을 마운트하고 데이터를 꺼낼 수 있어요.