DevOps 지식 허브
DevOps 지식 허브

Docker 컨테이너 문제 해결: 일반적인 시작 문제 및 해결 방법

이 실용적인 가이드를 통해 일반적인 Docker 컨테이너 시작 실패를 해결하십시오. `docker logs` 및 `docker inspect`를 사용하여 컨테이너가 즉시 종료되는 이유를 진단하는 방법을 배우십시오. 포트 충돌, 잘못된 진입점, 볼륨 권한 오류 및 OOM 종료에 대한 필수 수정 사항을 다루어 애플리케이션이 안정적으로 실행되도록 보장합니다.

39 조회수

Docker 컨테이너 문제 해결: 일반적인 시작 문제 및 해결 방법

Docker 컨테이너 시작은 이상적으로는 원활해야 하지만, 실제로는 장애물에 부딪히는 경우가 많습니다. 컨테이너화가 처음이든 숙련된 개발자이든, 시작되지 않거나 즉시 종료되거나 예상치 못한 동작을 하는 컨테이너에 직면하는 것은 흔한 과제입니다. 이 가이드는 Docker 애플리케이션 실행 시 발생하는 가장 빈번한 시작 실패를 진단하고 해결하기 위한 기술적인 플레이북 역할을 합니다.

컨테이너가 실패하는 이유를 이해하는 것이 수정의 첫걸음입니다. 포트 충돌, 잘못된 명령 실행, 누락된 종속성, 볼륨 및 네트워킹 관련 문제 등 일반적인 원인을 체계적으로 살펴보고, 원활한 컨테이너 작업을 복구하는 데 필요한 필수 명령과 논리를 제공할 것입니다.

필수 첫 단계: 진단

특정 오류 유형에 깊이 들어가기 전에 기본적인 진단 명령을 익히는 것이 중요합니다. 이러한 도구는 문제를 정확히 파악하는 데 필요한 즉각적인 증거를 제공합니다.

1. 컨테이너 상태 확인

항상 docker ps (실행 중인 컨테이너) 또는 docker ps -a (중지된 컨테이너를 포함한 모든 컨테이너)를 사용하여 컨테이너의 현재 상태를 확인하는 것으로 시작하십시오. 컨테이너에 Exited 상태가 표시되면 컨테이너 내부 프로세스가 시작 시 즉시 종료되었음을 의미합니다.

docker ps -a
# STATUS 및 PORTS 열을 확인하세요

2. 컨테이너 로그 검토

빠르게 종료되는 컨테이너의 경우, 로그에 결정적인 단서가 있는 경우가 많습니다. docker logs 명령은 컨테이너의 메인 프로세스에서 표준 출력 및 표준 오류 스트림을 검색합니다.

# <container_id_or_name>을 실제 ID 또는 이름으로 바꾸세요
docker logs <container_id_or_name>

# 실시간으로 로그를 보려면 -f를 사용하거나, 마지막 N줄을 보려면 --tail N을 사용하세요
docker logs --tail 50 <container_id_or_name>

3. 컨테이너 세부 정보 검사

docker inspect 명령은 State 객체, 구성 세부 정보, 마지막 종료 코드를 포함한 방대한 저수준 정보를 제공합니다.

docker inspect <container_id_or_name> | grep -A 10 State

0이 아닌 종료 코드(예: OOM kill의 경우 ExitCode: 137, 애플리케이션 오류의 경우 ExitCode: 1)는 종종 근본적인 문제를 직접적으로 나타냅니다.

일반적인 시작 문제 1: 포트 충돌

호스트 포트를 컨테이너 포트에 매핑할 때 (-p 플래그) 가장 빈번하게 발생하는 오류일 것입니다.

문제

호스트의 8080 포트를 컨테이너의 80 포트에 매핑하는 컨테이너를 시작하려고 하는데, 다른 서비스(다른 컨테이너 또는 로컬 애플리케이션)가 이미 호스트 포트 8080을 사용 중인 경우, Docker는 포트 바인딩에 실패하고 컨테이너가 종료되거나 시작되지 않을 수 있습니다.

진단

이런 일이 발생하면 시작 명령이 일반적으로 즉시 실패하고, 로그에 바인딩 오류 또는 already in use 메시지가 나타날 수 있습니다.

해결책

  1. 호스트 포트 변경: 컨테이너 포트를 호스트 머신의 다른 사용되지 않는 포트에 매핑합니다.
    ```bash
    # 원래 (실패):
    docker run -d -p 8080:80 my-web-app

    해결책 (8081 사용):

    docker run -d -p 8081:80 my-web-app
    `` 2. **충돌 식별:** 운영 체제 도구를 사용하여 어떤 것이 해당 포트를 사용하고 있는지 찾습니다. * **Linux/macOS:**sudo lsof -i :8080또는sudo netstat -tuln | grep 8080* **Windows (PowerShell):**Get-NetTCPConnection -LocalPort 8080`

일반적인 시작 문제 2: 잘못된 Entrypoint 또는 Command

컨테이너는 Dockerfile의 ENTRYPOINT 및 CMD에 의해 정의된 특정 전면 프로세스를 실행하도록 설계되었습니다. 이 명령이 잘못되면 컨테이너가 즉시 종료됩니다.

문제

  • 이미지에서 지정된 실행 파일의 철자가 틀렸거나 누락되었습니다.
  • 셸 스크립트 종속성이 누락되었습니다(예: 이미지에 Python이 설치되지 않은 상태에서 Python 스크립트 실행 시도).
  • 명령에 제공되지 않은 인수가 필요합니다.

진단

docker logs를 확인하십시오. 종종 command not found, No such file or directory 또는 특정 애플리케이션 시작 예외와 같은 오류가 표시됩니다.

해결책

  1. 대화형 모드에서 테스트: 기본 명령을 재정의하여 컨테이너 내에서 셸 세션을 실행하고 실행 경로를 수동으로 테스트합니다.
    ```bash
    # 알려진 셸(예: bash)을 사용하여 이미지를 대화형으로 실행
    docker run -it --entrypoint /bin/bash my-failing-image

    내부로 들어가면 경로를 수동으로 확인하고 의도한 시작 명령을 실행합니다.

    `` 2. **Dockerfile 확인:** 이미지의 Dockerfile에서CMD및ENTRYPOINT줄을 검토합니다. 필요한 경우 경로가 절대 경로인지, 또는 올바른 exec 형식(["executable", "param1"]`)을 사용하고 있는지 확인합니다.

모범 사례: 살아 있어야 하는 컨테이너(예: 웹 서버)를 실행할 때 실행하는 명령이 전면(foreground)에서 실행되는지 확인하십시오. 프로세스가 즉시 백그라운드(데몬화)로 포크되면 Docker는 컨테이너의 기본 작업이 완료된 것으로 간주하고 중지합니다.

일반적인 시작 문제 3: 볼륨 마운팅 오류

영구 데이터는 일반적으로 Docker 볼륨 또는 바인드 마운트 (-v 플래그)를 통해 처리됩니다. 애플리케이션이 해당 데이터에 크게 의존하는 경우 여기서의 잘못된 구성은 시작을 방해할 수 있습니다.

문제

  • 바인드 마운트 권한: 컨테이너 내부의 사용자에게 호스트에서 마운트된 디렉토리에 대한 읽기/쓰기 권한이 없습니다.
  • 호스트 디렉토리 누락 (바인드 마운트): 바인드 마운트를 사용할 때 호스트의 소스 디렉토리가 존재하지 않으면 Docker가 조용히 실패하거나 예기치 않게 동작할 수 있습니다(명명된 볼륨은 생성을 더 잘 처리하지만).

진단

애플리케이션이 로그에서 I/O 오류 또는 권한 거부 오류를 발생시키는 경우 볼륨 문제를 의심하십시오.

해결책

  1. 권한 확인: 컨테이너 내부에서 프로세스를 실행하는 UID/GID가 호스트의 마운트된 디렉토리 소유권과 일치하는지, 또는 디렉토리에 모든 사용자 읽기/쓰기 권한이 있는지 확인합니다(예: chmod 777 /path/on/host).
  2. 명명된 볼륨 사용: 직접적인 호스트 파일 시스템 액세스가 필요하지 않은 데이터의 지속성을 위해 명명된 볼륨을 사용하는 것이 일반적으로 더 안전하고 이식성이 좋습니다.
    bash docker volume create my_app_data docker run -d -v my_app_data:/var/lib/app my-app

일반적인 시작 문제 4: 이미지 가져오기 또는 빌드 실패

이미지 자체가 사용 불가능하거나 손상되어 컨테이너가 전혀 시작되지 않는 경우.

문제

  • 지정된 이미지 이름 또는 태그가 레지스트리(예: Docker Hub)에 존재하지 않습니다.
  • 네트워크 연결 문제로 이미지를 가져올 수 없습니다.
  • 빌드 프로세스가 실패하여 불완전하거나 태그가 지정되지 않은 로컬 이미지가 생성되었습니다.

해결책

  1. 태그 확인: 철자와 태그 버전(myimage:latest 대 myimage:v1.0)을 다시 확인합니다.
  2. 명시적으로 가져오기: 네트워크/레지스트리 문제를 분리하기 위해 이미지를 수동으로 가져옵니다.
    bash docker pull myimage:mytag
  3. 빌드 로그 확인: 사용자 정의 이미지를 사용하는 경우 docker build .를 실행하고 실행하기 전에 오류 없이 성공적으로 완료되었는지 확인합니다.

고급 문제 해결: 리소스 제한

컨테이너가 시작된 후 즉시 중지되는 경우, 특히 부하가 심한 경우 리소스 고갈로 인해 종료되었을 수 있습니다.

OOM Killer

가장 일반적인 리소스 종료는 메모리 부족(OOM) 킬러입니다. 컨테이너가 명시적으로 --memory로 설정되었거나 호스트 시스템 제약에 의해 암묵적으로 제한된 것보다 더 많은 RAM을 사용하려고 하면 커널이 이를 종료할 수 있습니다.

진단: docker inspect를 통해 컨테이너의 종료 코드를 확인합니다. 종료 코드 137은 컨테이너가 외부에서 종료되었음을 강력하게 나타내며, 종종 OOM 때문입니다.

해결책: Docker Desktop에 할당된 메모리를 늘리거나, 가능한 경우 컨테이너의 메모리 사용량을 명시적으로 제한하여 호스트의 사용 가능한 리소스를 초과하지 않도록 합니다.

# 이 특정 컨테이너에 1기가바이트 RAM 제한
docker run -d --memory="1g" my-heavy-app

요약 및 다음 단계

Docker 시작 문제 해결은 명확한 진단 경로를 따릅니다: 상태 확인 -> 로그 검토 -> 검사 -> 격리. 대부분의 실패는 환경 불일치(포트, 권한) 또는 잘못된 프로세스 실행(CMD/ENTRYPOINT)에서 비롯됩니다. docker ps -a, docker logs, docker inspect를 체계적으로 사용하면 실패한 시작에서 해결된 컨테이너로 빠르게 이동할 수 있습니다.

모든 방법이 실패하면 컨테이너를 완전히 제거(docker rm)하고 명령을 다시 실행해 보십시오. 복잡성을 줄여(예: 볼륨 또는 네트워크 설정 제거) 기본 이미지가 먼저 올바르게 작동하는지 확인할 수 있습니다.