Node 컨테이너 이미지 태그 헷갈릴 때

Docker를 쓰다 보면 로컬에서는 잘 돌아가는데 배포된 컨테이너에서 문제가 나는 경우가 있다. 대부분의 원인은 실제로 어떤 이미지 버전이 배포되었는지 헷갈렸기 때문이다.

현재 실행 중인 이미지 확인

먼저 지금 실행 중인 컨테이너가 어떤 이미지에서 나왔는지 확인해야 한다. docker ps로 컨테이너 ID를 알아낸 다음, 그 컨테이너의 이미지 정보를 본다.

• 먼저 볼 값: 이미지 ID, 태그, 빌드 시간
• 같이 비교할 값: 로컬에서 방금 빌드한 이미지
• 기록해둘 것: 이미지 SHA, 태그, 빌드 명령어

이미지 검사 명령어들

# 실행 중인 컨테이너 확인
docker ps

# 컨테이너의 이미지 정보 보기
docker inspect <container-id> | grep -i image

# 이미지 레이어와 빌드 히스토리 보기
docker history <image-name:tag>

# 이미지의 상세 정보
docker inspect <image-id>

환경변수와 마운트 확인

이미지가 맞아도 실행할 때 전달되는 환경변수나 볼륨 마운트가 다르면 다르게 동작한다. 컨테이너가 어떤 환경에서 실행 중인지 확인한다.

# 컨테이너의 환경변수 확인
docker exec <container-id> env

# 마운트된 볼륨 확인
docker inspect <container-id> | grep -A 5 Mounts

로그를 한 줄씩 읽기

Docker 이미지의 문제는 시작 로그에 자주 나타난다. Dockerfile의 RUN이나 ENTRYPOINT에서 뭔가 실패했는데 무시한 경우가 많다. 로그를 끝까지 읽으면서 에러나 경고가 있는지 확인한다.

# 최근 로그 보기
docker logs --tail=100 <container-id>

# 실시간 로그 따라가기
docker logs -f <container-id>

이미지 태그를 명확하게 유지하기

Docker 이미지를 latest로만 태그하면 나중에 어떤 버전이 배포되었는지 알 수 없다. 버전 번호나 빌드 날짜를 포함해서 태그하고, 배포할 때는 구체적인 태그를 명시한다.

# 버전과 빌드 시간을 포함한 태그
docker build -t myapp:v1.2.3-20260630 .
docker build -t myapp:latest .

포트와 헬스 체크도 확인

이미지가 맞고 로그도 문제없어 보여도 포트 매핑이 틀렸거나 헬스 체크가 계속 실패하면 제대로 작동 못 한다. docker ps에서 포트 정보를 확인하고, 실제로 그 포트로 통신되는지 테스트한다.

컨테이너 문제는 작은 것부터 하나씩 확인하면 금방 찾을 수 있다. 현재 상태를 명확히 기록해 두는 습관만 있어도 다음 번에는 훨씬 빠르게 대응할 수 있다.