NAS Docker Permission denied 해결: PUID·PGID와 폴더 권한 확인

NAS Docker Permission denied 오류는 폴더 권한 숫자만 바꾼다고 해결되는 문제가 아닙니다. 컨테이너가 실제로 어떤 UID·GID로 파일에 접근하는지, bind mount가 어느 호스트 경로를 가리키는지, NAS가 별도 ACL을 적용하는지를 순서대로 확인해야 합니다.

먼저 확인할 세 가지

확인 관계는 컨테이너 실행 사용자 → 호스트 마운트 경로 → 소유권·mode와 NAS ACL로 이어집니다. 각 지점은 컨테이너 안에서 id 확인, Mounts의 Source·RW 확인, NAS UI와 ls -ldn 확인 순서로 좁힙니다. PUID·PGID의 적용 범위는 아래 이미지 공식 문서로 확인합니다.

PUID와 PGID는 Docker 자체의 표준 환경변수가 아닙니다. LinuxServer.io의 PUID·PGID 문서처럼 일부 이미지가 컨테이너 내부 사용자를 호스트 사용자에 맞추기 위해 제공하는 방식입니다. 따라서 이미지 설명에 PUID·PGID 지원이 없다면 임의로 환경변수만 추가해서는 안 됩니다.

또한 bind mount는 NAS 호스트의 파일이나 디렉터리를 컨테이너에 직접 연결합니다. Docker bind mounts 공식 문서에서 설명하는 것처럼 실제 접근 권한은 호스트 파일시스템과 마운트 설정의 영향을 받습니다.

Synology, QNAP, UGREEN 등 NAS 제조사마다 ACL 메뉴 위치와 내부 계정 매핑 방식이 다를 수 있습니다. NAS UI에서 보이는 권한 이름과 경로는 해당 제조사의 현재 문서와 함께 확인하세요.

UID·GID와 마운트 상태 확인

먼저 컨테이너에서 기본 실행 사용자의 숫자 UID·GID를 확인합니다.

docker exec CONTAINER_NAME id

이미지가 시작 과정에서 다른 사용자로 권한을 낮추는 구조라면 위 결과만으로 실제 애플리케이션 프로세스 사용자를 단정하면 안 됩니다. 이미지 문서와 컨테이너 내부 프로세스 상태를 함께 확인합니다.

호스트에서는 실제 마운트 경로와 읽기·쓰기 여부를 확인합니다.

docker inspect CONTAINER_NAME
ls -ldn /path/to/nas-folder
stat /path/to/nas-folder

docker inspect의 Mounts에서 Source, Destination, RW를 확인합니다. ls -ldn은 사용자 이름 대신 숫자 UID·GID를 보여 주므로 컨테이너에서 확인한 값과 비교하기 쉽습니다. RW가 false라면 그 마운트는 읽기 전용입니다.

호스트 계정의 UID·GID가 필요하면 NAS 셸에서 다음처럼 확인할 수 있습니다.

id USERNAME

여기서 확인해야 할 핵심은 컨테이너가 쓰는 UID·GID와 호스트 폴더에 쓰기 권한을 가진 UID·GID가 맞는가입니다.

PUID·PGID를 써야 하는 경우

LinuxServer.io 계열처럼 이미지 문서에서 PUID와 PGID를 지원한다고 명시한 경우에는 호스트 계정의 숫자 UID·GID를 환경변수에 지정할 수 있습니다. 다음은 구조를 보여 주기 위한 예시이며 실제 이미지 이름, 경로, UID·GID는 사용 중인 이미지와 NAS에 맞춰 바꿔야 합니다.

services:
  app:
    image: vendor/image:tag
    environment:
      PUID: "1000"
      PGID: "1000"
    volumes:
      - /path/to/nas-folder:/config

LinuxServer.io 문서는 자사 이미지에서 PUID·PGID로 내부 사용자를 호스트 사용자에 매핑한다고 설명합니다. 동시에 현재 자사 이미지에는 Docker --user 대신 PUID·PGID 방식을 사용하도록 안내하고 있으므로, LinuxServer.io 이미지에 user:를 임의로 섞지 않는 편이 안전합니다.

PUID·PGID를 변경했다면 컨테이너를 재생성한 뒤 다시 id, 마운트 상태, 폴더 소유권을 확인합니다. 환경변수만 바뀌고 기존 파일의 소유권이나 NAS ACL이 그대로라면 Permission denied가 계속될 수 있습니다.

PUID·PGID가 없는 이미지의 해결 방법

이미지 문서에 PUID·PGID가 없다면 해당 환경변수는 해결책이 아닙니다. 먼저 이미지가 어떤 사용자로 실행되도록 설계됐는지 확인합니다. Docker Compose의 user는 컨테이너 프로세스의 실행 사용자를 덮어쓸 수 있지만, 모든 이미지가 임의 UID·GID 실행을 전제로 만들어진 것은 아닙니다.

따라서 user: "1000:1000" 같은 설정은 이미지가 그 실행 방식을 지원할 때만 사용합니다. 진입 스크립트가 root 권한을 필요로 하거나 내부 파일 소유권을 초기화하는 이미지에서는 오히려 시작 실패를 만들 수 있습니다.

필요하다면 호스트 폴더의 소유자·그룹을 실제 실행 사용자에 맞추되, 공유 폴더 전체에 재귀적으로 chown하거나 chmod 777을 적용하는 방식은 피합니다. 기존 서비스와 다른 계정의 접근 권한까지 바뀔 수 있기 때문입니다.

NAS ACL과 읽기 전용 설정 확인

Unix 권한이 맞는데도 NAS Docker Permission denied 오류가 남는다면 NAS의 공유 폴더 ACL을 확인합니다. NAS가 별도 ACL을 적용하는 환경에서는 ls -l의 mode bits만으로 최종 접근 권한을 판단하기 어렵습니다. Docker가 접근하는 사용자나 그룹에 해당 공유 폴더의 쓰기 권한이 있는지 NAS 웹 UI에서도 확인합니다.

또한 Compose의 bind mount에 :ro가 붙었는지 확인합니다.

services:
  app:
    image: vendor/image:tag
    volumes:
      - /path/to/nas-folder:/config:ro

이 설정은 해당 bind mount를 읽기 전용으로 만듭니다. 쓰기가 필요한 경로라면 이미지 문서를 확인한 뒤 :ro를 제거하거나 필요한 경로만 별도의 쓰기 가능한 마운트로 분리합니다. 서비스 수준의 read_only: true와 개별 bind mount의 읽기 전용 옵션은 구분해서 확인해야 합니다.

권한을 바꾼 뒤 재확인

수정 후에는 한 번에 여러 설정을 바꾸지 말고 다음 순서로 확인하는 편이 원인을 찾기 쉽습니다.

docker inspect로 실제 Source와 RW를 다시 확인합니다.
컨테이너의 실행 UID·GID를 다시 확인합니다.
호스트 폴더의 숫자 소유자·그룹과 쓰기 권한을 비교합니다.
NAS의 공유 폴더 ACL에서 같은 사용자·그룹의 쓰기 권한을 확인합니다.
애플리케이션에서 작은 파일 하나를 생성해 Permission denied가 사라졌는지 확인합니다.

NAS에서 Docker 데이터를 운영할 때의 백업·복구 구조는 NAS Docker 컨테이너 데이터 자동 백업 및 복구 가이드에서 이어서 확인할 수 있습니다.

핵심은 권한을 넓히는 것이 아니라 실제로 쓰기를 수행하는 UID·GID, bind mount의 호스트 경로, NAS ACL을 서로 일치시키는 것입니다. chmod 777은 원인을 가리는 임시 조치가 될 수 있으므로 일반적인 해결책으로 사용하지 않는 편이 좋습니다.

목차