Docker 로그 분석과 장애 추적 : Intel N100 홈서버 문제 해결의 첫 번째 단서

 

※ 이 글은 운영자가 직접 홈서버를 운영하며 실험한 경험과 Docker 공식 문서를 참고해 작성했습니다. 문장을 다듬고 구성하는 과정에서 일부 AI 도구의 도움을 받았지만, 최종 내용은 운영자가 꼼꼼하게 확인했습니다.

Docker 로그 분석과 장애 추적 : Intel N100 홈서버 문제 해결의 첫 번째 단서

도입

4주차에는 Docker를 사용하면서 자주 접하게 되는 내부 구조를 하나씩 정리하고 있습니다. 월요일에는 네트워크를 중심으로 서비스들이 어떻게 연결되어 있는지 살펴봤고, 화요일에는 볼륨과 바인드 마운트를 이용해 데이터가 어떻게 저장되는지 확인했습니다. 수요일에는 .env 파일을 설정값 관리 중심에 두고 기준을 다시 정리했습니다. 또 목요일에는 운영 입장에서 Docker 컨테이너 업데이트 정책을 어떻게 적용할지 살펴봤습니다.

금요일에는 문제가 발생했을 때 제일 먼저 살펴보는 Docker 로그에 대해 이야기해보려고 합니다. 직접 홈서버를 운영하다 보면, 컨테이너는 분명히 실행 중인데 웹 화면이 열리지 않거나, 업데이트 이후에 서비스가 계속해서 재시작되는 일이 생길 수 있습니다. 또, Reverse Proxy에서는 모든 게 괜찮아 보이는데 정작 내부 서비스가 응답하지 않는 경우도 있죠.

예전에는 문제가 생기면 일단 설정 파일부터 열어서 하나씩 값을 바꿔보곤 했습니다. 그런데 운영 경험이 쌓이면서, 가장 먼저 봐야 할 건 설정이 아니라 로그라는 걸 알게 됐어요. 물론 로그가 바로 문제를 해결해주지는 않지만, 어디를 들여다봐야 할지 가리켜주는 첫 단서가 되어줬습니다.

Docker 서비스 장애 발생 시 상태 확인, 로그 분석, 환경 변수, 데이터 경로, 네트워크 점검 순서를 운영 기준으로 정리한 Intel N100 홈서버 로그 분석 다이어그램입니다.

※ 다이어그램은 운영 환경 설계를 바탕으로 AI 도구를 활용해 제작했으며, 최종 구성과 내용은 운영자가 직접 검수했습니다.
출처: 디지털 장난감

본문

컨테이너가 실행 중이라고 서비스가 정상이라는 뜻은 아니었다

Docker 서비스를 운영하다 보면 docker compose ps에서 컨테이너가 Up 상태로 보일 때가 있습니다. 하지만 컨테이너가 실행 중이라는 것과 서비스가 정상적으로 동작한다는 것은 조금 다른 문제였습니다.

컨테이너 자체는 정상적으로 떠 있어도, 내부 애플리케이션이 데이터베이스에 연결하지 못하거나 환경 변수가 잘못되어 일부 기능이 제대로 작동하지 않을 때가 있습니다. 또, 내부 포트는 열려 있어도 리버스 프록시와 연결이 되지 않으면 외부에서 접속이 안 될 수도 있습니다.

# 서비스 상태 확인
docker compose ps

# 전체 컨테이너 상태 확인
docker ps -a

그래서 상태를 확인하는 건 시작에 불과했습니다. 진짜 원인을 파악하려면 그 다음 단계에서 로그를 직접 살펴봐야 했죠.

docker compose logs는 문제의 첫 문장을 보여줬다

Docker Compose 환경에서 가장 자주 보게 되는 명령어 중 하나는 docker compose logs였습니다. 이 명령어를 사용하면 Compose로 실행 중인 서비스들의 로그를 확인할 수 있습니다. 원하는 서비스만 따로 볼 수도 있고, 최근 로그 일부만 확인하거나 실시간으로 로그가 어떻게 쌓이는지 따라가며 살펴볼 수도 있습니다.

# 전체 서비스 최근 로그 확인
docker compose logs --tail=100

# 특정 서비스 로그 확인
docker compose logs 서비스이름 --tail=100

# 실시간 로그 확인
docker compose logs -f

# 특정 서비스 실시간 로그 확인
docker compose logs -f 서비스이름

처음에는 로그가 마치 복잡한 영어 문장처럼 보여서 쉽게 다가가지 못했습니다. 그런데 여러 번 들여다보면서 점차 반복되는 패턴이 눈에 들어왔죠. 예를 들어, 서비스 시작 메시지나 설정값 오류, 파일 접근 실패, 포트 충돌, 네트워크 연결 실패 같은 단서들이 생각보다 뚜렷하게 드러나 있었습니다.

자주 만난 오류는 몇 가지 패턴으로 나뉘었다

모든 오류를 처음부터 완벽하게 이해할 필요는 없었습니다. 홈랩을 운영하다 보면 자주 만나는 오류들이 몇 가지 유형으로 나뉘곤 했죠. 그래서 로그를 볼 때도 긴 문장을 처음부터 끝까지 일일이 해석하기보다는, 일단 어떤 문제 유형인지 먼저 짚어보는 게 훨씬 도움이 됐습니다.

오류 유형	로그에서 보일 수 있는 표현	먼저 확인할 항목
포트 충돌	port is already allocated	ports 설정, 이미 사용 중인 포트
환경 변수 누락	missing variable, undefined	.env, 변수명, Compose 치환 결과
권한 문제	permission denied	파일 권한, 디렉터리 소유자, mount 경로
경로 오류	file not found, no such file	Bind Mount 경로, volume 연결
네트워크 오류	connection refused, host not found	Docker network, 서비스명, 내부 포트

이 표가 모든 상황에 완벽하게 들어맞는 정답은 아닙니다. 그래도 실제로 운영을 하다 보면, 로그 문장을 오류 유형별로만 나눠도 다음에 어떤 부분을 확인해야 할지 훨씬 쉽게 알 수 있었습니다.

환경 변수 오류는 .env 파일과 함께 봐야 했다

수요일에 정리했던 .env 파일은 로그 분석에서도 자주 연결되었습니다. 컨테이너가 제대로 실행되지 않거나 원하는 기능이 작동하지 않을 때, 로그를 확인해 보면 환경 변수가 빠졌다거나 인증에 실패했다는 메시지가 종종 나타나곤 했습니다.

# .env 파일 확인
cat .env

# Compose 최종 설정 확인
docker compose config

# 서비스 로그 확인
docker compose logs 서비스이름 --tail=100

여기서 중요한 것은 .env 파일에 값이 있다고 해서 Compose에 제대로 적용되었다고 단정하지 않는 것입니다. 변수명이 다르거나, 실행 디렉터리가 다르거나, Compose 파일에서 변수명을 잘못 참조하면 실제 설정에는 반영되지 않을 수 있습니다.

그래서 현재 운영 기준에서는 .env를 수정한 뒤 docker compose config로 최종 해석 결과를 확인하는 과정을 함께 두고 있습니다.

데이터 경로 오류는 Volume과 Bind Mount를 다시 보게 했다

화요일에 정리한 Volume과 Bind Mount도 로그 분석과 직접 연결되었습니다. 로그에 file not found나 permission denied가 보인다면, 단순히 애플리케이션 문제라기보다 데이터 경로나 권한 문제일 수 있습니다.

# 컨테이너 Mount 정보 확인
docker inspect 컨테이너이름 --format='{{json .Mounts}}'

# Volume 목록 확인
docker volume ls

# 호스트 경로 권한 확인 예시
ls -la /opt/docker/app

Bind Mount는 사용자가 직접 경로를 입력하다 보니, 오타가 나거나 권한 설정이 맞지 않거나, 디렉터리가 아예 만들어지지 않은 경우 문제가 생기기 쉽습니다. 반면, Volume은 Docker에서 자동으로 관리해주기 때문에 경로 실수 같은 문제는 줄어듭니다. 다만, 어느 볼륨이 어떤 서비스와 연결되어 있는지 파악하지 못하면, 나중에 복구하거나 점검할 때 어려움을 겪을 수 있습니다.

로그를 살펴보면, 데이터 경로 문제가 단순히 저장소의 문제가 아니라 서비스가 정상적으로 실행되지 못할 수도 있다는 점을 알 수 있습니다.

네트워크 오류는 Docker network와 Reverse Proxy를 함께 봐야 했다

월요일에 정리한 Docker Network도 장애 추적에서 빠지지 않았습니다. 로그에 connection refused, host not found, timeout 같은 표현이 보이면 서비스 간 연결이나 내부 주소 문제를 의심할 수 있습니다.

# Docker network 목록 확인
docker network ls

# 특정 network 상세 확인
docker network inspect 네트워크이름

# 컨테이너가 연결된 network 확인
docker inspect 컨테이너이름 --format='{{json .NetworkSettings.Networks}}'

Reverse Proxy에서 외부 접속이 안 될 때는 먼저 로그를 확인하는 게 큰 도움이 됩니다. Proxy 설정 화면만 보면 모든 게 정상처럼 보일 수 있지만, 실제로는 대상 컨테이너가 같은 Docker 네트워크에 없거나 내부 포트가 다르게 설정돼 있을 수도 있습니다. 그래서 겉으로 보이는 설정만 믿기보다는, 직접 로그를 확인하면서 문제의 원인을 찾는 게 중요합니다.

이때 로그가 “도메인 문제인지, 프록시 때문인지, 아니면 도커 네트워크에 문제가 있는지” 구별하는 첫 번째 실마리가 됐습니다.

업데이트 이후에는 로그 확인이 더 중요했다

목요일에 정리했던 업데이트 정책을 보면, 로그 확인이 마지막 단계였어요. 이미지를 새로 받은 다음 컨테이너를 재생성하고 나면 꼭 상태와 로그를 살펴봐야 했습니다. 겉으로는 업데이트가 잘된 것처럼 보여도, 실제 내부에는 경고나 오류가 남아 있을 수 있기 때문입니다.

# 업데이트 후 상태 확인
docker compose ps

# 업데이트 후 최근 로그 확인
docker compose logs --tail=100

# 특정 서비스 로그만 확인
docker compose logs 서비스이름 --tail=100

주요 버전이 변경될 때는 환경 변수나 데이터 구조, 초기화 방식 등이 달라질 수 있습니다. 이럴 때 로그를 확인하지 않으면, 서비스가 겉보기에는 잘 작동하는 것처럼 보여도 실제로는 내부에서 문제가 발생하고 있을 수 있습니다.

현재 Intel N100 홈랩의 로그 점검 순서

현 기준으로는 서비스에 문제가 생기면 아래와 같은 순서로 점검하는 게 가장 실질적이었습니다. 중요한 점은 단순히 로그만 쳐다보는 게 아니라, 로그가 어디를 가리키는지 따라가며 다음 확인 단계로 넘어가는 것입니다.

1. docker compose ps
2. docker compose logs --tail=100
3. docker compose config
4. .env 파일 확인
5. Volume / Bind Mount 확인
6. Docker network 확인
7. 최근 업데이트 또는 변경 이력 확인

이 순서가 모든 상황에서 정답이 되는 건 아닙니다. 다만, Intel N100 홈서버처럼 한 대의 장비에서 여러 Docker 서비스를 돌릴 때는, 무턱대고 문제를 짐작하기보다 로그를 바탕으로 원인 범위를 좁혀가는 게 훨씬 더 안정적이었습니다.

운영 로그

아래 표는 4주차 금요일에 정리한 Docker 로그 분석 및 장애 추적 점검 항목입니다. 실제로 점검을 진행할 때는 서비스 종류나 Compose 구성, 네트워크 구조, 업데이트 이력 등에 따라 확인 순서가 달라질 수 있습니다.

점검 항목	명령어	운영 판단
서비스 상태	docker compose ps	컨테이너 실행 여부와 재시작 상태 확인
최근 로그	docker compose logs --tail=100	오류 유형과 발생 시점 확인
실시간 로그	docker compose logs -f	재시작 또는 접속 시점의 로그 변화 확인
설정 해석	docker compose config	환경 변수 치환 결과 확인
데이터 연결	docker inspect	Volume, Bind Mount, network 연결 확인

에디터의 해석 노트 (Editor's Lab Note)

• Docker를 처음 사용할 때는 문제가 생기면 설정 파일부터 열어봤습니다.
• 하지만 운영을 계속하다 보니 가장 먼저 확인해야 할 것은 로그였습니다.
• 로그는 문제를 해결해주지는 않지만, 어디를 봐야 하는지 알려주는 지도에 가까웠습니다.
• 현재 Intel N100 홈서버에서는 상태 확인 → 로그 확인 → 설정·데이터·네트워크 점검 순서가 가장 현실적이었습니다.

참고 링크 (References)

1. docker compose logs reference
2. docker logs reference
3. docker compose ps reference
4. docker compose config reference
5. docker inspect reference

트러블슈팅

문제: 컨테이너는 실행 중인데 외부에서 서비스에 접속되지 않음

컨테이너가 Up 상태라고 해서 서비스가 정상적으로 접속된다는 뜻은 아닙니다. 내부 애플리케이션 오류나 환경 변수 누락, 리버스 프록시 연결 문제, 도커 네트워크 분리, 그리고 내부 포트 오류 등 여러 가지가 원인일 수 있습니다.

확인: 서비스 상태, 로그, 설정값, network, Proxy 연결 순서로 점검

# 1. 서비스 상태 확인
docker compose ps

# 2. 최근 로그 확인
docker compose logs --tail=100

# 3. 설정 최종 해석 확인
docker compose config

# 4. 컨테이너 network 확인
docker inspect 컨테이너이름 --format='{{json .NetworkSettings.Networks}}'

# 5. Mount 정보 확인
docker inspect 컨테이너이름 --format='{{json .Mounts}}'

원인 : 컨테이너는 실행 중이지만 내부 서비스 오류, 환경 변수 적용 누락, network 연결 문제, Reverse Proxy 대상 포트 오류가 발생함

해결 : 로그를 보면 우선 어떤 오류인지 유형부터 파악하는 게 중요합니다. 그런 다음, 그 오류가 언급하는 설정 파일이나 데이터 경로, 네트워크 환경, 그리고 최근에 있었던 업데이트 이력 순으로 하나씩 점검해보면 문제의 원인을 찾는 데 도움이 됩니다.

지금과 같은 상황에서는 설정을 바로 변경하기보다는, 먼저 로그를 살펴보고 문제의 원인을 차근차근 좁혀 나간 후에 수정하는 것이 더 안전했습니다.

마무리

Docker 로그를 정리하면서 새삼 느낀 건, 로그가 단순히 오류만 기록하는 게 아니라 운영자가 문제의 흐름을 따라가며 해결할 수 있게 돕는 중요한 힌트라는 점이었습니다. 서비스 장애가 발생했을 때 무턱대고 설정부터 건드리기보다는, 로그를 꼼꼼히 살펴보면 원인을 훨씬 빠르고 정확하게 좁힐 수 있었습니다.

네트워크는 연결 구조였고, Volume은 데이터 구조였으며, .env는 설정 구조였습니다. 업데이트 정책은 마치 유지보수의 뼈대와 같았고, 로그는 문제가 발생했을 때 그 구조를 한 걸음씩 되짚어갈 수 있게 도와주는 길잡이 역할을 했습니다.

이번 금요일에 내린 결론은 아주 간단합니다. 문제가 생기면 설정부터 들여다보기보다는, 먼저 로그를 확인하는 게 중요하다는 걸 다시 한 번 느꼈습니다. 내일 토요일에는 이 흐름을 이어서 Docker Compose 운영 체크리스트를 만들어보고, 주간 점검해야 할 부분도 한 번에 정리할 예정입니다.