Docker 컨테이너 이미지 문제 디버깅

Docker를 사용하면 로컬과 운영 환경의 불일치 문제가 줄어들지만, 컨테이너 레벨의 새로운 문제들이 생긴다. 특히 이미지 로딩에 실패하면 문제의 원인을 파악하기 어려울 수 있다.

기본 진단 명령어

컨테이너 상태를 파악하는 첫 단계:

docker ps
docker logs --tail=100 service-name
docker inspect service-name

• docker ps: 현재 실행 중인 컨테이너 목록과 상태
• docker logs: 컨테이너의 최근 로그 - 대부분의 문제는 여기서 원인을 찾을 수 있다
• docker inspect: 컨테이너의 상세 설정 정보

한 줄로 요약하는 방법

문제가 뭔지 한 문장으로 설명할 수 있어야 원인을 좁힐 수 있다. 예를 들어:

• "컨테이너가 시작 직후 종료된다" → 엔트리포인트 명령 확인
• "포트 연결이 안 된다" → 포트 매핑과 방화벽 확인
• "이미지를 찾을 수 없다" → 이미지 이름과 태그 확인

먼저 볼 파일과 설정

컨테이너 문제를 체계적으로 해결하려면:

1. 컨테이너 상태 확인 (정상인가, 실패했나)
2. 환경 변수가 제대로 전달되었는가
3. 이미지 태그가 예상한 버전인가

브라우저에서 볼 값

• 실제 응답이 오는가
• 에러 페이지가 나타나는가
• 연결 타임아웃이 발생하는가

포트 매핑을 다시 확인하는 것도 중요하다. 컨테이너 내부 포트와 호스트 포트가 제대로 연결되어 있는지 확인하자.

결과가 바뀐 이유를 로그로 설명할 수 있으면 충분히 정리된 것이다. 다음에 같은 문제가 나올 때 참고할 기록을 남겨두자.