Docker 컨테이너가 계속 재시작될 때 로그 확인 방법

이런 상황일 때

홈서버의 서비스 하나가 안 열려 docker ps 를 쳐 보니 상태가 Restarting 입니다. 잠시 뒤 다시 봐도 여전히 Restarting 이고, 괄호 안 숫자와 '몇 초 전' 이라는 시간만 바뀝니다. 지우고 다시 만들어야 하나 고민 중입니다.

한 줄 결론

지우기 전에 로그부터 남기세요. 재시작 반복은 원인이 반드시 기록에 남는 실패입니다. 순서는 셋입니다 — 상태 옆 종료 코드 → 로그 마지막 오류 → 설정·마운트. 이 순서로 보면 대부분 지우지 않고도 원인이 나옵니다.

핵심 개념

재시작 정책은 원인을 고치지 않는다

unless-stopped 나 on-failure 같은 재시작 정책은 실패한 컨테이너를 다시 띄울 뿐입니다. 원인이 그대로면 같은 실패가 그대로 반복됩니다 — 시험 환경에서 잘못된 설정 하나로 8초 만에 재시작이 7회 쌓였습니다.

상태 옆 괄호가 첫 단서다

docker ps 의 Restarting (1) Less than a second ago 에서 괄호 안 1 이 종료 코드입니다. 0이 아닌 작은 수는 대개 프로그램이 스스로 낸 오류(로그를 볼 것), 137 은 밖에서 강제 종료된 것(메모리 부족이 흔한 원인), 126·127 은 명령 자체를 실행하지 못한 것입니다.

로그는 재시작을 가로질러 쌓인다

docker logs 는 재시작이 반복되는 중에도 동작하고, 이전 시도의 기록까지 이어서 보여 줍니다. 다만 컨테이너를 지우면 로그도 함께 사라집니다. 지우고 다시 만들기 전에 로그를 파일로 남겨야 하는 이유입니다.

시작조차 못 한 실패는 로그가 거의 없다

명령을 찾지 못하는 경우(종료 코드 127)는 로그가 한 줄뿐이거나 비어 있습니다. 이때는 로그 대신 docker inspect 의 상태 필드가 말해 줍니다 — 종료 코드, 강제 종료 여부, 재시작 횟수가 거기 있습니다.

지금 추적 중인 버전

이 표의 값은 공식 릴리스에서 가져온 것이며, 아래 마지막 검토일 기준입니다.

이런 분에게 해당됩니다

• Docker 로 서비스를 돌리는 홈서버 사용자
• docker ps 에서 Restarting 을 처음 본 분
• 지웠다 다시 만들기를 반복했는데 같은 증상이 돌아온 분

확인해야 할 항목

• 상태가 Restarting 인가, 괄호 안 종료 코드는 몇인가
• 재시작 횟수(RestartCount)가 계속 늘고 있는가
• 로그 마지막 50줄에 오류 문장이 있는가
• 로그가 아예 비어 있는가 — 시작 실패의 신호다
• 강제 종료(OOMKilled)로 표시돼 있는가
• 최근에 이미지 태그·설정·마운트 경로를 바꿨는가

잘못 이해하기 쉬운 부분

안전한 행동 순서

1. docker ps -a 로 상태를 봅니다. Restarting 옆 괄호의 종료 코드를 적어 둡니다.
2. 로그를 파일로 남깁니다. 아래 명령 그대로면 됩니다 — 재시작 중에도 동작합니다.
3. 로그 마지막 50줄에서 오류 문장을 찾습니다. 파일 경로·설정 항목·연결 실패가 흔한 갈래입니다.
4. 로그가 거의 없으면 docker inspect 로 종료 코드와 강제 종료 여부를 봅니다.
5. 갈래대로 짚습니다 — 작은 수는 로그의 오류를, 137 은 메모리 여유를, 126·127 은 명령·이미지를 봅니다.
6. 원인을 고친 뒤 상태가 Up 으로 유지되는지, 재시작 횟수가 더 늘지 않는지 확인합니다.
7. 그래도 반복되면 쓰고 있는 판(버전) 그대로 이슈 목록을 검색합니다. 점검 순서 글의 마지막 단계와 같습니다.

① 상태와 재시작 횟수

docker ps -a
docker inspect <컨테이너이름> --format '{{.RestartCount}}회 재시작'

서버 셸에서 실행합니다(관리자 권한 불필요, docker 그룹 필요). 상태 예: Restarting (1) — 괄호가 종료 코드입니다 · 확인: 2026-08-07 · wp3 VM (Debian, Docker Engine 29.7.1)

② 로그 남기고 읽기 (지우기 전에 먼저)

docker logs <컨테이너이름> > container.log 2>&1
docker logs --tail 50 <컨테이너이름>

읽기만 하는 명령입니다. 시험 환경의 실제 마지막 줄: nginx: [emerg] open() "/etc/nginx/no-such.conf" failed (2: No such file or directory) · 확인: 2026-08-07 · wp3 VM (Debian, Docker Engine 29.7.1)

③ 종료 코드·강제 종료 여부

docker inspect <컨테이너이름> --format '코드 {{.State.ExitCode}} · 강제종료 {{.State.OOMKilled}}'

시험 환경 출력: 잘못된 설정은 코드 1, 없는 명령은 코드 127 이었습니다. 강제종료가 true 면 메모리 부족이 흔한 원인입니다 · 확인: 2026-08-07 · wp3 VM (Debian, Docker Engine 29.7.1)

확인 체크리스트

• Restarting 옆 괄호의 종료 코드를 적었다
• 지우기 전에 로그를 파일로 남겼다
• 종료 코드·강제 종료 여부·재시작 횟수를 확인했다
• 설정 파일·마운트 경로에서 최근 바꾼 것을 확인했다
• 고친 뒤 상태가 Up 으로 유지되는 것을 확인했다

관련 도구와 버전 페이지

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

자주 묻는 것

로그가 아예 비어 있습니다.

프로그램이 시작조차 못 한 것입니다. 종료 코드 127(명령을 못 찾음)·126(실행 불가)이 흔하고, 최근 이미지나 실행 명령을 바꿨다면 그쪽부터 보세요. 볼 곳이 오히려 좁아진 상태입니다.

재시작이 너무 빨라 로그를 못 잡을 것 같습니다.

괜찮습니다. docker logs 는 재시작이 반복되는 중에도 동작하고 이전 시도의 기록까지 이어서 보여 줍니다. 위 명령으로 파일로 남겨 두고 천천히 읽으세요.

종료 코드가 137 입니다.

프로그램 잘못이 아니라 밖에서 끊긴 것입니다. 메모리 부족으로 강제 종료된 경우가 흔합니다 — inspect 의 강제종료 필드가 true 인지, 서버의 메모리 여유가 있는지 확인하세요.