Docker 컨테이너 캐시 문제 해결하기

Docker 빌드 캐시는 개발 속도를 높이는 데 도움이 되지만, 때로는 예상치 못한 결과를 만들기도 한다. 레이어가 변경되지 않았다고 판단하고 이전 결과를 사용할 때, 실제로는 의존성이나 코드가 바뀌었을 수 있다. 이런 문제는 로그, 이미지 태그, 환경 변수를 함께 봐야 해결할 수 있다.

핵심 질문부터 시작

정말 캐시 때문인가? 아니면 Dockerfile 자체에 문제가 있는가? 또는 런타임 설정이 잘못됐는가? 한 번에 한 가지씩 제외해나간다.

제외할 원인 먼저 찾기

캐시 문제가 아닐 가능성이 높은 것부터 확인한다. 이미지 태그가 정확한지, 환경 변수가 제대로 전달되는지, 볼륨 마운트가 올바른지.

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

환경 변수 검증

런타임에 필요한 모든 환경 변수가 정의됐는지, 값이 올바른지 확인한다.

• 확인할 것: 이미지 태그, 컨테이너 상태, 로그 메시지
• 비교 기준: 정상 상태의 컨테이너
• 기록할 것: 이미지 ID, 환경 변수, 포트 매핑

빌드 단계별 확인

Dockerfile의 각 단계가 제대로 실행되는지 본다. 어느 레이어부터 캐시를 사용하지 않는지 로그에서 찾을 수 있다.

docker build --no-cache -t app:latest .
# 캐시 없이 완전히 새로 빌드

예상되는 정상 상태

컨테이너가 시작되고, 필요한 서비스가 준비되고, 헬스 체크를 통과해야 한다. 로그에서 이 모든 단계가 완료되는지 확인한다.

비정상일 때 할 일

캐시가 의심된다면 --no-cache 플래그로 완전히 새로 빌드한다. 그렇게 해도 같은 에러가 나면 캐시는 원인이 아니다.

# 캐시 비활성화
docker build --no-cache -t app:latest .

# 이미지와 컨테이너 정리
docker container prune -f
docker image prune -f

정리와 마무리

Docker 문제는 빠른 해결보다는 정확한 진단이 중요하다. 다음에 같은 증상이 나오면 이전 기록을 참고하면 디버깅이 훨씬 빠르다.

완료 기준

1. 캐시가 정말 원인인지 확인했는가
2. 각 단계의 로그를 읽을 수 있는가
3. 해결책을 명령어로 설명할 수 있는가

이미지 빌드 후 실제 동작을 테스트하기 전까지는 완전히 해결된 것이 아니다.