커뮤니티 솔루션

Gluetun을 사용해 ZimaOS 앱을 VPN으로 라우팅하기

A ZimaOS user looking for WireGuard client mode discovered Gluetun as the practical Docker VPN-client path. Later replies worked through qBittorrent routing, shared network namespaces, and port conflicts.

선택한 ZimaOS 애플리케이션의 트래픽을 상용 VPN을 통해 전송하려면, 커뮤니티 스레드에서는 WireGuard App Store 항목을 클라이언트 설정 파일을 간단히 업로드하는 인터페이스로 보는 대신 Gluetun을 사용할 것을 제안합니다. 원래 작성자는 WireGuard를 클라이언트로 실행하는 방법을 물었지만, 이후 ZimaOS에서 Gluetun을 발견하고 Docker 네트워크 방식을 문서화했습니다.

핵심 설계는 대상 앱이 Gluetun의 네트워크 네임스페이스를 공유하는 것입니다. Gluetun이 VPN 터널, 방화벽, 게시 포트를 관리하고, qBittorrent 또는 다른 애플리케이션은 자체 일반 브리지 인터페이스 대신 해당 네트워크 스택을 사용합니다.

ZimaOS App Store의 WireGuard와 Tailscale은 VPN 제공업체 클라이언트와 동일하지 않습니다

Zima-Giorgio는 WireGuard와 Tailscale을 App Store에서 사용할 수 있다고 답했습니다. 그러자 작성자는 빠진 부분을 명확히 했습니다. 제공업체 설정을 가져와 애플리케이션 트래픽을 라우팅하는 클라이언트 방식이 필요했던 것입니다.

이 구분은 중요합니다. Tailscale과 자체 호스팅 WireGuard 엔드포인트는 비공개 원격 액세스 네트워킹에 유용하지만, Gluetun은 OpenVPN 또는 WireGuard를 사용해 지원되는 상용 VPN 제공업체를 통해 Docker 워크로드를 연결하도록 특별히 설계되었습니다.

원문 스레드에서 Gluetun을 찾은 과정

작성자는 나중에 ZimaOS에 Gluetun이 포함되어 있었지만, App Store에서 일반적인 용어인 “VPN”을 검색해도 쉽게 찾을 수 없었다고 썼습니다.

원래 조언은 터널링할 애플리케이션의 네트워킹을 일반 브리지 모드에서 Gluetun의 네트워크 네임스페이스로 변경하고, Gluetun이 포트를 게시해야 하므로 애플리케이션 자체의 게시 포트를 제거하라는 것이었습니다.

network_mode: container:gluetun

외부 컨테이너가 이름으로 이미 실행 중인 Gluetun 컨테이너에 연결할 때 유효한 구문입니다.

service:gluetun과 container:gluetun

현재 Gluetun 문서에서는 일반적인 Compose 사례를 두 가지로 구분합니다.

# 동일한 Compose 프로젝트
network_mode: "service:gluetun"

그리고:

# 별도의 Compose 프로젝트 / 외부 컨테이너
network_mode: "container:gluetun"

커뮤니티 논의에서는 두 가지 형식이 개념적으로 모두 등장했습니다. 올바른 형식은 Gluetun과 라우팅할 애플리케이션이 동일한 Compose 스택에 있는지에 따라 달라집니다.

현재 Gluetun 컨테이너 네트워킹 가이드

qBittorrent에서 ISP IP가 여전히 유출될 수 있는 이유

이후 한 사용자는 Gluetun 자체의 로그에는 NordVPN IP가 표시되었지만 테스트했을 때 qBittorrent는 여전히 ISP 주소를 사용하는 것처럼 보였다고 보고했습니다. 이 증상은 “Gluetun이 연결됨”과 “qBittorrent가 실제로 Gluetun의 네트워크 스택을 공유함”을 별도로 테스트해야 한다는 의미입니다.

qBittorrent 컨테이너 정의를 확인하고 네트워크 모드가 실제로 Gluetun에 연결되어 있는지 확인하세요. Gluetun과 함께 일반 브리지 인터페이스를 사용하면 qBittorrent가 일반 호스트 경로를 사용할 수 있습니다.

qBittorrent 포트를 Gluetun 컨테이너로 이동

Gluetun의 현재 문서에 따르면 다른 컨테이너가 Gluetun의 네트워크 스택을 공유할 때 대상 애플리케이션의 포트는 Gluetun에 게시해야 합니다.

예를 들어 qBittorrent가 내부적으로 8080 포트에서 수신 대기하는 경우:

services:
  gluetun:
    image: qmcgaw/gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    ports:
      - "8080:8080"

  qbittorrent:
    image: your-qbittorrent-image
    network_mode: "service:gluetun"

두 컨테이너에서 동일한 qBittorrent 포트를 게시하지 마세요. 그러면 소스 스레드에 설명된 포트 충돌이 발생합니다.

Gluetun 포트 매핑 가이드

커뮤니티 스레드에서 언급된 동영상

이후 한 참가자는 qBittorrent의 트래픽을 Gluetun을 통해 라우팅하려고 DB Tech의 CasaOS 동영상을 따라 했다고 명시적으로 말했습니다. 해당 동영상은 소스 스레드의 문제 해결 과정에 포함되어 있으므로 여기에 보존합니다.

이 동영상은 ZimaOS 스레드보다 먼저 제작되었고 CasaOS를 사용하므로, 모든 UI 단계를 그대로 따라 하기보다는 Docker/Gluetun 아키텍처를 이해하는 데 활용하세요.

이후 다른 사용자가 사용자 지정 Compose 스택이 작동한다고 확인했습니다

2025년 11월, 다른 커뮤니티 구성원은 신뢰할 수 있는 해결 방법이 qBittorrent와 Gluetun을 함께 사용자 지정 앱/Compose 스택으로 배포하고 그곳에서 VPN 공급자를 구성하는 것이라고 말했습니다. 선택한 호스트 포트로 qBittorrent에 접속하면 VPN을 통해 라우팅된 트래픽이 표시된다고 보고했습니다.

소스 스레드에는 해당 설정을 위한 사용자가 만든 Gist 링크가 포함되어 있습니다. 타사 Compose 파일은 예시로만 취급하고, 배포하기 전에 환경 변수, 이미지 버전, 시크릿 및 네트워크 설정을 검토하세요.

Gluetun은 VPN 킬 스위치를 제공합니다

현재 Gluetun 문서는 VPN 경로를 사용할 수 없을 때 방화벽이 일반 인터페이스를 통해 나가서는 안 되는 트래픽을 차단하는 킬 스위치로 방화벽을 설명합니다. 이것이 단순히 qBittorrent 옆에 VPN 컨테이너를 시작하는 것보다 Gluetun의 네트워크 스택을 공유하는 편이 나은 이유 중 하나입니다.

포트에 연결할 수 있게 하려고 Gluetun 방화벽 규칙을 비활성화하지 마세요. 의도한 LAN/출력 라우트를 대신 수정하세요.

LAN 액세스를 의도적으로 허용하세요

라우팅되는 앱이 로컬 서브넷에 연결해야 하는 경우 Gluetun은 다음을 지원합니다. FIREWALL_OUTBOUND_SUBNETS예를 들면 다음과 같습니다.

FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24

실제 LAN 서브넷을 사용하고 VPN 터널 범위와 겹치지 않도록 하세요.

VPN 제공업체 포트 포워딩은 Docker 포트 매핑과 다릅니다

Gluetun 문서에서는 다음을 구분합니다.

  • Docker 포트 게시: LAN에서 qBittorrent WebUI에 연결할 수 있도록 하는 기능입니다.
  • VPN 제공업체 포트 포워딩: 이를 지원하는 VPN 제공업체로부터 인바운드 포트를 할당받는 기능입니다.

활성화하지 마세요 VPN_PORT_FORWARDING 로컬 qBittorrent WebUI 액세스 문제만 해결하기 위한 것입니다. 두 기능은 서로 다른 문제를 해결합니다.

ZimaOS Gluetun 체크리스트

  1. 현재 제공업체 문서를 기준으로 실제 VPN 제공업체에 맞게 Gluetun을 구성하세요.
  2. Gluetun 로그에 예상되는 VPN 출구 IP가 표시되는지 확인하세요.
  3. 대상 앱을 Gluetun의 네트워크 네임스페이스에 넣으세요.
  4. 사용 service:gluetun 동일한 Compose 스택의 경우 또는 container:gluetun 외부 컨테이너의 경우
  5. 라우팅되는 애플리케이션에서 중복으로 게시된 포트를 제거하세요.
  6. 필요한 WebUI/수신 포트를 Gluetun에 게시하세요.
  7. 스택을 다시 시작하세요.
  8. Gluetun 자체 로그와 별도로 대상 애플리케이션의 공인 IP를 테스트하세요.
  9. VPN 자격 증명과 WireGuard 개인 키를 공개 Compose 파일에 포함하지 마세요.

ZimaOS Gluetun 체크리스트

ZimaOS에서 qBittorrent만 VPN을 통해 라우팅할 수 있나요?

예. 커뮤니티 스레드에서는 모든 ZimaOS 서비스를 터널링하는 대신, Gluetun을 사용해 선택한 Docker 애플리케이션과 VPN 네트워크 스택을 공유했습니다.

Gluetun에는 VPN IP가 표시되는데 qBittorrent에는 여전히 ISP IP가 표시되는 이유는 무엇인가요?

VPN 컨테이너는 정상 상태일 수 있지만 qBittorrent가 여전히 일반 네트워크에 연결되어 있을 수 있기 때문입니다. qBittorrent의 실제 네트워크 모드를 확인하세요.

포트를 변경하면 qBittorrent WebUI가 작동하지 않는 이유는 무엇인가요?

qBittorrent가 Gluetun의 네트워크 네임스페이스를 공유하는 경우, qBittorrent가 아니라 Gluetun에 WebUI 포트를 게시하세요.

service:gluetun과 container:gluetun 중 무엇을 사용해야 하나요?

사용 service:gluetun 두 서비스가 동일한 Compose 프로젝트에 있을 때 사용합니다. container:gluetun 외부 컨테이너가 이름이 지정된 Gluetun 컨테이너에 연결될 때