Docker Node 이미지 디버깅: 컨테이너가 계속 죽을 때

운영 중에 Node 컨테이너가 자꾸 재시작된다면, 작은 신호도 빨리 분리해서 봐야 한다. 로그가 애매하면 아무리 다른 부분을 고쳐도 결과가 안 바뀐다.

컨테이너 상태 파악

먼저 현재 컨테이너가 어떤 상태인지 확인하자:

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

컨테이너가 running 상태인지, exited 상태인지 파악한다. 환경변수가 제대로 전달되었는지 docker inspect로 확인할 수 있다.

로그 분석

docker logs에서 나오는 에러 메시지가 핵심이다. 애플리케이션이 시작되지 않는 건지, 시작은 되는데 크래시되는 건지, 외부 연결이 실패하는 건지 분류한다.

특히 "cannot connect", "ECONNREFUSED", "ENOENT" 같은 에러는 환경 설정 문제가 많다.

환경변수와 포트 매핑 확인

Node 애플리케이션이 쓰는 포트가 Docker compose나 deployment에서 제대로 매핑되었는지 보자. 예를 들어 앱이 포트 3000을 쓰는데, 컨테이너 설정에서는 8080으로 매핑했다면 연결할 수 없다.

환경변수도 마찬가지다. 로컬에서는 .env 파일을 쓰지만, Docker에서는 명시적으로 전달해야 한다.

볼륨 마운트 문제

Node 앱이 파일을 읽거나 쓰려고 할 때 권한이 없거나 경로가 없으면 에러가 난다. 볼륨이 제대로 마운트되었는지, 권한이 맞는지 확인한다.

작은 수정 후 확인

한 가지만 수정한 후 컨테이너를 재시작해서 로그를 본다. 증상이 같은 환경에서 다시 나는지 확인하고, 어디가 바뀌었는지 기록한다.

마지막 점검

로그와 응답으로 왜 상황이 바뀌었는지 설명할 수 있으면 충분히 정리된 것이다. 비슷한 문제가 나중에 다시 생겼을 때, 이번에 남겨둔 기록을 보면 훨씬 빠르게 대응할 수 있다.