Docker 컨테이너가 예상과 다르게 동작할 때

Docker 컨테이너가 로컬에서는 잘 동작하는데 운영 환경에서는 문제가 나는 경우가 있다. 운영 중에는 작은 이상 신호도 빨리 분리해서 봐야 원인을 빠르게 찾을 수 있다.

Docker 컨테이너가 실행 중인지 확인한다

가장 기본적인 확인은 컨테이너가 실제로 실행 중인지 보는 것이다.

docker ps
docker ps -a # 중지된 컨테이너도 포함

컨테이너 상태, 포트 매핑, 재시작 횟수를 확인한다. 계속 재시작되고 있다면 컨테이너 내부에서 에러가 발생하고 있다는 뜻이다.

로그를 확인한다

컨테이너의 최근 로그를 보면 무엇이 문제인지 명확해진다.

docker logs --tail=100 service-name
docker logs -f service-name # 실시간 확인

에러 메시지, 경고, 정상 시작 메시지 여부를 확인한다. 특히 포트 충돌이나 환경변수 누락으로 인한 에러가 자주 나타난다.

포트 매핑을 확인한다

컨테이너 내부 포트와 호스트 포트 매핑이 올바른지 확인한다.

docker ps --format "table {{.Names}}\t{{.Ports}}"

예를 들어 내부는 3000인데 호스트에서 8080으로 매핑했다면, 호스트에서는 8080으로 접근해야 한다. 이런 포트 매핑 실수가 생각보다 자주 발생한다.

환경변수를 확인한다

컨테이너가 실행될 때 받은 환경변수가 올바른지 확인한다.

docker inspect service-name | grep -A 20 "Env"

필수 환경변수가 빠졌거나 잘못된 값이 들어가 있으면 애플리케이션이 제대로 시작되지 않는다.

컨테이너 내부로 들어가서 직접 확인한다

더 자세한 확인이 필요하면 컨테이너 내부로 진입한다.

docker exec -it service-name sh
# 또는
docker exec -it service-name bash

내부에서 필요한 파일이 있는지, 포트가 열려있는지, 필수 프로세스가 실행 중인지를 확인할 수 있다.

브라우저나 curl로 실제 접근을 해본다

컨테이너 상태와 로그가 모두 정상이라면 실제로 애플리케이션이 응답하는지 확인한다.

curl http://localhost:8080
curl -v http://service-name:3000/health

응답 코드, 응답 body를 확인하면 애플리케이션 레벨의 문제인지 Docker 레벨의 문제인지를 구분할 수 있다.

이미지와 컨테이너의 태그를 확인한다

배포한 이미지의 태그가 실제로 올바른 버전인지 확인한다.

docker images | grep service-name

오래된 버전의 이미지가 실행 중일 수도 있다. 최신 이미지를 다시 풀링(pull)하고 새로 실행해야 할 수도 있다.

마지막으로, 이런 확인 순서를 간단히 남겨두면 다음 Docker 문제에서 빠르게 대응할 수 있다.