홈서버에 장애가 발생했을 때 점검해야 할 순서를 정리

 

Intel N100 기반에서 Docker로 운영 중이라면, 아래 루틴을 참고하면 좋겠습니다.

1. 서버 전원 및 하드웨어 상태 확인 : 먼저 서버가 정상적으로 작동하고 있는지 확인하세요. 단순히 전원을 껐다 켜는 것이 아니라, 전원 LED에 불이 들어오는지, 팬이 제대로 돌아가는지 살펴봐야 합니다. 또 발열이나 소음에서 평소와 다른 점이 없는지도 함께 체크하면 좋습니다.

2. 네트워크 연결 상태 점검 : 랜 케이블이 제대로 꽂혀 있는지 한번 확인해 보세요. 또 라우터나 스위치 같은 네트워크 장비에 문제가 없는지도 살펴보면 좋습니다. 집 안에 있는 다른 기기들도 인터넷이 잘 되는지 같이 점검하면, 문제의 원인을 찾는 데 도움이 됩니다.

3. 원격 접속 시도 : SSH 등 원격 접속 방식으로 서버에 접속할 수 있는지 먼저 확인해 보세요. 만약 원격 접속이 되지 않는다면, 모니터와 키보드를 직접 연결해 콘솔 화면에 에러 메시지가 뜨는지 살펴보면 됩니다.

4. Docker 서비스 상태 확인 : 서버에 접속했다면 가장 먼저 Docker가 정상적으로 작동 중인지 확인해야 합니다.

'shell systemctl status docker '

위 명령어를 입력하면 Docker가 현재 실행 중인지 바로 알 수 있습니다.

5. 컨테이너 개별 점검 : Docker가 정상적으로 실행되고 있다면, 먼저 `docker ps` 명령어로 각 컨테이너가 잘 돌아가고 있는지 확인해보세요. 그리고 컨테이너별로 로그를 살펴보면서 문제가 있는지 점검합니다. 만약 이상이 있는 컨테이너가 있으면, `docker logs [컨테이너 이름]` 명령을 사용해 어떤 오류가 발생했는지 구체적으로 확인할 수 있습니다

6. 디스크, CPU, 메모리 등 리소스 점검 : `top`, `htop`, `df -h` 같은 명령어를 이용해 서버의 하드웨어 리소스 상태를 꼭 확인해보세요. 갑자기 디스크 용량이 가득 찼거나, CPU와 메모리 사용률이 100%에 가까우면 서비스가 중단될 수 있습니다. 평소보다 자원이 빠르게 소모되는지 살펴보는 것도 도움이 됩니다.

7. 로그 파일 추가 확인 : 시스템에서는 주로 `/var/log/syslog`나 `/var/log/messages`와 같은 기본 로그 파일을 참고하면 도움이 됩니다. 또, Docker 서비스를 사용하고 있다면 Docker 관련 로그도 함께 확인해 보세요. 이러한 로그를 꼼꼼하게 살펴보면 문제의 원인을 좀 더 쉽게 찾을 수 있습니다.

최근에 무슨 에러가 발생했는지, 언제부터 문제가 있었는지 단서가 될 수 있습니다.

이런 식으로 하나씩 차근차근 문제의 원인을 좁혀 나가면, 홈서버 장애가 발생했을 때 빠르게 정상화할 수 있습니다.

평소에도 가끔씩 리소스 사용량이나 Docker 상태를 체크하면, 미리 문제를 예방하는 데 도움이 됩니다.

※ 이 글은 운영자가 직접 홈서버를 운영하며 얻은 경험과 Docker 공식 문서를 참고해 작성한 것입니다. 문장 다듬기와 구성에는 AI 도구를 부분적으로 활용했지만, 최종 내용은 운영자가 꼼꼼히 검토해 완성했습니다.

홈서버에 장애가 발생했을 때 점검해야 할 순서 정리 

 

도입

이번 주엔 Intel N100 홈서버에서 Docker를 어떻게 운영할지 하나씩 정리해봤어요. 월요일엔 Compose 구조를 다시 점검했고, 화요일에는 백업 자동화와 운영 데이터 보존 과정을 정리했죠. 수요일엔 로그가 제대로 순환되는지, 디스크 용량은 괜찮은지 확인했고, 목요일에는 Reverse Proxy 설정과 외부에서 서버에 접근하는 구조를 다시 한번 살펴봤어요.

금요일에는 이런 흐름을 바탕으로 실제로 문제가 발생했을 때 어떤 순서로 점검하면 좋을지 정리해볼 생각입니다. 홈서버를 직접 운영하다 보면 서비스가 접속되지 않거나, 외부에서 접근이 안 되거나, 컨테이너가 계속 재시작된다든지, 갑자기 디스크 용량이 확 늘어나는 등 다양한 상황을 겪게 됩니다.

이번 글에서 전하고자 하는 핵심은 ‘장애를 완벽하게 막아낸다’는 데 있지 않습니다. 실제 서비스 운영을 하다 보면, 장애를 아예 없앨 수는 없습니다. 오히려 문제가 발생했을 때 어디부터 점검할지 미리 순서를 정해두는 것이 훨씬 현실적이죠. 이런 확인 순서가 있으면, 당황해서 허둥대는 시간을 줄일 수 있고, 빠르게 원인을 좁혀나갈 수 있습니다.

Intel N100 홈서버에서 Docker 서비스 장애 발생 시 상태, 로그, 디스크, 네트워크, Reverse Proxy, 백업을 순서대로 점검하는 운영 흐름입니다.

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

본문

장애 대응은 원인을 맞히는 일이 아니라 범위를 줄이는 일이었다

홈서버에 문제가 생기면 처음에는 바로 원인을 찾아내고 싶어지죠. 하지만 실제로 운영해보면, 처음부터 정확한 원인을 짚어내기보다는 하나씩 확인 범위를 좁혀가며 점검하는 게 훨씬 안정적이라는 걸 알게 됩니다.

예를 들어, 외부에서 서비스 접속이 안 된다고 바로 Reverse Proxy에 문제가 있다고 단정하긴 어렵습니다. 컨테이너가 중지됐을 수도 있고, Docker 네트워크가 끊겼거나 디스크 용량이 꽉 차서 서비스에 영향을 준 것일 수도 있습니다. 혹은 DNS 설정이나 SSL 인증서에 문제가 생겼을 가능성도 있습니다.

• 서비스가 실제로 실행 중인지 확인
• 최근 로그에 오류가 있는지 확인
• 디스크와 Docker 사용량이 임계점에 가까운지 확인
• Docker network와 내부 서비스 연결을 확인
• Reverse Proxy와 도메인 연결 상태를 확인
• 최근 변경 사항과 백업 상태를 확인

이렇게 순서를 미리 정해두니, 장애가 발생했을 때 감정적으로 추측하며 대응하기보다 일상적인 운영처럼 차분하게 처리할 수 있게 됐습니다.

1단계 : 서비스 상태부터 확인했다

가장 먼저 확인한 것은 컨테이너가 실제로 실행 중인지 여부였습니다. Docker Compose 기반으로 운영 중이라면 docker compose ps가 첫 번째 확인 지점이 되었습니다.

# 현재 디렉터리의 Compose 서비스 상태 확인
docker compose ps

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

여기서는 단순히 Up 상태인지뿐 아니라, Exited, Restarting, 반복 재시작 상태가 있는지도 함께 확인해야 했습니다. 컨테이너가 살아 있더라도 내부 서비스가 정상적으로 응답하지 않을 수 있기 때문에, 이 단계는 시작일 뿐, 최종 결론으로 볼 수는 없습니다.

상태	의미	운영 판단
Up	컨테이너 실행 중	다음 단계에서 로그와 응답 상태 확인
Exited	컨테이너 종료됨	종료 원인 로그 확인 필요
Restarting	반복 재시작 중	설정, 권한, 의존 서비스, volume 확인 필요

2단계 : 최근 로그를 확인했다

컨테이너 상태를 확인한 뒤에는 로그를 봤습니다. Docker 공식 문서 기준으로 docker logs는 컨테이너의 로그를 가져오는 명령이며, --tail 옵션을 사용하면 최근 일부 로그만 확인할 수 있습니다.

# 특정 컨테이너 최근 로그 확인
docker logs 컨테이너이름 --tail=100

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

# 실시간 로그 따라가기
docker logs -f 컨테이너이름

이 단계에서는 오류 메시지만 보고 단정하지 않고, 문제가 어떤 유형인지 먼저 파악하는 데 집중했습니다. 권한 문제인지, 포트 충돌이나 데이터 경로의 문제인지, 또는 네트워크나 설정 파일과 관련된 건지 등 원인을 구분하는 게 중요했죠.

• permission denied : 파일 권한 또는 실행 권한 확인
• address already in use : 포트 충돌 가능성 확인
• connection refused : 내부 서비스 또는 네트워크 연결 확인
• no such file : volume, bind mount, 경로 설정 확인
• authentication failed : 계정, 토큰, 환경 변수 확인

3단계 : 디스크 사용량을 확인했다

서비스가 제대로 올라오지 않을 때, 디스크 공간도 의외로 자주 점검해야 했습니다. 특히 Intel N100 미니 PC처럼 SSD 용량이 넉넉하지 않은 환경에서는 Docker 이미지나 볼륨, 로그, 백업 파일 등이 한데 쌓여 금세 공간이 부족해질 수 있습니다. 

# 전체 파일시스템 사용량 확인
df -h

# Docker 사용량 확인
docker system df

# 백업 디렉터리 크기 확인 예시
du -sh /backup

docker system df는 Docker 데몬이 사용하는 디스크 공간 정보를 보여줍니다. 이미지, 컨테이너, 로컬 볼륨, 빌드 캐시의 크기를 확인할 때 이 명령어가 꽤 유용했습니다. 하지만 이것만으로 모든 원인을 알 수 있는 건 아니어서, 필요에 따라 백업 디렉터리나 systemd 저널 로그도 함께 살펴봐야 했습니다.

디스크가 부족해 보인다고 해서 곧바로 docker system prune --volumes를 실행하는 것은 피했습니다. volume에는 실제 서비스 데이터가 들어 있을 수 있기 때문입니다. 먼저 무엇이 커졌는지 확인하고, 백업 여부를 확인한 뒤 정리하는 편이 더 안전했습니다.

4단계 : Docker network를 확인했다

컨테이너가 정상적으로 실행되고 있고 로그에도 별다른 오류가 나타나지 않는데, 서비스들 사이에 연결이 되지 않는다면 Docker 네트워크 설정을 점검해봐야 합니다. 예를 들어 Reverse Proxy가 내부 서비스에 접근하지 못하거나, 서비스 이름으로 연결이 되지 않는 상황이 여기에 해당할 수 있습니다.

# Docker network 목록 확인
docker network ls

# 컨테이너 네트워크 상세 확인
docker inspect 컨테이너이름 --format='{{json .NetworkSettings.Networks}}'

특히 Reverse Proxy, n8n, 미디어 서버, 그리고 관리용 서비스가 각각 다른 Compose 디렉터리에서 실행된다면, 이 서비스들이 같은 네트워크에 제대로 연결되어 있는지 별도로 확인하는 과정이 필요할 수 있습니다.

실제로 네트워크에 문제가 있다고 생각되면, 우선 도메인부터 살펴보기보다는 내부 컨테이너들끼리 제대로 통신이 되는지 먼저 확인하는 것이 더 현실적이었습니다.

5단계 : Reverse Proxy와 외부 접속 경로를 확인했다

외부에서는 접속이 되지 않지만 내부에서는 서비스가 잘 된다면, 우선 Reverse Proxy 설정과 도메인 경로를 다시 한번 점검해봐야 합니다. 목요일에 정리했던 내용처럼, 외부에서 접속이 이루어질 때는 여러 단계를 거치게 되죠. 각각의 구간에서 문제가 생길 수 있으니, 하나씩 꼼꼼히 살펴보는 게 중요합니다.

도메인 / DNS
↓
공유기 포트포워딩
↓
Reverse Proxy
↓
Docker 내부 서비스

이때 저는 먼저 DNS 레코드를 확인한 뒤, 포트포워딩 설정, SSL 인증서 상태, 그리고 Proxy Host의 내부 주소와 포트를 차례로 살펴봤어요. 모든 설정을 한 번에 바꾸면 어디에서 문제가 발생했는지 알아내기 더 어려워지기 때문에, 요청이 어떻게 흐르는지 단계별로 나누어 차근차근 확인하는 게 훨씬 효과적이었습니다.

• 도메인 A 레코드 또는 CNAME 확인
• 공유기 80/443 포트포워딩 확인
• Nginx Proxy Manager Proxy Host 설정 확인
• Forward Hostname/IP와 Forward Port 확인
• SSL 인증서 발급 및 갱신 상태 확인

6단계 : 백업 상태를 확인했다

장애에 대응할 때 백업은 마지막에 생각할 선택지가 아니라, 항상 함께 챙겨야 하는 필수 운영 기준이었습니다. 설정을 바꾸기 전에 최근 백업이 있는지, Compose 파일과 .env, volume 데이터가 포함되어 있는지 확인하는 것이 안전했습니다.

# 백업 파일 확인 예시
ls -lh /backup

# 백업 디렉터리 크기 확인
du -sh /backup

# Compose 파일 위치 확인
find /opt/docker -name "compose.yml"

# 예약 백업 작업 확인
crontab -l

특히 설정을 바꾸거나 업데이트를 진행할 때, 볼륨 정리나 프루닝 관련 명령을 실행하기 전에 먼저 백업이 제대로 되어 있는지 확인하는 게 좋았습니다. 이렇게 하면 장애가 발생했을 때 문제를 더 키우지 않고 최소한의 안전장치는 마련할 수 있었습니다.

7단계 : 최근 변경 사항을 되짚었다

실제 운영에서는 장애 원인이 최근 변경 사항과 연결되는 경우가 많았습니다. Compose 파일을 수정했거나, .env 값을 바꿨거나, 이미지를 업데이트했거나, Reverse Proxy 설정을 만졌다면 그 변경이 문제의 출발점일 수 있습니다.

최근 변경	확인할 항목	운영 판단
Compose 수정	들여쓰기, 포트, volume, environment	설정 오류 가능성 확인
.env 수정	경로, 토큰, 시간대, 포트	변수 치환 오류 확인
이미지 업데이트	버전 변경, breaking change	릴리스 노트 확인 필요
Reverse Proxy 변경	도메인, 내부 포트, SSL	외부 접속 경로 확인
정리 명령 실행	image, container, volume	삭제 범위 확인 필요

운영 기록을 남기면 이 과정이 훨씬 수월해집니다. ‘어제 어떤 점을 바꿨지?’ 하고 기억만 더듬는 대신, 글이나 메모로 정리해두면 실제로 장애가 발생했을 때 대응하는 데 큰 도움이 되었습니다.

운영 로그

아래 표는 3주차 금요일을 기준으로 정리한 Docker 홈서버 장애 대응 점검 루틴입니다. 실제 장애 대응 순서는 발생한 장애의 종류나 서버의 환경에 따라 달라질 수 있습니다. 하지만 현재 Intel N100으로 운영하는 홈서버에서는 이 방식이 가장 관리하기 편리했어요.

순서	확인 항목	명령어 또는 기준
1	서비스 상태	docker compose ps, docker ps -a
2	최근 로그	docker compose logs --tail=100
3	디스크 사용량	df -h, docker system df
4	Docker network	docker network ls, docker inspect
5	Reverse Proxy	도메인, SSL, Proxy Host, 내부 포트 확인
6	백업 상태	ls -lh /backup, crontab -l
7	최근 변경 이력	Compose, .env, image update, proxy 변경 확인

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

• 장애 대응은 원인을 한 번에 맞히는 일이 아니라 확인 범위를 줄여가는 과정에 가까웠습니다.
• Intel N100 홈서버 환경에서는 서비스 상태, 로그, 디스크, 네트워크, 외부 접속 순서로 보는 것이 현실적이었습니다.
• 정리 명령이나 설정 변경 전에는 백업 상태를 먼저 확인하는 편이 안전했습니다.
• 운영 기록을 남겨두면 최근 변경 사항을 되짚을 수 있어 장애 대응 시간이 줄어들었습니다.

참고 링크 (References)

1. docker compose ps reference
2. docker logs reference
3. docker system df reference
4. Docker networking overview
5. docker network ls reference

트러블슈팅

문제 : Docker 서비스 장애가 발생했지만 어디부터 확인해야 할지 불명확함

홈서버에 장애가 발생하는 이유는 여러 가지가 한꺼번에 작용할 수 있습니다. 예를 들어, 컨테이너가 갑자기 멈췄거나 로그 파일이 너무 빨리 쌓여 저장 공간이 부족해졌을 수도 있습니다. 또, 디스크 공간 부족이 원인일 때도 있고, Docker 네트워크나 리버스 프록시, SSL, DNS 중 하나에 문제가 생겼을 가능성도 있습니다. 이처럼 원인이 다양하니, 각각의 부분을 차근차근 점검해 보는 것이 좋습니다.

확인 : 서비스 상태 → 로그 → 디스크 → 네트워크 → Reverse Proxy → 백업 → 최근 변경 이력 순서로 점검

# 1. 서비스 상태
docker compose ps
docker ps -a

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

# 3. 디스크 확인
df -h
docker system df

# 4. 네트워크 확인
docker network ls

# 5. 백업 확인
ls -lh /backup
crontab -l

원인: 장애 대응 순서가 정리되어 있지 않아 원인을 추측으로만 찾으려 함

해결: 반복 가능한 점검 루틴을 만들고, 각 단계에서 확인할 명령어와 판단 기준을 운영 문서로 남김

지금과 같은 상황에서는 “이것저것을 빠르게 바꾸는 것”보다 “정해진 순서대로 하나씩 좁혀가는 방법”이 장애를 대응하는 데 훨씬 더 안정적이었습니다.

마무리

Intel N100 홈서버에서 Docker 서비스를 운영하다 보면, 어떤 형태로든 장애가 생기는 걸 완전히 막는 건 쉽지 않습니다. 그래서 중요한 건 장애가 전혀 없는 것처럼 꾸미는 게 아니라, 실제로 문제가 생겼을 때 어디서부터 점검하면 되는지 명확히 알 수 있도록 구조를 짜는 일이었습니다.

이번 금요일에는 서비스 상태, 로그, 디스크, Docker 네트워크, 리버스 프록시, 백업, 그리고 최근 변경 이력 순으로 점검 루틴을 정리했습니다. 이 순서가 모든 환경에서 꼭 맞는 정답은 아니지만, 지금 Intel N100 홈서버를 운영하는 상황에서는 가장 현실적으로 점검할 수 있는 흐름이라고 생각합니다.

홈서버를 운영하다 보면, 완벽하게 장애가 없는 상태를 유지하는 것보다 장애가 발생했을 때 그 원인을 추적할 수 있는 상태를 만드는 게 더 중요하다고 느꼈습니다. 이번 주 토요일에는 그동안 쌓인 운영 점검 항목들을 데이터와 기록 중심으로 다시 한 번 정리해보려고 합니다. 이를 통해 앞으로 문제가 생기더라도 빠르게 원인을 파악할 수 있도록 준비하려고 합니다.