시놀로지 Container Manager 컨테이너가 Exit Code 1로 종료되는 이유

시놀로지 NAS에서 Docker 컨테이너를 운영하다 보면 Container Manager에서 컨테이너가 갑자기 중지되면서 Exit Code 1이 표시되는 경우가 있습니다.

특히 컨테이너를 처음 설치하거나 Docker Compose로 서비스를 구성한 직후 다음과 같은 상황이 발생할 수 있습니다.

컨테이너를 실행하면 잠시 정상적으로 실행되는 것처럼 보이지만 곧바로 중지됩니다.

다시 시작해도 몇 초 후 종료됩니다.

Container Manager의 컨테이너 상태에는 Exited가 표시되고 종료 코드에는 1이 나타납니다.

이때 처음 접하는 사용자라면 “Exit Code 1이라는 오류가 발생했으니 Docker 자체에 문제가 있는 것 아닐까?”라고 생각하기 쉽습니다.

하지만 Exit Code 1은 특정한 하나의 원인을 의미하는 오류 코드가 아닙니다.

일반적으로 컨테이너 내부의 프로그램이 정상적으로 실행되지 않아 비정상 종료됐다는 정도의 의미로 해석해야 합니다.

따라서 Exit Code 1이 표시됐다는 이유만으로 Container Manager를 다시 설치하거나 컨테이너를 삭제할 필요는 없습니다.

오히려 컨테이너 로그를 먼저 확인하고 프로그램이 왜 종료됐는지 원인을 찾아야 합니다.

Exit Code 1은 무엇을 의미할까?

Docker에서 컨테이너는 내부에서 실행되는 메인 프로세스가 종료되면 컨테이너도 함께 종료됩니다.

쉽게 표현하면 다음과 같은 구조입니다.

Container Manager → 컨테이너 실행 → 내부 프로그램 실행 → 프로그램 종료 → 컨테이너 종료

여기서 프로그램이 정상적으로 종료되면 일반적으로 Exit Code 0이 반환됩니다.

반면 Exit Code 1이 반환됐다면 프로그램이 정상적인 상태로 종료되지 않았다는 의미로 볼 수 있습니다.

중요한 것은 Exit Code 1 자체가 구체적인 원인을 알려주지는 않는다는 점입니다.

설정 파일이 잘못됐을 수도 있고, 환경변수가 빠졌을 수도 있습니다.

권한 문제일 수도 있고 볼륨 경로가 잘못됐을 수도 있습니다.

필요한 파일이나 데이터베이스에 접근하지 못했을 수도 있습니다.

따라서 Exit Code 1은 원인이라기보다 문제가 발생했다는 결과에 가깝습니다.

가장 먼저 확인해야 할 것은 컨테이너 로그

Exit Code 1이 나타났다면 가장 먼저 확인해야 할 것은 컨테이너 로그입니다.

Container Manager에서 해당 컨테이너를 선택하고 로그를 확인하면 컨테이너가 종료되기 직전에 출력한 메시지를 확인할 수 있습니다.

예를 들어 다음과 같은 형태의 메시지가 나타날 수 있습니다.

configuration file not found

permission denied

connection refused

invalid configuration

command not found

이러한 메시지가 있다면 Exit Code 1의 원인을 훨씬 쉽게 파악할 수 있습니다.

반대로 로그를 확인하지 않고 컨테이너를 계속 재시작하면 같은 오류가 반복될 뿐입니다.

따라서 Exit Code 1 문제를 해결하는 첫 번째 단계는 로그 확인이라고 생각하는 것이 좋습니다.

환경변수가 빠진 경우

컨테이너가 Exit Code 1로 종료되는 대표적인 원인 중 하나가 환경변수(Environment Variables) 설정 오류입니다.

Docker 컨테이너 중에는 실행할 때 특정 환경변수를 반드시 요구하는 프로그램이 있습니다.

예를 들어 다음과 같은 값이 필요할 수 있습니다.

TZ

PUID

PGID

USER_ID

PASSWORD

DATABASE_URL

API_KEY

이 중 필요한 값이 빠져 있거나 잘못 입력되어 있으면 컨테이너 내부의 프로그램이 실행 과정에서 오류를 발생시키고 종료될 수 있습니다.

특히 Docker Hub나 공식 문서에서 제공하는 예제의 환경변수를 일부만 복사해서 사용하는 경우 이런 문제가 발생하기 쉽습니다.

따라서 컨테이너가 바로 종료된다면 현재 입력한 환경변수와 해당 이미지가 요구하는 환경변수를 비교해 보는 것이 좋습니다.

환경변수 이름을 잘못 입력한 경우

환경변수가 존재한다고 해서 반드시 정상적으로 작동하는 것은 아닙니다.

변수 이름을 잘못 입력하는 경우도 있습니다.

예를 들어 이미지가 DATABASE_HOST를 요구하는데 사용자가 DB_HOST라고 입력했다면 Docker 입장에서는 환경변수가 존재하지만 프로그램 입장에서는 필요한 설정이 없는 것과 같습니다.

이런 경우 컨테이너는 실행되지만 내부 프로그램이 설정을 읽지 못하고 종료할 수 있습니다.

따라서 환경변수 문제를 확인할 때는 값뿐만 아니라 변수 이름과 대소문자까지 확인해야 합니다.

볼륨 매핑 경로가 잘못된 경우

시놀로지 Container Manager에서 컨테이너를 구성할 때 매우 자주 발생하는 문제가 볼륨 매핑(Volume Mapping)입니다.

NAS의 실제 폴더와 컨테이너 내부에서 사용할 경로를 연결하는 과정입니다.

예를 들어 NAS에 /docker/app/data라는 폴더가 있고 컨테이너에서는 /config라는 경로를 사용하도록 구성할 수 있습니다.

이때 컨테이너 내부 프로그램이 /config에 설정 파일을 저장하거나 읽으려고 하는데 매핑이 잘못되어 있다면 실행에 실패할 수 있습니다.

특히 다음과 같은 문제가 발생할 수 있습니다.

NAS 폴더가 존재하지 않습니다.

컨테이너 경로를 잘못 입력했습니다.

파일과 폴더를 반대로 매핑했습니다.

필요한 설정 파일이 다른 경로에 있습니다.

이런 경우 컨테이너는 정상적으로 생성됐지만 실제 프로그램을 시작하는 과정에서 오류가 발생할 수 있습니다.

권한 문제로 종료될 수 있다

시놀로지 NAS에서는 파일 및 폴더 권한도 중요한 원인입니다.

컨테이너 내부에서 특정 파일이나 폴더에 접근해야 하는데 해당 디렉터리에 대한 권한이 없다면 다음과 같은 메시지가 로그에 표시될 수 있습니다.

Permission denied

이 경우 Exit Code 1은 원인이 아니라 권한 문제로 인해 프로그램이 종료된 결과입니다.

특히 /config, /data, /media 등 컨테이너에서 사용하는 폴더를 NAS에 직접 매핑한 경우 권한을 확인해야 합니다.

컨테이너가 어떤 사용자 또는 그룹 권한으로 실행되는지도 함께 확인하는 것이 좋습니다.

무조건 모든 폴더에 전체 권한을 부여하는 방식은 보안상 권장되지 않습니다.

필요한 폴더에 필요한 권한만 부여하는 것이 좋습니다.

컨테이너 이미지 자체의 문제

모든 설정이 정상인데도 컨테이너가 실행되지 않는다면 Docker 이미지 자체의 문제도 생각해 볼 수 있습니다.

예를 들어 이미지가 손상됐거나 특정 버전에서 문제가 발생했을 수 있습니다.

또한 최신 버전의 이미지가 기존 설정과 호환되지 않는 경우도 있습니다.

특히 이전에는 정상적으로 작동하던 컨테이너가 이미지 업데이트 이후 Exit Code 1로 종료되기 시작했다면 최근 변경된 이미지 버전을 확인해 보는 것이 좋습니다.

이런 경우 무작정 컨테이너를 삭제하기보다 이전에 사용하던 이미지 버전과 현재 버전의 변경 사항을 확인하는 것이 좋습니다.

이미지와 CPU 아키텍처가 맞지 않는 경우

NAS 모델에 따라 사용하는 CPU 아키텍처가 다릅니다.

일부 컨테이너 이미지는 여러 아키텍처를 지원하지만 모든 이미지가 모든 NAS에서 동일하게 실행되는 것은 아닙니다.

예를 들어 특정 이미지가 ARM 환경을 제대로 지원하지 않는데 ARM 기반 NAS에서 해당 이미지를 실행하려 하면 정상적으로 실행되지 않을 수 있습니다.

따라서 처음 설치하는 컨테이너가 계속 Exit Code 1로 종료된다면 해당 이미지가 자신의 시놀로지 NAS CPU 아키텍처를 지원하는지도 확인해야 합니다.

특히 오래된 이미지나 개인이 제작한 이미지를 사용하는 경우 더욱 주의할 필요가 있습니다.

Docker Compose YAML 설정 오류

Docker Compose를 이용해 컨테이너를 생성했다면 YAML 설정 오류도 확인해야 합니다.

예를 들어 다음과 같은 부분에서 문제가 발생할 수 있습니다.

들여쓰기 오류

잘못된 환경변수

잘못된 볼륨 경로

존재하지 않는 네트워크

잘못된 이미지 이름

잘못된 포트 설정

Compose 파일은 문법적으로는 정상적으로 읽히더라도 컨테이너가 실행된 이후 내부 프로그램이 필요한 값을 받지 못하면 Exit Code 1이 발생할 수 있습니다.

따라서 Compose를 사용했다면 Container Manager 화면뿐만 아니라 실제 compose.yaml 또는 docker-compose.yml 파일도 확인하는 것이 좋습니다.

명령어가 잘못된 경우

컨테이너 이미지에는 기본적으로 실행할 명령어가 지정되어 있을 수 있습니다.

Docker Compose에서 command나 entrypoint를 직접 지정했다면 이 부분의 오류도 확인해야 합니다.

예를 들어 실행해야 할 프로그램의 이름이나 경로가 잘못되어 있으면 컨테이너가 시작되자마자 종료될 수 있습니다.

로그에 command not found 또는 executable file not found와 같은 메시지가 표시된다면 실행 명령어 또는 이미지 내부의 실행 파일을 확인해야 합니다.

이 경우 Docker 자체보다는 컨테이너가 실행하려는 프로그램의 설정 문제일 가능성이 높습니다.

포트 충돌 때문에 종료되는 경우

컨테이너가 사용하는 포트가 이미 다른 서비스에서 사용 중인 경우에도 문제가 발생할 수 있습니다.

예를 들어 새로운 컨테이너가 호스트의 8080 포트를 사용하도록 설정했는데 다른 컨테이너가 이미 해당 포트를 사용하고 있다면 정상적으로 서비스를 시작할 수 없습니다.

다만 포트 충돌은 항상 컨테이너 자체가 Exit Code 1로 종료되는 형태로 나타나는 것은 아닙니다.

Container Manager에서 포트 바인딩 오류가 별도로 표시될 수도 있습니다.

따라서 컨테이너를 시작하자마자 문제가 발생한다면 호스트 포트가 다른 서비스와 중복되지 않는지 확인하는 것이 좋습니다.

데이터베이스 연결 실패

웹 서비스나 서버 프로그램을 Docker로 설치한 경우 데이터베이스와 연결해야 하는 컨테이너도 많습니다.

예를 들어 애플리케이션 컨테이너가 별도의 MariaDB나 PostgreSQL 컨테이너와 통신하도록 구성되어 있다면 데이터베이스 연결 정보가 정확해야 합니다.

다음과 같은 상황에서는 프로그램이 시작되지 않을 수 있습니다.

데이터베이스 컨테이너가 실행되지 않았습니다.

데이터베이스 호스트 이름이 잘못됐습니다.

포트가 잘못됐습니다.

사용자 이름이나 비밀번호가 잘못됐습니다.

Docker 네트워크가 다릅니다.

이 경우 애플리케이션 컨테이너의 로그에 Connection refused 또는 Unable to connect to database와 같은 메시지가 나타날 수 있습니다.

컨테이너 간 네트워크 설정 확인

여러 컨테이너를 함께 사용하는 환경에서는 Docker 네트워크도 확인해야 합니다.

예를 들어 웹 애플리케이션 → 데이터베이스 형태로 통신해야 하는데 두 컨테이너가 서로 다른 네트워크에 연결되어 있다면 통신이 되지 않을 수 있습니다.

Container Manager에서 각각의 컨테이너가 어떤 네트워크에 연결되어 있는지 확인해야 합니다.

특히 Compose 파일을 수정하면서 네트워크 이름이나 설정을 변경한 경우 문제가 발생할 수 있습니다.

TZ 설정 때문에 발생하는 문제

일부 컨테이너는 시간대 설정을 필요로 합니다.

예를 들어 한국에서 사용하는 NAS라면 컨테이너의 시간대를 Asia/Seoul로 설정할 수 있습니다.

환경변수로 TZ=Asia/Seoul을 사용하는 이미지도 있습니다.

시간대 설정 자체가 Exit Code 1의 직접적인 원인이 되는 경우는 모든 이미지에서 흔한 것은 아니지만, 특정 애플리케이션은 시간 설정이나 환경변수에 의존할 수 있습니다.

따라서 로그에 시간이나 타임존 관련 오류가 나타난다면 이 부분도 확인할 수 있습니다.

설정 파일이 손상됐을 가능성

컨테이너가 기존에는 정상적으로 실행됐는데 설정을 변경한 이후 갑자기 Exit Code 1이 발생했다면 설정 파일 손상 또는 잘못된 설정을 의심할 수 있습니다.

특히 컨테이너가 /config와 같은 볼륨을 사용하고 있다면 프로그램이 해당 폴더에 저장한 설정 파일을 읽으면서 오류가 발생할 수 있습니다.

이 경우 컨테이너 자체는 정상인데 애플리케이션 설정만 잘못됐을 가능성이 있습니다.

따라서 설정 파일을 최근에 직접 수정했다면 마지막으로 변경한 부분을 되돌려 보는 것도 하나의 방법입니다.

단, 설정 파일이나 데이터를 삭제하기 전에 반드시 백업 여부를 확인해야 합니다.

컨테이너를 계속 재시작하면 해결될까?

Exit Code 1이 발생했을 때 컨테이너를 계속 재시작하는 경우가 있습니다.

하지만 설정이나 권한, 환경변수에 문제가 있다면 재시작해도 같은 오류가 반복됩니다.

오히려 restart: always와 같은 재시작 정책이 설정되어 있다면 컨테이너가 계속 시작과 종료를 반복하면서 로그가 빠르게 쌓일 수 있습니다.

따라서 컨테이너가 반복적으로 종료된다면 먼저 자동 재시작 여부를 확인하고 로그를 통해 원인을 찾은 다음 설정을 수정하는 것이 좋습니다.

Exit Code 1 문제를 확인하는 순서

Container Manager 컨테이너가 Exit Code 1로 종료됐다면 다음 순서로 확인하는 것이 효율적입니다.

먼저 컨테이너 로그를 확인합니다.

로그에서 Error, Failed, Permission denied, Connection refused와 같은 메시지를 찾습니다.

그다음 환경변수 설정을 확인합니다.

볼륨 매핑의 NAS 경로와 컨테이너 경로가 올바른지도 확인합니다.

해당 폴더에 컨테이너가 접근할 수 있는 권한이 있는지 확인합니다.

컨테이너에서 사용하는 포트가 다른 서비스와 충돌하지 않는지 확인합니다.

데이터베이스나 다른 컨테이너에 의존하는 서비스라면 해당 컨테이너가 정상적으로 실행되고 있는지도 확인합니다.

Docker 네트워크 설정을 확인합니다.

Compose를 사용했다면 YAML 파일의 환경변수, 볼륨, 네트워크, 명령어 설정을 확인합니다.

마지막으로 이미지 버전과 CPU 아키텍처 호환성까지 확인합니다.

이 순서대로 확인하면 단순히 컨테이너를 삭제하고 다시 설치하는 것보다 원인을 훨씬 정확하게 파악할 수 있습니다.

컨테이너를 삭제하기 전에 주의할 점

문제를 해결하려고 컨테이너를 바로 삭제하는 것은 주의해야 합니다.

컨테이너 자체는 삭제해도 볼륨이나 바인드 마운트로 NAS에 저장된 데이터가 남아 있을 수 있지만, 구성 방식에 따라 중요한 데이터가 컨테이너 내부에만 존재하는 경우도 있습니다.

특히 데이터베이스나 애플리케이션 설정이 컨테이너 내부에 저장되어 있다면 삭제 과정에서 데이터가 사라질 가능성을 확인해야 합니다.

따라서 Exit Code 1이 발생했다고 해서 바로 컨테이너 삭제 → 이미지 삭제 → 재설치 순서로 진행하기보다 먼저 로그와 볼륨 구성을 확인하는 것이 안전합니다.

로그가 가장 중요한 이유

Exit Code 1은 매우 일반적인 종료 코드입니다.

따라서 이 숫자만 가지고는 정확한 원인을 알기 어렵습니다.

예를 들어 똑같이 Exit Code 1이 표시되더라도 한 컨테이너에서는 환경변수 오류일 수 있고, 다른 컨테이너에서는 권한 문제일 수 있습니다.

또 다른 컨테이너에서는 데이터베이스 연결 실패가 원인일 수도 있습니다.

즉, Exit Code 1 = 문제가 발생했다 정도로 이해하고, 무슨 문제가 발생했는지 = 컨테이너 로그에서 확인 하는 것이 가장 정확합니다.

마무리

시놀로지 Container Manager에서 컨테이너가 Exit Code 1로 종료되는 문제는 Docker 자체의 고장으로 단정하기 어렵습니다.

Exit Code 1은 컨테이너 내부의 메인 프로세스가 정상적으로 실행되지 못하고 종료됐다는 결과를 보여주는 것이기 때문입니다.

대표적인 원인은 다음과 같습니다.

환경변수 오류

볼륨 매핑 오류

폴더 권한 문제

설정 파일 오류

포트 충돌

컨테이너 간 네트워크 문제

데이터베이스 연결 실패

실행 명령어 오류

이미지 버전 문제

CPU 아키텍처 호환성 문제

따라서 문제를 해결할 때는 컨테이너를 무작정 삭제하거나 재설치하기보다 로그를 먼저 확인하는 것이 가장 중요합니다.

특히 로그에 표시되는 Permission denied, Connection refused, command not found와 같은 메시지는 실제 원인을 찾는 데 중요한 단서가 됩니다.

문제 확인 순서는 컨테이너 로그 → 환경변수 → 볼륨 매핑 → 권한 → 포트 → 네트워크 → 의존 서비스 → Compose 설정 → 이미지 버전 순으로 진행하는 것이 좋습니다.

로그에서 파일이나 디렉터리에 접근하지 못했다는 메시지가 나온다면 볼륨 매핑과 권한 문제를 별도로 확인해야 합니다.

결국 Exit Code 1은 원인을 알려주는 오류라기보다 컨테이너가 정상적으로 실행되지 않았다는 결과에 가깝습니다.

따라서 숫자 자체에 집중하기보다 컨테이너가 종료되기 직전에 어떤 오류 메시지를 남겼는지를 확인하는 것이 시놀로지 Container Manager 문제를 해결하는 가장 빠른 방법입니다.