Docker 로그로 컨테이너 문제 추적하기

Docker 컨테이너 문제는 로그에서 시작한다. 컨테이너가 떠 있는데 접속이 안 되면 먼저 증상을 확인하고, 그 다음 로그를 보는 순서가 중요하다. 무작정 설정부터 바꾸면 원인을 놓치기 쉽다.

먼저 정상 상태 정의하기

문제를 판단하려면 정상 상태가 뭔지 알아야 한다. 같은 컨테이너가 다른 환경에서는 잘 돌아갔다면, 그 환경의 설정을 기준으로 비교한다.

로그에서 볼 것들

# 현재 실행 중인 컨테이너 확인
docker ps | grep service-name

# 최근 로그 보기
docker logs --tail=100 service-name

# 실시간 로그 스트림
docker logs -f service-name

# 컨테이너 상세 정보 확인
docker inspect service-name

로그는 세 가지를 보면 된다. 첫째, 시작 단계에서 에러가 났는지 (permission denied, port in use 등). 둘째, 실행 중 반복되는 에러가 있는지 (connection timeout, ECONNREFUSED). 셋째, 환경변수가 제대로 로드되었는지.

이미지 태그와 볼륨 확인

로그가 깔끔해도 접속이 안 되면, 컨테이너가 실제로 최신 이미지로 띄워졌는지 확인해야 한다. docker inspect에서 Image와 Mounts를 보면 된다. 특히 볼륨 마운트가 제대로 안 되면 설정 파일을 못 읽어서 예상과 다르게 동작한다.

포트 매핑이 제대로 됐나

docker ps --no-trunc

로그가 정상이고 이미지도 맞는데 접속이 안 되면, 포트 매핑을 의심해본다. 0.0.0.0:8080->3000/tcp 같은 형태로 떠야 한다. 만약 127.0.0.1:8080->3000/tcp라면 호스트의 다른 IP에서는 접속이 안 된다.

환경변수와 설정 값 비교

마지막으로 환경변수가 제대로 넘어갔는지 확인한다. 로컬에서는 .env 파일을 읽지만, 배포 환경에서는 컨테이너에 환경변수를 명시적으로 넘겨야 한다. 만약 DATABASE_URL이 필요한데 설정하지 않았다면, 앱은 떠 있어도 DB 쿼리에서 에러난다.

체계적으로 확인하는 순서

1. 컨테이너가 떠 있는지, 정상 상태 코드(0)로 떠 있는지 확인
2. 로그를 보고 시작 단계 에러 체크
3. 이미지 태그와 볼륨 마운트 맞는지 확인
4. 포트 매핑 올바른지 확인
5. 환경변수와 설정이 컨테이너에 전달됐는지 확인

한 번에 여러 가지를 바꾸면 원인을 찾기 어렵다. 작은 확인들이 모이면 자연스럽게 원인이 좁혀진다.