시놀로지 Container Manager 볼륨 매핑 후 권한 거부가 발생하는 이유

시놀로지 NAS에서 Container Manager로 Docker 컨테이너를 설치하다 보면 볼륨 매핑을 완료한 후 컨테이너가 정상적으로 실행되지 않거나 Permission denied 오류가 발생하는 경우가 있습니다.

특히 컨테이너 자체는 정상적으로 생성됐는데 실행 직후 종료되거나, 웹 서비스는 열리지만 특정 폴더에 파일을 생성하지 못하는 문제가 나타날 수 있습니다.

대표적으로 다음과 같은 상황입니다.

• 컨테이너 로그에 Permission denied가 표시된다.
• /config, /data, /media 등의 폴더에 접근하지 못한다.
• 컨테이너가 실행 직후 종료된다.
• 파일을 읽을 수 있지만 수정하거나 삭제할 수 없다.
• 다운로드 폴더에 파일을 저장하지 못한다.
• 설정 파일을 생성하지 못해 컨테이너가 계속 재시작된다.

이런 경우 Docker 이미지에 문제가 있다고 생각하기 쉽지만, 실제로는 NAS의 공유 폴더 권한과 컨테이너 내부에서 실행되는 사용자의 권한이 서로 맞지 않아서 발생하는 경우가 많습니다.

볼륨 매핑은 단순히 NAS 폴더와 컨테이너 폴더를 연결하는 기능처럼 보이지만, 연결된 이후에는 컨테이너 프로세스가 해당 NAS 폴더에 어떤 권한으로 접근할 수 있는지가 중요합니다.

볼륨 매핑이란 무엇일까?

Docker 컨테이너는 기본적으로 독립적인 환경에서 실행됩니다.

컨테이너 내부에 /config라는 폴더가 있다고 해서 NAS의 실제 폴더와 자동으로 연결되는 것은 아닙니다.

예를 들어 NAS에 다음과 같은 폴더가 있다고 가정해 보겠습니다.

/docker/jellyfin/config

이 폴더를 컨테이너 내부의 /config와 연결하면 다음과 같은 구조가 됩니다.

NAS의 /docker/jellyfin/config

↓

컨테이너의 /config

이것이 볼륨 매핑입니다.

컨테이너가 /config에 파일을 저장하면 실제 데이터는 NAS의 /docker/jellyfin/config에 저장됩니다.

문제는 여기서부터 발생할 수 있습니다.

컨테이너가 /config에 접근하려고 하더라도 NAS의 실제 폴더에 대한 권한이 없다면 파일을 읽거나 생성할 수 없습니다.

볼륨 매핑을 했는데 왜 권한이 없을까?

가장 중요한 이유는 컨테이너 내부 프로세스의 사용자와 NAS 폴더의 권한이 맞지 않기 때문입니다.

예를 들어 NAS의 폴더가 특정 사용자만 읽고 쓸 수 있도록 설정되어 있다고 가정해 보겠습니다.

그런데 컨테이너 내부의 애플리케이션이 다른 사용자 또는 다른 UID로 실행된다면 NAS 폴더에 접근할 수 없습니다.

결과적으로 컨테이너 로그에 다음과 같은 메시지가 나타날 수 있습니다.

Permission denied 또는 Access denied 또는 Read-only file system

이때 Docker 자체가 폴더를 잘못 연결한 것이 아니라 연결된 폴더에 컨테이너가 접근할 권한이 없는 것일 수 있습니다.

NAS 권한과 Docker 권한은 별개로 생각해야 한다

시놀로지 NAS에서 파일을 관리할 때는 DSM의 사용자 및 공유 폴더 권한을 사용합니다.

반면 Docker 컨테이너 안에서는 Linux의 사용자 및 그룹 ID를 기준으로 파일 접근 권한이 적용될 수 있습니다.

따라서 NAS에서 “나는 이 폴더에 관리자 권한이 있는데?”라고 생각하더라도 컨테이너 내부 프로세스는 해당 권한을 그대로 가지고 있지 않을 수 있습니다.

쉽게 표현하면 다음과 같습니다.

NAS 사용자 권한

컨테이너 프로세스의 Linux 사용자/그룹 권한

이 두 부분이 맞아야 정상적으로 파일을 읽고 쓸 수 있습니다.

PUID와 PGID가 중요한 이유

일부 Docker 이미지에서는 컨테이너가 실행될 사용자를 지정하기 위해 PUID와 PGID 환경변수를 사용합니다.

예를 들어 다음과 같은 설정을 볼 수 있습니다.

PUID=1026

PGID=100

이 값은 컨테이너 내부 애플리케이션이 어떤 사용자 및 그룹 권한으로 파일에 접근할지 결정하는 데 사용됩니다.

하지만 모든 Docker 이미지가 PUID와 PGID를 사용하는 것은 아닙니다.

이미지에 따라 환경변수 이름이나 권한 관리 방식이 다를 수 있습니다.

따라서 인터넷에서 다른 사람이 사용하는 PUID, PGID 값을 그대로 복사하는 것은 권장되지 않습니다.

먼저 해당 이미지의 공식 문서에서 어떤 방식으로 사용자 권한을 설정하는지 확인해야 합니다.

NAS 사용자의 UID와 컨테이너 사용자가 다를 수 있다

Linux에서는 사용자의 이름뿐만 아니라 내부적으로 UID(User ID)를 사용합니다.

예를 들어 NAS의 특정 사용자가 UID 1026을 사용한다고 하더라도 컨테이너 내부의 애플리케이션이 UID 1000으로 실행된다면 두 사용자는 같은 권한을 가진 것으로 인식되지 않을 수 있습니다.

따라서 컨테이너에서 NAS 폴더에 파일을 생성하려고 할 때 권한이 거부될 수 있습니다.

이 문제는 특히 Linux 기반 Docker 이미지에서 자주 확인해야 하는 부분입니다.

공유 폴더 권한을 확인해야 한다

볼륨 매핑 후 Permission denied가 발생한다면 DSM에서 해당 공유 폴더의 권한을 확인하는 것이 좋습니다.

예를 들어 제어판 → 공유 폴더에서 해당 폴더의 접근 권한을 확인할 수 있습니다.

컨테이너가 사용하는 폴더에 필요한 사용자 또는 그룹의 읽기 및 쓰기 권한이 있는지 확인해야 합니다.

중요한 것은 컨테이너가 실제로 어떤 사용자 권한으로 실행되는지 확인한 다음 해당 사용자에게 필요한 권한을 부여하는 것입니다.

무조건 Everyone에게 읽기/쓰기 권한을 주는 방식으로 해결하는 것은 권장하지 않습니다.

읽기는 되는데 쓰기가 안 되는 이유

권한 문제에서 자주 발생하는 현상입니다.

컨테이너가 폴더에 있는 파일을 읽는 것은 가능한데 새로운 파일을 생성하지 못할 수 있습니다.

이 경우 해당 폴더에 읽기 권한은 있지만 쓰기 권한이 없는 상황일 수 있습니다.

예를 들어 미디어 서버 컨테이너가 영화 파일을 읽는 것은 정상인데 다운로드 프로그램이 같은 폴더에 새로운 파일을 저장하지 못한다면 쓰기 권한을 별도로 확인해야 합니다.

따라서 “폴더에 접근할 수 있다”는 것과 “폴더에 파일을 쓸 수 있다”는 것은 다르게 확인해야 합니다.

상위 폴더 권한도 확인해야 한다

볼륨 매핑 대상 폴더에 권한을 부여했는데도 문제가 해결되지 않는 경우 상위 디렉터리의 권한도 확인해야 합니다.

예를 들어 다음과 같은 경로가 있다고 가정하겠습니다.

/volume1/docker/app/data

마지막 data 폴더의 권한만 확인해서는 충분하지 않을 수 있습니다.

상위 경로를 거쳐 해당 폴더까지 접근할 수 있어야 하기 때문입니다.

따라서 특정 폴더에 권한을 부여했는데도 접근이 되지 않는다면 상위 폴더의 접근 권한까지 함께 확인해야 합니다.

읽기 전용으로 매핑했는지 확인

Container Manager에서 볼륨을 매핑할 때 읽기/쓰기 방식도 확인해야 합니다.

컨테이너가 파일을 저장해야 하는 폴더를 읽기 전용으로 연결했다면 애플리케이션이 파일을 생성할 수 없습니다.

예를 들어 미디어 서버가 영상 파일을 단순히 읽기만 한다면 읽기 전용 매핑도 사용할 수 있습니다.

반면 다운로드 프로그램이나 데이터베이스처럼 파일을 계속 생성하고 수정하는 서비스라면 읽기/쓰기 권한이 필요할 수 있습니다.

따라서 볼륨 매핑 후 쓰기 오류가 발생한다면 해당 매핑이 Read Only로 설정되어 있지 않은지 확인해야 합니다.

데이터베이스 컨테이너는 특히 주의해야 한다

MariaDB, PostgreSQL 같은 데이터베이스를 컨테이너로 운영한다면 권한 문제가 더욱 중요합니다.

데이터베이스는 실행 과정에서 많은 파일을 생성하고 수정합니다.

데이터 디렉터리에 대한 쓰기 권한이 없으면 컨테이너가 실행되지 않거나 데이터베이스 초기화 단계에서 오류가 발생할 수 있습니다.

예를 들어 로그에 Permission denied와 함께 데이터 디렉터리나 특정 파일의 경로가 표시된다면 해당 경로의 권한을 확인해야 합니다.

데이터베이스 컨테이너는 중요한 데이터를 저장하므로 권한 문제를 해결하기 위해 폴더를 무작정 삭제하거나 권한을 크게 변경해서는 안 됩니다.

Docker Compose에서도 권한 문제가 발생한다

Docker Compose를 사용하는 경우에도 같은 문제가 발생할 수 있습니다.

예를 들어 다음과 같이 볼륨을 지정할 수 있습니다.

/volume1/docker/app:/config

이 설정은 NAS의 특정 폴더를 컨테이너의 /config에 연결합니다.

문제는 Compose 파일에 경로만 제대로 입력했다고 해서 컨테이너가 해당 폴더에 접근할 수 있는 것은 아니라는 점입니다.

경로 설정은 정상인데 권한 설정이 잘못된 경우에도 Permission denied가 발생할 수 있습니다.

따라서 Compose를 사용할 때는 볼륨 경로 + 컨테이너 사용자 + NAS 폴더 권한을 함께 확인해야 합니다.

컨테이너를 root로 실행하면 해결될까?

권한 문제가 발생하면 컨테이너를 root 사용자로 실행하면 해결된다는 이야기를 접할 수 있습니다.

실제로 root 권한으로 실행하면 특정 파일 권한 문제를 우회할 수 있는 경우가 있습니다.

하지만 이것을 일반적인 해결 방법으로 사용하는 것은 주의해야 합니다.

컨테이너에 필요 이상의 권한을 부여하면 보안 위험이 커질 수 있기 때문입니다.

특히 외부에 서비스를 공개하는 컨테이너라면 더욱 신중해야 합니다.

따라서 가능한 경우 애플리케이션에 필요한 최소한의 권한만 부여하는 방식으로 구성하는 것이 좋습니다.

ACL 권한 때문에 문제가 발생할 수도 있다

시놀로지 DSM에서는 일반적인 공유 폴더 권한 외에도 Windows ACL 기반의 세부 권한이 적용될 수 있습니다.

이 때문에 단순히 사용자에게 읽기/쓰기 권한을 부여한 것처럼 보여도 실제 접근 과정에서 권한이 제한될 수 있습니다.

특히 특정 사용자에게만 접근을 허용하거나 복잡한 권한 구조를 사용하고 있다면 ACL 설정도 함께 확인해야 합니다.

따라서 권한 문제가 반복된다면 단순히 Container Manager 설정만 확인하기보다 DSM의 공유 폴더 권한과 ACL 설정까지 확인하는 것이 좋습니다.

파일 소유권 때문에 발생하는 경우

컨테이너가 생성한 파일의 소유자가 예상과 다른 경우에도 문제가 발생할 수 있습니다.

예를 들어 컨테이너가 특정 UID로 파일을 생성하면 NAS에서 해당 파일의 소유권이 다른 사용자처럼 표시될 수 있습니다.

이후 다른 컨테이너나 NAS 사용자로 해당 파일을 수정하려고 하면 권한 오류가 발생할 수 있습니다.

특히 여러 Docker 컨테이너가 동일한 폴더를 공유하는 환경이라면 각 컨테이너가 사용하는 사용자 및 그룹 권한이 서로 맞는지 확인하는 것이 중요합니다.

여러 컨테이너가 같은 폴더를 사용하는 경우

하나의 폴더를 여러 컨테이너가 공유하는 경우에도 권한 문제가 발생할 수 있습니다.

예를 들어

다운로드 컨테이너 → /downloads

미디어 서버 → /media

자동 정리 컨테이너 → /media

처럼 여러 서비스가 동일한 데이터를 사용하는 구조가 있을 수 있습니다.

이때 각각의 컨테이너가 서로 다른 사용자 권한으로 실행된다면 한 컨테이너가 생성한 파일을 다른 컨테이너가 수정하지 못하는 상황이 발생할 수 있습니다.

따라서 여러 컨테이너가 동일한 폴더를 공유한다면 사용자와 그룹 권한을 처음부터 일관되게 설계하는 것이 좋습니다.

권한 문제를 확인하는 가장 좋은 방법은 로그

Container Manager에서 Permission denied가 발생했다면 컨테이너 로그를 먼저 확인하는 것이 좋습니다.

예를 들어 다음과 같은 로그가 있다고 가정해 보겠습니다.

Permission denied: /config/settings.json

이 메시지가 있다면 /config와 연결된 NAS 폴더의 권한을 확인하면 됩니다.

반대로

Permission denied: /media/download

라고 표시된다면 /media/download에 연결된 실제 NAS 폴더의 권한을 확인해야 합니다.

즉, 로그에 표시되는 정확한 경로를 확인하는 것이 중요합니다.

볼륨 매핑 후 권한 거부가 발생했을 때 확인 순서

권한 오류가 발생했다면 다음과 같은 순서로 확인하는 것이 좋습니다.

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

Permission denied가 발생한 정확한 경로를 확인합니다.

그다음 해당 컨테이너의 볼륨 매핑을 확인합니다.

컨테이너 경로와 NAS의 실제 경로가 올바르게 연결되어 있는지 확인합니다.

해당 NAS 공유 폴더에 필요한 사용자 및 그룹의 권한이 있는지 확인합니다.

컨테이너가 어떤 사용자 또는 UID/GID로 실행되는지 확인합니다.

읽기 전용 매핑으로 설정되어 있지 않은지도 확인합니다.

상위 폴더의 접근 권한도 확인합니다.

ACL을 사용하는 환경이라면 세부 권한도 확인합니다.

여러 컨테이너가 동일한 폴더를 사용하는 경우 사용자 및 그룹 권한을 비교합니다.

이후 컨테이너를 다시 시작해 정상적으로 파일을 생성하고 수정할 수 있는지 확인합니다.

권한을 무조건 777로 변경하면 안 되는 이유

인터넷에서 Docker 권한 문제를 검색하다 보면 chmod 777과 같은 방법을 해결책으로 소개하는 경우가 있습니다.

실제로 모든 사용자에게 읽기, 쓰기, 실행 권한을 주면 일부 권한 오류가 사라질 수 있습니다.

하지만 이것은 원인을 해결한 것이 아니라 권한 제한을 크게 풀어버린 것에 가깝습니다.

NAS에는 개인 파일이나 중요한 데이터가 저장될 수 있기 때문에 필요 이상의 권한을 부여하는 것은 바람직하지 않습니다.

따라서 가능하면 컨테이너가 실제로 사용하는 사용자와 그룹에 필요한 권한만 부여하는 방식으로 해결하는 것이 좋습니다.

마무리

시놀로지 Container Manager에서 볼륨 매핑 후 Permission denied 오류가 발생하는 가장 흔한 이유는 볼륨 연결 자체가 잘못됐다기보다 컨테이너 내부에서 실행되는 프로세스와 NAS의 실제 폴더 권한이 맞지 않기 때문입니다.

특히 다음과 같은 요소를 함께 확인해야 합니다.

NAS 공유 폴더 권한

컨테이너 실행 사용자

UID/GID

볼륨 매핑 경로

읽기/쓰기 설정

상위 폴더 권한

ACL 설정

여러 컨테이너의 공유 폴더 사용 여부

따라서 문제가 발생했을 때는 컨테이너를 삭제하고 다시 설치하기보다 먼저 로그에서 오류가 발생한 경로를 확인하는 것이 중요합니다.

그다음 해당 경로가 NAS의 어느 폴더와 연결되어 있는지 확인하고, 컨테이너가 사용하는 사용자 및 그룹이 해당 폴더에 필요한 권한을 가지고 있는지 확인하면 됩니다.

특히 권한 문제를 해결하기 위해 무조건 777 권한을 적용하거나 컨테이너를 root로 실행하는 방법은 신중하게 접근해야 합니다.

Docker 컨테이너를 안정적으로 운영하려면 “폴더를 연결하는 것”과 “연결된 폴더를 사용할 권한을 부여하는 것”은 서로 다른 작업이라는 점을 이해하는 것이 중요합니다.

결국 볼륨 매핑 후 권한 거부 문제가 발생했다면

컨테이너 로그 확인 → 오류 경로 확인 → 볼륨 매핑 확인 → NAS 폴더 권한 확인 → UID/GID 확인 → 읽기/쓰기 설정 확인 → ACL 확인

순서로 점검하는 것이 가장 효율적인 방법입니다.