왜 Docker로 Clash 사이드 게이트웨이를 쓰는가
거실 TV, 게임 콘솔, 일부 IoT 기기는 시스템 프록시 설정이 없거나 제한적입니다. 이때 기본 게이트웨이만 바꿔 트래픽을 옆집에 둔 작은 PC·NAS로 보내는 방식이 흔한데, 이 장치를 보통 사이드 라우터(旁路由)라고 부릅니다. Ubuntu에 바이너리를 직접 깔아 systemd로 돌리는 방법은 별도 글(Ubuntu·systemd·TUN)에서 다뤘고, 여기서는 Docker Clash로 같은 역할을 할 때만 달라지는 포인트—이미지·볼륨·포트 매핑·브리지/호스트 네트워크—에 초점을 맞춥니다.
NAS OS(예: 일부 제조사 앱 센터)나 홈서버는 커널 모듈·권한을 GUI로 감춰 두는 경우가 많아, 컨테이너로 올리면 업데이트와 롤백이 쉽습니다. 반대로 투명 프록시까지 한 번에 넣으려면 TUN·iptables·NET_ADMIN 같은 요구가 붙어 환경마다 난이도가 갈립니다. 이 글은 먼저 포트 기반 프록시 + LAN 게이트웨이/DNS로 안정적인 베이스를 만든 뒤, 필요할 때만 TUN 쪽으로 확장하는 순서를 권합니다.
토폴로지와 IP 계획
전형적인 홈 네트워크에서는 메인 공유기가 192.168.1.1이고 DHCP로 휴대폰·노트북을 나눠 줍니다. 사이드 장치(Clash Docker 호스트)에는 고정 LAN IP를 부여하는 편이 디버깅에 유리합니다. 예를 들어 192.168.1.10으로 고정했다면, TV는 여전히 192.168.1.0/24에 남기되 기본 게이트웨이만 192.168.1.10으로 지정하는 패턴이 됩니다. 메인 공유기는 인터넷 출구이자 동일 세그먼트 내의 “첫 홉” 역할을 하고, TV가 보낸 패킷은 먼저 1.10으로 와서 Clash가 규칙에 따라 프록시 또는 직접 연결로 넘깁니다.
서브넷을 아예 나누는 구성(예: 사이드 WAN을 메인 LAN에 붙이는 이중 NAT)도 가능하지만, 초보자에게는 단일 L2 세그먼트 + 게이트웨이만 분리가 설정·트래블슈팅 비용이 적습니다. 공유기 관리 화면에서 “게이트웨이·DNS를 수동으로 받는 장치”만 따로 적어 두면 나중에 혼선이 줄어듭니다.
Docker 쪽 사전 조건
호스트에 Docker(또는 호환 런타임)와 Compose v2가 있어야 합니다. NAS 이미지는 아키텍처(amd64·arm64)에 맞는 Clash·Mihomo 이미지를 골라야 하고, 호스트 방화벽이 Docker 체인을 덮어쓰는지도 미리 확인합니다. 구성 파일 config.yaml은 바인드 마운트로 읽기 전용으로 거는 예가 많지만, 구독 갱신 캐시를 쓰려면 해당 디렉터리는 쓰기 가능하게 두는 편이 낫습니다.
이미지 태그는 팀 정책에 따라 고정하세요. 공식 다운로드 페이지에서 안내하는 클라이언트·코어 정책을 먼저 확인하고, 컨테이너 허브의 서드파티 이미지를 쓸 때는 출처와 업데이트 주기를 문서화하는 것이 안전합니다. 오픈소스 저장소는 라이선스·이슈 확인용으로 두고, 설치 패키지·이미지 선택의 기준은 사이트 안내와 맞추는 것이 독자에게 혼선이 적습니다.
네트워크 모드: bridge vs host
기본 bridge에서는 컨테이너가 내부 IP를 받고, 호스트의 특정 TCP/UDP 포트를 컨테이너 포트에 포트 매핑으로 연결합니다. 반면 network_mode: host는 컨테이너가 호스트 네임스페이스를 공유해 127.0.0.1:9090 같은 바인딩이 호스트에 그대로 노출됩니다. 사이드 게이트웨이로 IP 포워딩·TUN을 건드릴 계획이면 host 모드가 단순해지는 경우가 있지만, NAS 제품은 host 네트워크를 막거나 권한을 제한하기도 합니다.
첫 세팅에서는 bridge + 명시적 포트 매핑으로 mixed-port·DNS·외부 컨트롤 API(필요 시)만 열어 두고, 동작이 안정화되면 host나 macvlan 같은 고급 옵션을 검토하는 흐름이 안전합니다. TUN·전역 트래픽 개념은 동일하지만, Docker 안에서는 커널 capability와 /dev/net/tun 마운트가 추가 변수입니다.
Compose 예시: 포트 매핑 정리
아래는 개념을 보여 주는 예시이며, 이미지 이름·경로·버전은 환경에 맞게 바꿔야 합니다. mihomo가 7890에서 mixed, 1053에서 DNS, 9090에서 외부 API를 듣는다고 가정합니다.
services:
mihomo:
image: example/mihomo:stable
restart: unless-stopped
volumes:
- ./config:/root/.config/mihomo
ports:
- "7890:7890/tcp"
- "1053:1053/udp"
- "9090:9090/tcp"
# cap_add / devices for TUN — only if you know you need them
호스트 방화벽에서 위 포트가 LAN에 열려 있는지 확인하세요. NAS는 “앱별 방화벽”이 별도인 경우가 있어, Docker를 통과해도 관리 UI에서 막히면 클라이언트가 타임아웃 납니다. 포트 매핑은 “호스트 IP:호스트포트 → 컨테이너포트” 관계이므로, TV 쪽 프록시를 쓸 계획이면 호스트의 192.168.1.10:7890이 실제로 리슨하는지 ss·관리 도구로 검증합니다.
Clash 측 최소 설정 포인트
mixed-port를 포트 매핑과 동일하게 맞추고, DNS 섹션은 사이드 장치가 LAN에 DNS 서버로 응답할지 여부에 따라 달라집니다. TV를 메인 공유기 DHCP만 쓰게 두고 게이트웨이만 바꾼 경우, DNS는 여전히 공유기를 가리키는 경우가 많습니다. 이때 Clash의 스니핑·규칙과 실제 DNS 경로가 어긋나 “일부 앱만 실패”가 나올 수 있으니, 문제가 보이면 TV에 192.168.1.10(또는 Clash가 듣는 DNS 포트)을 지정하는 편이 낫습니다.
allow-lan 또는 동등 옵션을 켜 외부 LAN에서 mixed 포트에 접속할 수 있게 하고, 인증 없는 외부 API 포트는 LAN에만 노출되게 제한하세요. 프로필에 구독 URL이 있으면 컨테이너가 인터넷에 나갈 수 있어야 하고, 실패 시 로그에 구독 다운로드 오류가 남습니다. 규칙 디버깅은 로그·DNS·규칙 점검 흐름과 같습니다.
클라이언트에 LAN 게이트웨이 적용하기
Android TV·일부 스마트 TV는 “고급 Wi‑Fi 옵션”에서 게이트웨이를 고를 수 있습니다. 값은 Clash Docker가 도는 호스트의 고정 IP입니다. 콘솔(PlayStation·Xbox·Switch)도 유선·무선 설정에 동일하게 “라우터 IP 대신 사이드 IP”를 넣습니다. 이때 메인 공유기와 충돌하지 않게 TV만 수동 설정으로 빼 두면, 나머지 가족 기기는 기존 DHCP를 유지할 수 있습니다.
게이트웨이를 바꾼 뒤에도 “특정 앱만 직통”을 원한다면 분할 라우팅이 필요해 난이도가 올라갑니다. 기본값은 해당 장치의 모든 외부 트래픽이 사이드 장치를 경유한다고 이해하면 됩니다. 사이드 장치가 꺼지면 해당 클라이언트는 인터넷이 끊기므로, UPS·자동 재시작 정책도 운영 체크리스트에 넣는 것이 좋습니다.
DNS·DHCP: 공유기와의 역할 나누기
메인 공유기가 DHCP로 DNS를 배포하고 있다면, 게이트웨이만 바꾼 TV는 여전히 공유기 DNS를 쓸 수 있습니다. Clash 규칙이 도메인 기반이라면 DNS가 Clash 앞단에서 먼저 해석되면 기대와 다른 경로로 나갈 수 있어, 증상이 보이면 TV에 Clash가 제공하는 DNS(또는 사이드 호스트 IP)을 직접 지정하세요. 반대로 가정 내 다른 PC는 공유기 DHCP를 유지해도 됩니다.
고급 사용자는 메인 공유기에서 특정 MAC 주소에만 다른 게이트웨이·DNS를 배포하도록 설정할 수 있습니다. 제조사·펌웨어마다 메뉴 이름이 다르지만, “정적 DHCP 예약 + 옵션” 정도로 검색하면 문서가 나옵니다. 이 방식이면 TV 리모컨으로 일일이 치지 않아도 되어 가족 구성원이 쓰기 편합니다.
투명 프록시(TUN)와 컨테이너 한계
투명 프록시에 가깝게 가려면 TUN 모드와 iptables/nftables 리다이렉트가 함께 등장합니다. Docker 안에서 이를 완성하려면 --cap-add=NET_ADMIN, /dev/net/tun, 때로는 privileged에 가까운 권한이 필요합니다. NAS는 이런 플래그를 UI에서 허용하지 않거나, 재부팅 후 규칙이 사라지는 경우가 있어, “컨테이너 한 방에 끝”이 잘 안 될 수 있습니다.
그럴 때는 첫 단계로 명시적 HTTP/SOCKS 프록시를 지원하는 앱만 사이드 경로를 타게 하거나, 게이트웨이 방식으로 전체 IP 트래픽을 Clash 쪽으로 보내되 TUN은 호스트 OS에서 직접 돌리는 타협을 고려합니다. 개념 정리는 TUN 모드 글과 맞춰 읽으면 Windows·리눅스·컨테이너 차이를 빠르게 정렬할 수 있습니다.
IP 포워딩과 라우팅 점검
사이드 장치가 게이트웨이 역할을 하려면 커널에서 IP forwarding이 켜져 있어야 합니다. 호스트에서 net.ipv4.ip_forward=1을 확인하고, Clash가 아닌 OS 레벨에서 포워딩이 막히면 “핑은 되는데 웹만 안 된다” 같은 증상이 납니다. Docker bridge만 쓰는 경우에도, NAT·masquerade가 필요한지는 토폴로지에 따라 다릅니다.
점검 순서로는 사이드 호스트에서 메인 공유기로, 인터넷으로 순서대로 traceroute를 찍어 어느 홉에서 끊기는지 보고, 동시에 Clash 로그에서 DIRECT와 프록시 규칙이 의도대로 찍히는지 확인합니다. MTU 문제는 VPN·터널 노드에서 가끔 드러나므로, 장시간 재현되는 끊김이면 MTU 조정 문서를 참고하세요.
문제 해결 체크리스트
첫째, 호스트 고정 IP·포트 매핑·방화벽 세 줄이 맞는지 다시 확인합니다. 둘째, TV가 실제로 새 게이트웨이를 쓰는지(일부 UI는 저장 후 재부팅 필요) 확인합니다. 셋째, DNS가 Clash 밖에서 먼저 해석되는지 dig·기기 내 네트워크 진단으로 봅니다. 넷째, 구독·노드가 죽어 있으면 게이트웨이까지는 가도 외부가 안 열리므로 코어 로그를 봅니다. 다섯째, NAS 앱 업데이트로 Docker 네트워크가 초기화된 경우가 있어, 업데이트 후 포트 바인딩이 사라졌는지 확인합니다.
증상을 좁힌 뒤에는 “정상일 때”의 라우팅 표·리스너 목록·Clash 버전을 메모해 두면 다음 장애 때 비교가 쉽습니다. 규칙이 길어졌다면 문서 허브의 고급 규칙 챕터와 함께 백업 정책을 세우는 것도 좋습니다.
정리
Docker Clash로 사이드 라우터를 만들 때 핵심은 세 가지입니다. 컨테이너와 호스트 사이의 포트 매핑과 방화벽을 일치시키고, LAN 클라이언트가 가리킬 LAN 게이트웨이(사이드 호스트 고정 IP)를 명확히 하며, 도메인 규칙을 쓸 계획이라면 DNS 경로까지 함께 설계하는 것입니다. 투명 프록시에 해당하는 TUN·iptables까지 한 번에 넣으려면 권한과 유지보수 부담이 커지므로, 먼저 mixed 포트와 게이트웨이 분리만으로 목표 기기가 안정적으로 동작하는지 검증하는 순서를 권합니다.
동일 코어를 쓰더라도 베어메탈 systemd 구성과 Docker 구성은 운영 포인트가 다릅니다. 위 순서대로 맞추면 TV·콘솔처럼 프록시 UI가 없는 기기도 재현 가능한 절차로 옆 경로 게이트웨이에 붙일 수 있습니다. 다른 플랫폼에서 이미 Clash를 쓰고 있다면, 규칙 파일만 공유해도 Docker 쪽은 디렉터리 마운트 한 번으로 맞출 수 있어 관리가 단순해집니다.