Portainer 설치 후 docker.sock 연결이 거부되는 이유와 권한 문제

시놀로지 NAS에서 Docker를 관리하기 위해 Portainer를 설치한 뒤 다음과 같은 오류가 발생하는 경우가 있습니다.

Cannot connect to the Docker daemon

또는 permission denied while trying to connect to the Docker daemon socket

Portainer 화면에서는 컨테이너가 정상적으로 실행되고 있는 것처럼 보이는데 Docker 환경을 불러오지 못하거나, Endpoint가 연결되지 않는 현상이 나타나기도 합니다.

이런 문제는 Portainer 자체의 오류라기보다 Docker 소켓인 docker.sock에 Portainer 컨테이너가 접근하지 못해서 발생하는 경우가 많습니다.

특히 시놀로지 NAS의 Container Manager에서 Portainer를 Docker 컨테이너로 실행했다면 볼륨 매핑과 권한 설정을 먼저 확인할 필요가 있습니다.

docker.sock이란 무엇일까?

Portainer의 Docker 관리 기능을 이해하려면 먼저 docker.sock이 무엇인지 알아야 합니다.

Docker 데몬과 Docker 클라이언트가 통신할 때 사용하는 소켓 파일이 바로 docker.sock입니다.

일반적인 Linux Docker 환경에서는 다음과 같은 경로에 존재합니다.

/var/run/docker.sock

Portainer는 이 소켓을 통해 Docker 데몬에 명령을 전달합니다.

구조를 단순하게 표현하면 다음과 같습니다.

Portainer

↓

docker.sock

↓

Docker Engine

↓

컨테이너

따라서 Portainer가 docker.sock에 접근할 수 없다면 Docker 컨테이너 목록이나 이미지, 네트워크 등의 정보를 정상적으로 가져오지 못할 수 있습니다.

Portainer 컨테이너가 실행된다고 연결되는 것은 아니다

여기서 가장 많이 혼동하는 부분이 있습니다.

Container Manager에서 Portainer 컨테이너가 실행 중이라고 표시된다고 해서 Docker 관리 기능까지 정상적으로 작동하는 것은 아닙니다.

Portainer 자체는 웹 서버처럼 실행될 수 있습니다.

하지만 Portainer가 Docker Engine을 관리하려면 별도로 Docker 소켓에 접근할 수 있어야 합니다.

따라서 다음 두 가지는 구분해야 합니다.

Portainer 웹 화면 접속 가능

→ Portainer 컨테이너 자체는 실행 중

Docker Endpoint 연결 가능

→ Portainer가 Docker Engine과 통신 가능

Portainer 화면은 정상적으로 열리는데 Docker 환경이 연결되지 않는다면 docker.sock 접근 문제를 먼저 확인하는 것이 좋습니다.

가장 흔한 원인은 docker.sock 볼륨 매핑 오류

시놀로지 NAS에서 Portainer를 Docker로 실행할 때 가장 먼저 확인할 부분입니다.

Portainer 컨테이너가 호스트의 Docker 소켓을 사용할 수 있도록 연결해야 합니다.

일반적인 Docker 구성에서는 다음과 같은 형태가 사용됩니다.

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

앞쪽은 호스트의 경로이고 뒤쪽은 컨테이너 내부에서 접근할 경로입니다.

즉,

NAS의 /var/run/docker.sock

↓

Portainer 컨테이너의 /var/run/docker.sock

으로 연결하는 구조입니다.

이 매핑이 빠져 있거나 경로가 잘못되어 있으면 Portainer가 Docker Engine에 접근할 수 없습니다.

docker.sock 경로를 잘못 입력하면 어떻게 될까?

예를 들어 다음과 같이 잘못된 경로를 지정했다고 가정해 보겠습니다.

volumes:
  - /volume1/docker/docker.sock:/var/run/docker.sock

실제 Docker 소켓이 해당 위치에 존재하지 않는다면 Portainer가 정상적으로 Docker Engine에 연결할 수 없습니다.

시놀로지 NAS에서는 일반적인 Linux 환경과 다른 부분이 있을 수 있기 때문에 인터넷에서 찾은 Docker 명령어를 그대로 복사하기보다 현재 DSM과 Container Manager 환경에서 실제 Docker 소켓 경로가 어떻게 구성되어 있는지 확인하는 것이 중요합니다.

docker.sock은 일반 파일과 다르다

docker.sock은 일반적인 설정 파일이나 문서 파일과 다릅니다.

Docker 데몬과 통신하기 위한 Unix Domain Socket입니다.

따라서 단순히 파일이 존재하는지만 확인해서는 충분하지 않습니다.

Portainer 컨테이너에서 해당 소켓을 실제로 사용할 수 있어야 합니다.

이 때문에 다음 세 가지를 함께 확인해야 합니다.

소켓 경로

볼륨 매핑

접근 권한

이 중 하나라도 잘못되면 Portainer와 Docker Engine 사이의 통신이 실패할 수 있습니다.

권한 거부 오류가 발생하는 이유

Portainer 로그에 다음과 비슷한 메시지가 나타날 수 있습니다.

permission denied

이 경우 Portainer 컨테이너가 docker.sock을 발견했지만 해당 소켓에 접근할 권한이 없는 상황일 수 있습니다.

Docker 소켓은 Docker 데몬을 제어할 수 있는 중요한 인터페이스이기 때문에 일반적인 파일처럼 모든 사용자가 자유롭게 접근할 수 있도록 설정되어 있지 않습니다.

Portainer가 Docker Engine을 관리하려면 컨테이너 내부의 프로세스가 해당 소켓에 접근할 수 있어야 합니다.

docker.sock 권한을 무작정 변경하면 안 되는 이유

인터넷에서는 Portainer의 권한 오류를 해결하기 위해 docker.sock의 권한을 변경하라는 방법을 쉽게 찾아볼 수 있습니다.

하지만 시놀로지 NAS에서는 무조건 권한을 777로 변경하는 방식은 권장하지 않습니다.

예를 들어 다음과 같은 방식입니다.

chmod 777 /var/run/docker.sock

이렇게 하면 접근 문제를 해결하는 것처럼 보일 수 있지만 Docker 소켓은 매우 강력한 권한을 가진 인터페이스입니다.

Docker 소켓에 접근할 수 있다는 것은 사실상 Docker Engine을 제어할 수 있는 권한과 연결되기 때문에 불필요하게 접근 권한을 넓히는 것은 보안상 주의해야 합니다.

따라서 권한 문제는 가능한 한 현재 환경에 맞는 방식으로 해결하는 것이 좋습니다.

Portainer에 docker.sock을 연결할 때 주의할 점

Portainer를 설치할 때 다음과 같은 구성이 많이 사용됩니다.

services:
  portainer:
    image: portainer/portainer-ce
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /volume1/docker/portainer:/data

여기서 중요한 부분은 두 가지입니다.

첫 번째는 Docker 소켓입니다.

- /var/run/docker.sock:/var/run/docker.sock

두 번째는 Portainer 데이터를 저장할 볼륨입니다.

- /volume1/docker/portainer:/data

다만 실제 경로와 이미지 태그는 사용하는 환경에 맞게 확인해야 합니다.

/data와 docker.sock은 서로 다른 역할이다

Portainer를 처음 설정할 때 또 하나 자주 발생하는 혼동이 있습니다.

/data와 docker.sock은 역할이 완전히 다릅니다.

docker.sock

→ Docker Engine과 통신

/data

→ Portainer 설정 및 데이터 저장

따라서 /data 볼륨이 정상적으로 연결되어 있다고 해서 Docker Engine 연결까지 정상이라는 의미는 아닙니다.

반대로 docker.sock이 정상적으로 연결되어 있어도 /data에 문제가 있으면 Portainer 설정이나 데이터 저장 과정에서 문제가 발생할 수 있습니다.

Container Manager에서 볼륨 설정을 확인한다

시놀로지 Container Manager에서 Portainer 컨테이너의 설정을 확인할 때는 볼륨 또는 마운트 항목을 살펴봅니다.

Docker 소켓이 다음과 같은 구조로 연결되어 있는지 확인합니다.

호스트 경로

/var/run/docker.sock

↓

컨테이너 경로

/var/run/docker.sock

경로가 다르거나 오타가 있다면 수정이 필요할 수 있습니다.

특히 읽기 전용으로 설정되어 있는지 여부도 환경에 따라 확인할 필요가 있습니다.

컨테이너를 재생성해야 하는 경우도 있다

Portainer 컨테이너를 처음 만들 때 docker.sock 매핑을 빠뜨렸다면 단순히 Portainer 웹 화면에서 설정을 변경하는 것으로 해결되지 않을 수 있습니다.

왜냐하면 Docker의 볼륨 및 장치 매핑은 컨테이너 생성 과정에서 결정되는 설정이기 때문입니다.

따라서 기존 컨테이너를 수정하기 어렵다면 필요한 설정을 반영해 컨테이너를 다시 생성하는 방법을 고려할 수 있습니다.

다만 Portainer의 /data 볼륨을 별도로 유지하고 있다면 컨테이너를 다시 생성하더라도 기존 Portainer 설정을 유지할 수 있도록 구성해야 합니다.

Portainer Endpoint 설정도 확인해야 한다

docker.sock 매핑이 정상인데도 연결되지 않는다면 Portainer의 Endpoint 설정을 확인해야 합니다.

Portainer에서는 Docker 환경을 Endpoint 형태로 관리합니다.

일반적인 로컬 Docker 환경에서는 Portainer가 연결된 Docker Engine을 대상으로 Endpoint가 구성됩니다.

이 과정에서 잘못된 Endpoint를 선택했거나 원격 Docker 환경을 잘못 설정하면 연결 문제가 발생할 수 있습니다.

따라서 docker.sock 문제가 해결된 후에도 Portainer 화면에서 Endpoint 상태를 확인해야 합니다.

Portainer Agent와 docker.sock은 다르다

Portainer를 사용하다 보면 Portainer Agent라는 개념도 접하게 됩니다.

Portainer Agent를 사용하는 구성과 로컬 Docker 소켓을 직접 연결하는 구성은 서로 다릅니다.

예를 들어 로컬 NAS에서 Portainer가 Docker Engine을 관리하는 경우에는 docker.sock을 직접 연결하는 방식이 사용될 수 있습니다.

반면 여러 Docker 호스트를 관리하는 환경에서는 Agent를 사용하는 구조가 적합할 수 있습니다.

따라서 인터넷에서 발견한 Portainer 설치 방법을 그대로 적용하기 전에 현재 구성에서 Agent 방식인지 docker.sock 방식인지 먼저 확인하는 것이 좋습니다.

권한 문제와 네트워크 문제를 구분해야 한다

Portainer가 Docker Endpoint에 연결되지 않는다고 해서 항상 권한 문제인 것은 아닙니다.

대표적으로 다음과 같은 원인이 있습니다.

docker.sock 볼륨 매핑 오류

docker.sock 접근 권한 문제

Endpoint 설정 오류

Portainer 컨테이너 설정 오류

Docker Engine 상태 문제

따라서 오류 메시지를 확인하는 것이 중요합니다.

예를 들어 permission denied가 나타난다면 권한 문제를 우선 의심할 수 있습니다.

반면 Docker 데몬 자체에 연결할 수 없다는 메시지가 나타난다면 Docker Engine의 상태나 소켓 경로를 함께 확인해야 합니다.

Docker Engine 자체가 정상인지 확인한다

Portainer만 확인해서는 원인을 찾기 어려울 때도 있습니다.

시놀로지 Container Manager에서 다른 Docker 컨테이너가 정상적으로 실행되는지 확인해 보는 것도 도움이 됩니다.

다른 컨테이너까지 이상하게 동작한다면 Portainer만의 문제가 아니라 Docker Engine 또는 Container Manager 환경 자체의 문제일 가능성도 있습니다.

반대로 다른 컨테이너는 모두 정상인데 Portainer만 Docker Endpoint에 연결하지 못한다면 Portainer의 소켓 연결과 권한을 집중적으로 확인하는 것이 좋습니다.

Portainer 로그를 확인하면 원인을 좁힐 수 있다

Portainer가 Docker Engine에 연결되지 않는다면 Container Manager에서 Portainer 컨테이너의 로그를 확인합니다.

로그에서 다음과 같은 단어를 찾아보면 좋습니다.

docker.sock

permission denied

Docker daemon

endpoint

connection refused

오류 메시지에 따라 확인해야 할 부분이 달라집니다.

특히 permission denied가 반복된다면 단순한 네트워크 문제가 아니라 소켓 접근 권한을 우선 확인해야 합니다.

docker.sock을 외부에 공개하면 안 되는 이유

Docker 소켓은 매우 중요한 인터페이스입니다.

Portainer가 이 소켓에 접근할 수 있다는 것은 Docker Engine을 관리할 수 있다는 의미이기도 합니다.

따라서 Docker 소켓을 인터넷에 직접 노출하거나 불필요하게 외부에서 접근할 수 있도록 구성하는 것은 피해야 합니다.

Portainer 자체도 외부에서 접근해야 한다면 HTTPS, 강력한 관리자 인증, 접근 제한, 방화벽 등을 함께 고려해야 합니다.

단순히 Portainer 접속 문제를 해결하기 위해 Docker 소켓을 외부에 공개하는 것은 적절한 해결 방법이 아닙니다.

시놀로지에서 Portainer 권한 문제를 확인하는 순서

문제가 발생했다면 다음 순서로 확인하는 것이 좋습니다.

1. Portainer 컨테이너가 실행 중인지 확인

Container Manager에서 Portainer 상태를 확인합니다.

2. 웹 화면에 접속되는지 확인

접속 자체가 안 된다면 Portainer 컨테이너의 포트와 실행 상태부터 확인합니다.

3. Docker Endpoint 상태 확인

Portainer에서 Docker 환경이 연결되어 있는지 확인합니다.

4. docker.sock 볼륨 매핑 확인

호스트와 컨테이너 양쪽 경로가 올바른지 확인합니다.

5. 소켓 접근 권한 확인

permission denied가 발생하는지 로그를 확인합니다.

6. Portainer 데이터 볼륨 확인

/data 경로가 정상적으로 연결되어 있는지 확인합니다.

7. Docker Engine 상태 확인

다른 컨테이너가 정상적으로 실행되는지도 확인합니다.

8. 컨테이너를 재생성해야 하는지 검토

소켓 매핑이 처음부터 빠져 있었다면 올바른 설정으로 재생성하는 방법을 고려합니다.

docker.sock 권한은 정상인데 컨테이너 내부에서 파일 접근 문제가 발생한다면 이번에는 볼륨 매핑과 파일 권한을 별도로 확인해야 합니다.

무조건 chmod 777부터 하면 안 되는 이유

Docker 관련 권한 오류를 검색하면 파일 권한을 크게 변경하는 방법이 등장할 수 있습니다.

하지만 시놀로지 NAS에서 운영 중인 Docker 환경이라면 원인을 확인하지 않고 권한부터 크게 열어버리는 방식은 피하는 것이 좋습니다.

특히 Docker 소켓은 단순한 데이터 파일이 아닙니다.

Docker Engine을 제어할 수 있는 인터페이스이기 때문에 접근 권한을 가진 주체가 누구인지 신중하게 관리해야 합니다.

따라서

경로 확인

→ 볼륨 매핑 확인

→ 컨테이너 사용자 및 권한 확인

→ 로그 확인

순서로 접근하는 것이 안전합니다.

Portainer가 정상적으로 연결됐는지 확인하는 방법

설정을 수정한 뒤에는 Portainer 화면에서 Docker Endpoint가 정상적으로 연결되는지 확인합니다.

정상적으로 연결되면 Docker 환경에 대한 정보를 가져올 수 있고 컨테이너, 이미지, 네트워크 등의 관리 기능을 사용할 수 있습니다.

반대로 Endpoint가 계속 오프라인 상태로 표시되거나 Docker 관련 오류가 나타난다면 docker.sock 연결과 권한을 다시 확인해야 합니다.

단순히 Portainer 웹 화면이 열린다는 이유만으로 정상적으로 설치됐다고 판단하면 안 됩니다.

마무리

시놀로지 NAS에서 Portainer 설치 후 Docker Endpoint가 연결되지 않거나 docker.sock 접근 거부 오류가 발생한다면, 가장 먼저 확인해야 할 부분은 Docker 소켓의 연결 구조입니다.

Portainer는 Docker Engine을 관리하기 위해 docker.sock을 사용할 수 있어야 합니다.

따라서

Portainer

↓

docker.sock

↓

Docker Engine

이라는 연결 구조가 정상적으로 구성되어 있어야 합니다.

특히 다음과 같은 문제가 자주 발생합니다.

docker.sock 볼륨 매핑 누락

잘못된 소켓 경로

컨테이너의 소켓 접근 권한 부족

Portainer Endpoint 설정 오류

Docker Engine 자체의 문제

이 가운데 특히 주의해야 할 부분이 권한 문제입니다.

Docker 소켓은 강력한 권한을 가진 인터페이스이기 때문에 단순히 chmod 777 같은 방법으로 권한을 무작정 확대하는 것은 좋은 해결 방법이 아닙니다.

먼저 소켓 경로와 볼륨 매핑이 정확한지 확인하고, Portainer 컨테이너가 해당 소켓을 사용할 수 있는 환경인지 로그를 통해 확인하는 것이 우선입니다.

결국 Portainer 연결 오류를 해결하는 핵심은 “Portainer가 실행되고 있는가?”가 아니라 “Portainer가 Docker Engine과 통신할 수 있는 권한과 연결 구조를 갖추고 있는가?”를 확인하는 것입니다.

시놀로지 Container Manager에서 Portainer를 운영한다면 이 부분을 정확하게 이해해 두는 것만으로도 docker.sock, Endpoint 연결 실패, permission denied와 같은 오류의 원인을 훨씬 빠르게 찾을 수 있습니다.