시놀로지 Docker 컨테이너 실행 후 포트 충돌이 발생하는 이유와 해결 방법

시놀로지 NAS에서 Docker 컨테이너를 사용하다 보면 컨테이너를 생성하거나 실행하는 과정에서 포트 충돌(Port Conflict) 문제가 발생하는 경우가 있습니다.

특히 새로운 웹 서비스나 서버 프로그램을 설치한 뒤 컨테이너가 실행되지 않거나 다음과 같은 오류 메시지가 표시될 수 있습니다.

Port is already allocated 또는 Bind for 0.0.0.0:8080 failed: port is already allocated

Container Manager에서는 컨테이너가 정상적으로 만들어진 것처럼 보이는데 막상 시작하려고 하면 오류가 발생하는 경우도 있습니다.

이런 문제는 대부분 Docker 자체의 오류라기보다 같은 NAS 포트를 두 개 이상의 서비스가 동시에 사용하려고 하기 때문에 발생합니다.

따라서 포트 충돌이 발생했다면 컨테이너를 다시 설치하기보다 먼저 어떤 서비스가 해당 포트를 사용하고 있는지 확인하는 것이 중요합니다.

Docker 포트는 왜 충돌할까?

Docker 컨테이너는 내부적으로 독립된 네트워크 환경에서 실행됩니다.

하지만 외부에서 NAS의 특정 서비스에 접속할 수 있도록 하려면 컨테이너의 포트를 NAS의 포트와 연결해야 합니다.

예를 들어 컨테이너 내부에서 웹 서비스가 8080 포트를 사용한다고 가정해 보겠습니다.

NAS 외부에서 접속하기 위해 다음과 같이 설정할 수 있습니다.

NAS 8080 → 컨테이너 8080

이때 이미 다른 컨테이너나 NAS 서비스가 NAS의 8080 포트를 사용하고 있다면 새로운 컨테이너가 같은 포트를 사용할 수 없습니다.

즉, 컨테이너 A → NAS 8080, 컨테이너 B → NAS 8080 처럼 동일한 NAS 포트를 두 서비스가 동시에 사용하려고 하면 충돌이 발생합니다.

컨테이너 내부 포트와 NAS 포트는 다르다

Docker 포트 충돌을 이해하려면 컨테이너 포트와 호스트 포트의 차이를 알아야 합니다.

예를 들어 다음과 같이 설정했다고 가정해 보겠습니다.

NAS 포트 8081 → 컨테이너 포트 8080

이 경우 사용자가 NAS의 8081 포트로 접속하면 Docker가 해당 요청을 컨테이너의 8080 포트로 전달합니다.

중요한 것은 여러 컨테이너가 동일한 컨테이너 내부 포트를 사용하는 것은 문제가 되지 않는다는 것입니다.

예를 들어 컨테이너 A: 내부 8080, 컨테이너 B: 내부 8080으로 구성하는 것은 가능합니다.

대신 NAS에서 사용하는 호스트 포트는 서로 달라야 합니다.

예를 들어 NAS 8081 → 컨테이너 A 8080, NAS 8082 → 컨테이너 B 8080 처럼 구성하면 두 컨테이너를 동시에 실행할 수 있습니다.

따라서 포트 충돌이 발생했을 때는 컨테이너 포트가 같은지보다 NAS의 호스트 포트가 중복되는지를 먼저 확인해야 합니다.

가장 흔한 원인은 기존 컨테이너와 포트가 겹치는 경우

가장 흔한 원인은 이미 실행 중인 다른 Docker 컨테이너가 같은 포트를 사용하고 있는 경우입니다.

예를 들어 기존에 Jellyfin → NAS 8096을 사용하고 있는데 새 컨테이너도 NAS의 8096 포트를 사용하도록 설정했다면 충돌이 발생할 수 있습니다.

특히 여러 서비스를 설치하다 보면 어떤 포트를 사용하고 있는지 기억하기 어려워집니다.

따라서 새로운 컨테이너를 추가할 때는 기존 컨테이너의 포트 설정부터 확인하는 것이 좋습니다.

시놀로지 NAS 자체 서비스와 충돌할 수도 있다

포트 충돌은 Docker 컨테이너끼리만 발생하는 것이 아닙니다.

NAS에서 실행되는 DSM이나 기타 서비스가 이미 해당 포트를 사용하고 있을 수도 있습니다.

예를 들어 NAS에서 특정 웹 서비스가 5000, 5001 등의 포트를 사용하고 있는데 Docker 컨테이너를 동일한 호스트 포트로 설정한다면 충돌할 수 있습니다.

따라서 Docker 컨테이너를 설치할 때는 Docker에서 사용하는 포트뿐만 아니라 NAS 자체에서 사용하는 포트도 고려해야 합니다.

Container Manager에서 포트 매핑 확인

시놀로지 Container Manager에서 컨테이너를 선택하면 해당 컨테이너의 포트 매핑을 확인할 수 있습니다.

예를 들어 다음과 같이 표시될 수 있습니다.

로컬 포트	컨테이너 포트
8080	8080
8443	443

여기서 로컬 포트가 NAS에서 실제로 사용하는 호스트 포트입니다.

컨테이너 내부의 8080과 다른 서비스의 컨테이너 내부 8080이 같아도 문제가 되지 않을 수 있지만, 같은 NAS에서 두 컨테이너가 모두 8080을 사용하도록 매핑하면 충돌합니다.

따라서 충돌이 발생하면 먼저 로컬 포트가 다른 서비스와 중복되는지 확인해야 합니다.

다만 컨테이너의 네트워크 모드가 Bridge인지 Host인지에 따라 포트가 동작하는 방식도 달라질 수 있습니다.

포트 번호를 변경하면 해결할 수 있다

가장 간단한 해결 방법은 호스트 포트를 변경하는 것입니다.

예를 들어 기존 컨테이너가 NAS 8080 → 컨테이너 8080을 사용하고 있다면 새 컨테이너를 NAS 8081 → 컨테이너 8080으로 변경할 수 있습니다.

컨테이너 내부 포트는 그대로 두고 NAS에서 사용하는 포트만 변경하는 방식입니다.

이렇게 하면 컨테이너 내부 프로그램의 설정을 크게 변경하지 않고도 포트 충돌을 해결할 수 있습니다.

포트 변경 후 접속 주소도 달라진다

호스트 포트를 변경하면 외부에서 접속하는 주소도 달라집니다.

예를 들어 기존에 http://NAS주소:8080으로 접속했다면 포트를 8081로 변경한 이후에는 http://NAS주소:8081로 접속해야 합니다.

이 부분을 놓치면 컨테이너는 정상적으로 실행됐는데 접속이 안 되는 것처럼 보일 수 있습니다.

따라서 포트를 변경했다면 북마크나 역방향 프록시 설정 등 기존 접속 경로도 함께 확인해야 합니다.

역방향 프록시를 사용하는 경우

시놀로지 NAS에서 여러 Docker 서비스를 운영한다면 역방향 프록시를 사용하는 경우가 많습니다.

예를 들어 service1.example.com은 컨테이너 A로 연결하고, service2.example.com은 컨테이너 B로 연결하는 방식입니다.

이 경우 외부에서는 모두 기본 HTTPS 포트를 사용하는 것처럼 보이지만 NAS 내부에서는 각각 다른 컨테이너 포트로 연결할 수 있습니다.

예를 들어 service1 → NAS 8081 → 컨테이너 A, service2 → NAS 8082 → 컨테이너 B 처럼 구성할 수 있습니다.

따라서 포트가 부족하다고 해서 반드시 외부에서 여러 포트를 직접 개방해야 하는 것은 아닙니다.

Docker Compose에서 포트 충돌이 발생하는 경우

Docker Compose를 이용해 컨테이너를 생성하는 경우 ports 항목에서 호스트 포트를 지정합니다.

예를 들어 8080:80 이라고 설정했다면 일반적으로 NAS 8080 → 컨테이너 80이라는 의미입니다.

이때 다른 서비스에서 이미 NAS의 8080 포트를 사용하고 있다면 Compose를 실행하는 과정에서 포트 충돌이 발생할 수 있습니다.

이 경우 컨테이너 포트 80을 변경할 필요 없이 앞의 호스트 포트만 변경할 수 있습니다.

예를 들어 8081:80으로 변경하면 NAS 8081 → 컨테이너 80으로 연결됩니다.

Compose 파일에서 포트를 변경할 때 주의할 점

포트를 변경했다고 해서 모든 문제가 자동으로 해결되는 것은 아닙니다.

다른 서비스가 해당 포트를 참조하고 있다면 관련 설정도 함께 변경해야 합니다.

예를 들어 애플리케이션에서 데이터베이스를 특정 포트로 참조하도록 설정했거나 역방향 프록시에서 기존 포트를 사용하고 있다면 포트 변경 후 연결이 끊어질 수 있습니다.

따라서 Compose 파일의 포트 설정뿐만 아니라 환경변수, 네트워크, 역방향 프록시 등의 연결 관계도 함께 확인하는 것이 좋습니다.

포트 충돌과 포트포워딩은 다른 문제다

초보자가 자주 혼동하는 부분입니다.

Docker의 포트 충돌은 NAS 내부에서 같은 호스트 포트를 여러 서비스가 사용하려고 할 때 발생하는 문제입니다.

반면 공유기의 포트포워딩은 인터넷에서 들어오는 연결을 NAS 내부의 특정 IP와 포트로 전달하는 설정입니다.

즉, Docker 포트 매핑과 공유기 포트포워딩은 서로 다른 단계입니다.

예를 들어 인터넷 → 공유기 443 → NAS 443 → 역방향 프록시 → Docker 컨테이너 처럼 여러 단계로 연결될 수 있습니다.

따라서 Docker 컨테이너에서 포트 충돌이 발생했다고 해서 공유기의 포트포워딩부터 변경할 필요는 없습니다.

먼저 NAS 내부에서 어떤 서비스가 해당 포트를 사용하고 있는지 확인해야 합니다.

포트가 열려 있는데도 접속되지 않는 경우

포트 충돌을 해결했는데도 컨테이너에 접속할 수 없다면 다른 원인을 확인해야 합니다.

대표적으로 다음과 같은 문제가 있습니다.

컨테이너가 실제로 실행되지 않았습니다.

컨테이너 내부 프로그램이 다른 포트에서 실행되고 있습니다.

포트 매핑이 잘못됐습니다.

컨테이너의 네트워크 모드가 다릅니다.

NAS 방화벽이 접근을 차단하고 있습니다.

공유기의 포트포워딩이 잘못됐습니다.

애플리케이션 자체가 실행에 실패했습니다.

특히 컨테이너 상태가 Running으로 표시되더라도 내부 애플리케이션이 정상적으로 실행되고 있다는 의미는 아닐 수 있습니다.

이 경우 컨테이너 로그를 함께 확인해야 합니다.

포트 충돌이 발생했을 때 확인하는 순서

포트 충돌이 발생했다면 다음 순서로 확인하는 것이 좋습니다.

먼저 오류 메시지에서 충돌한 포트 번호를 확인합니다.

그다음 Container Manager에서 기존 컨테이너의 포트 매핑을 확인합니다.

NAS 자체 서비스가 해당 포트를 사용하는지도 확인합니다.

새로 생성한 컨테이너의 호스트 포트와 컨테이너 포트를 구분해서 확인합니다.

동일한 호스트 포트를 사용하고 있다면 새로운 포트로 변경합니다.

포트를 변경한 뒤 컨테이너를 다시 실행합니다.

정상적으로 실행되면 변경된 포트로 접속합니다.

역방향 프록시를 사용하는 경우 변경된 내부 포트도 함께 수정합니다.

외부에서 접속하는 구조라면 공유기의 포트포워딩도 필요한지 확인합니다.

마지막으로 컨테이너 로그를 확인해 애플리케이션 자체에 다른 오류가 없는지 확인합니다.

사용하지 않는 포트를 정리하는 것도 중요하다

Docker 서비스를 계속 추가하다 보면 사용하지 않는 컨테이너나 테스트용 서비스가 남아 있는 경우가 있습니다.

이런 컨테이너가 포트를 계속 점유하고 있으면 새로운 서비스를 설치할 때 포트 충돌이 발생할 수 있습니다.

따라서 NAS에서 운영하지 않는 컨테이너가 있다면 상태와 포트 매핑을 정리하는 것이 좋습니다.

다만 컨테이너를 삭제하기 전에 해당 컨테이너에서 사용하는 볼륨과 데이터가 무엇인지 확인해야 합니다.

특히 데이터베이스나 파일 서버처럼 중요한 데이터를 저장하는 컨테이너는 단순히 삭제하면 안 됩니다.

포트를 무작정 변경하면 안 되는 이유

포트 충돌을 해결하기 위해 아무 숫자로 변경하는 것도 좋은 방법은 아닙니다.

특히 이미 다른 서비스에서 사용하는 포트를 피해야 합니다.

또한 외부에 서비스를 공개할 경우 어떤 포트를 인터넷에 노출하는지도 고려해야 합니다.

가능하면 Docker 내부 네트워크와 역방향 프록시를 활용하여 외부에 직접 노출하는 포트를 최소화하는 것이 좋습니다.

포트가 다르다고 해서 보안 문제가 자동으로 해결되는 것도 아닙니다.

보안이 필요한 서비스라면 인증, HTTPS, 방화벽 및 접근 제한 설정을 함께 고려해야 합니다.

마무리

시놀로지 Docker 컨테이너를 실행한 뒤 포트 충돌이 발생하는 가장 일반적인 이유는 같은 NAS의 호스트 포트를 두 개 이상의 서비스가 동시에 사용하려 하기 때문입니다.

특히 다음과 같은 구조에서 쉽게 발생합니다.

기존 컨테이너 → NAS 8080

새 컨테이너 → NAS 8080

두 컨테이너가 같은 호스트 포트를 사용하려 하기 때문에 하나의 서비스가 정상적으로 실행되지 않습니다.

이때 중요한 것은 컨테이너 포트와 NAS 호스트 포트를 구분하는 것입니다.

예를 들어 NAS 8081 → 컨테이너 8080으로 변경하면 컨테이너 내부의 서비스 포트는 그대로 유지하면서 NAS에서 사용하는 포트만 변경할 수 있습니다.

포트 충돌이 발생했을 때는 충돌 포트 확인 → 기존 컨테이너 확인 → NAS 서비스 확인 → 호스트 포트 변경 → 접속 주소 변경 → 역방향 프록시 확인 순서로 점검하는 것이 좋습니다.

또한 Docker의 포트 매핑과 공유기의 포트포워딩은 서로 다른 설정이므로 두 가지를 혼동하지 않아야 합니다.

결국 시놀로지에서 Docker 컨테이너를 여러 개 운영할 때는 각 서비스가 어떤 호스트 포트를 사용하는지 관리하는 것이 중요합니다.

처음부터 컨테이너별 포트 사용 현황을 정리해 두면 새로운 서비스를 추가할 때 발생하는 포트 충돌을 상당 부분 예방할 수 있습니다.