Docker 컨테이너 문제 디버깅할 때 먼저 확인할 것

컨테이너 문제가 발생했을 때 로그만 들여다보면 시간을 낭비한다. 로컬에서는 잘 작동하는데 서버에서만 터지거나, 환경 차이 때문에 헤매게 되는 경우가 대부분이다.

먼저 컨테이너 상태 확인하기

무작정 로그를 뒤지기 전에 전체 컨테이너 상태를 먼저 파악해야 한다. 정상인 상태가 무엇인지 알아야 비정상을 판단할 수 있다.

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

첫 번째 명령은 컨테이너가 정말 실행 중인지, 상태가 어떤지 본다. 자주 있는 실수는 컨테이너가 사실 Exited 상태인데도 로그를 보려 한다는 것이다. docker ps -a로 모든 컨테이너를 봐야 할 때도 있다.

볼륨 마운트 확인

대부분의 문제는 볼륨 마운트 경로가 잘못되었거나, 호스트의 파일이 없을 때 발생한다. docker inspect의 Mounts 섹션을 정확히 읽으면 절반의 문제는 여기서 찾을 수 있다.

정상일 때의 컨테이너 상태를 기록해두면 다음 번에 비교할 기준점이 생긴다.

환경 변수와 빌드 설정 차이

로컬과 운영 환경의 가장 큰 차이는 환경 변수다. 데이터베이스 URL, API 엔드포인트, 디버그 플래그 등이 다르면 같은 이미지도 다르게 동작한다.

docker inspect에서 Env 섹션을 확인하고, 실제 파일 시스템을 보려면:

docker exec service-name env

이 정도면 웬만한 문제는 찾을 수 있다.

포트 매핑 검증

포트가 제대로 열려 있지 않으면 모든 설정이 헛수고다. 외부에서 접근 가능한지 확인하려면:

docker port service-name

그리고 실제로 포트가 응답하는지 테스트해야 한다. 컨테이너 안에서 서버가 실행 중이라도, 포트 바인딩이 잘못되면 외부에서 연결할 수 없다.

작은 변경, 큰 확인

한 번에 여러 설정을 바꾸지 말 것. 하나를 고치고 결과를 확인한 뒤, 그 다음을 시도해야 된다. 그래야 어디서 문제가 풀렸는지 알 수 있다.

마지막으로는 실제 공개 URL이나 화면까지 확인해야 작업이 끝난다. 로그가 깨끗해도 사용자가 보는 화면이 틀리면 소용없다.