업데이트 후 프로그램이 실행되지 않을 때 점검 순서

이런 상황일 때

업데이트를 올렸는데 화면이 안 뜹니다. 검색해 보면 비슷한 증상에 서로 다른 해결책이 잔뜩 나오는데, 어느 것이 제 경우인지 모른 채 이것저것 따라 하다 더 꼬입니다.

한 줄 결론

해결책을 찾기 전에 범위를 좁히세요. 순서는 넷입니다 — 떠 있는가 → 로그가 남았는가 → 포트를 잡았는가 → 설정을 읽었는가. 이 순서를 건너뛰면 남의 문제의 해결책을 내 환경에 적용하게 됩니다.

핵심 개념

① 떠 있는가

프로세스나 컨테이너 자체가 살아 있는지 봅니다. 계속 재시작을 반복하고 있다면 설정이나 데이터 쪽이고, 아예 안 떴다면 이미지나 명령 쪽입니다.

② 로그가 남았는가

로그가 한 줄이라도 있으면 프로그램이 시작은 했다는 뜻입니다. 아예 없으면 시작조차 못 한 것이고, 그때는 이미지·명령·권한 쪽을 봅니다.

③ 포트를 잡았는가

프로그램은 떴는데 화면이 안 뜨는 경우, 대개 포트에서 갈립니다. 다른 것이 이미 그 포트를 쓰고 있거나, 묶인 주소가 달라졌을 수 있습니다.

④ 설정을 읽었는가

앞의 셋이 멀쩡하면 설정 형식이 바뀐 경우가 많습니다. 로그에 그 항목 이름이 찍혀 있는 것이 보통입니다.

공식으로 확인된 문제와 내 환경 문제를 나눈다

같은 증상이라도 원인이 다를 수 있습니다. 이슈 목록에 같은 판·같은 조건으로 보고된 것이 있는지 먼저 확인하세요. 없다면 내 환경 쪽일 가능성이 큽니다.

이런 분에게 해당됩니다

• 업데이트 뒤 서비스가 뜨지 않아 곤란한 홈서버 사용자
• 컨테이너가 재시작을 반복하는 것을 보고 있는 분
• 검색 결과를 따라 하다 더 꼬인 경험이 있는 분

확인해야 할 항목

• 컨테이너나 서비스가 살아 있는가
• 재시작을 반복하고 있는가
• 로그에 줄이 남았는가
• 포트를 다른 것이 쓰고 있지 않은가
• 설정 항목 이름이 로그에 찍혀 있는가
• 같은 판에서 같은 증상이 보고돼 있는가

잘못 이해하기 쉬운 부분

안전한 행동 순서

1. 먼저 로그를 파일로 남깁니다. 되돌리면 사라집니다.
2. 컨테이너나 서비스가 살아 있는지 봅니다.
3. 로그에 줄이 남았는지 봅니다. 없으면 이미지·명령·권한 쪽입니다.
4. 떴는데 안 닿으면 포트를 확인합니다.
5. 여기까지 멀쩡하면 로그에서 설정 항목 이름을 찾습니다.
6. 찾은 낱말로 그 프로그램의 이슈 목록을 검색합니다. 같은 판으로 보고된 것만 봅니다.
7. 해결이 안 되면 되돌립니다. 남겨 둔 로그를 갖고 이슈를 올리면 됩니다.

① 떠 있는가

docker compose ps

State 가 restarting 이면 계속 죽고 있다는 뜻입니다 · 확인: 2026-08-05 · wp3 VM (Debian, Docker Compose v2)

② 로그가 남았는가 (되돌리기 전에 먼저)

docker compose logs --tail 50 <서비스이름>

<서비스이름> 은 compose 파일에 적힌 이름입니다. 한 줄도 없으면 시작조차 못 한 것입니다 · 확인: 2026-08-05 · wp3 VM (Debian, Docker Compose v2)

컨테이너가 아닌 경우 (systemd)

journalctl -u <서비스이름> -n 50 --no-pager

–no-pager 를 빼면 화면이 멈춘 것처럼 보입니다 · 확인: 2026-08-05 · wp3 VM (Debian, Docker Compose v2)

확인 체크리스트

• 되돌리기 전에 로그를 남겼다
• 서비스가 살아 있는지 확인했다
• 로그에 줄이 있는지 확인했다
• 포트를 확인했다
• 같은 판으로 보고된 이슈가 있는지 찾아봤다

관련 도구와 버전 페이지

• 알려진 문제 추적 — 아직 제공하지 않습니다
  어떤 판에 어떤 문제가 보고됐는지 이 사이트는 아직 모으지 않습니다. 각 제품의 이슈 목록을 직접 보셔야 합니다.

자주 묻는 것

로그가 너무 길어 어디를 봐야 할지 모르겠습니다.

맨 처음부터 보세요. 마지막 오류는 대개 앞에서 일어난 일의 결과입니다. 시작 부분에 진짜 원인이 적혀 있는 경우가 많습니다.

재시작을 반복하는데 로그가 계속 지워집니다.

위 명령으로 남겨 두면 됩니다. 재시작해도 이전 기록은 남아 있습니다.

되돌렸는데도 안 됩니다.

데이터가 이미 새 형식으로 바뀐 경우입니다. 이때는 백업에서 데이터까지 되살려야 합니다.