어떤 증상인가
macOS나 Windows, Linux 호스트에서 Clash(또는 Mihomo 기반 GUI)를 켠 뒤 브라우저로는 노드 출구가 정상인데, 같은 머신에서 돌아가는 Docker 컨테이너 안의 curl·apt·pip·npm만 타임아웃되거나 집/회사 회선 IP로만 나가는 경우를 말합니다. 검색어로는 Docker Clash, HTTP_PROXY, 컨테이너 프록시, 브리지 네트워크처럼 묶어 적는 경우가 많습니다.
이 패턴은 대개 「구독 URL이 망가졌다」보다 앞서, 컨테이너가 호스트에서 열어 둔 로컬 프록시 포트까지 트래픽을 보내고 있지 않다는 신호에 가깝습니다. 특히 기본 브리지 네트워크를 쓰면 컨테이너의 127.0.0.1은 호스트의 루프백과 다른 네임스페이스이므로, 호스트에서 http://127.0.0.1:7890으로 잘 되는 설정을 컨테이너에 그대로 복사하면 거의 항상 실패합니다. 이 글에서는 그 전제를 바로잡고, HTTP_PROXY 계열 환경 변수를 호스트의 실제 도달 주소에 맞춘 뒤 검증하는 순서를 적습니다.
브리지 네트워크에서 127.0.0.1이 통하지 않는 이유
Docker는 컨테이너마다 네트워크 네임스페이스를 나눕니다. 브리지 모드에서 컨테이너가 보는 127.0.0.1은 그 컨테이너 자신을 가리킬 뿐이고, 호스트에서 Clash가 리슨하는 포트와 연결되지 않습니다. 그래서 호스트 셸에서 export https_proxy=http://127.0.0.1:7890이 잘 먹더라도, 컨테이너 Dockerfile이나 Compose에 같은 문자열을 넣으면 프록시 데몬이 없는 쪽으로 붙으려다 실패합니다.
반대로 호스트가 아닌 다른 컨테이너끼리 통신할 때는 Docker DNS 이름을 쓰면 되지만, 「호스트에서 돌아가는 Clash」로 나가야 할 때는 호스트 OS의 IP(또는 예약 호스트명)가 필요합니다. WSL2 안의 리눅스에서 비슷한 「127.0.0.1 착각」을 다룬 글은 WSL2·호스트 프록시 브리지 가이드와 원리가 맞닿아 있으니, 윈도우 개발자는 두 문서를 함께 두고 보는 편이 좋습니다.
1단계: 컨테이너에서 호스트 IP(또는 host.docker.internal) 정하기
Docker Desktop(macOS·Windows)에서는 컨테이너 안에서 host.docker.internal이 호스트를 가리키는 경우가 많습니다. 아래처럼 빠르게 확인해 볼 수 있습니다.
docker run --rm curlimages/curl:latest -sS http://host.docker.internal:7890 2>&1 | head
포트 번호 7890은 본인 Clash 화면의 HTTP 또는 mixed 포트로 바꿉니다. 연결이 거절되면 아직 Allow LAN·바인드·방화벽 문제일 수 있으니 2단계로 넘어가기 전에 호스트 셸에서 같은 포트가 열려 있는지부터 확인합니다.
Linux 네이티브 Docker에서는 host.docker.internal이 기본으로 없을 수 있습니다. 이때는 docker run에 --add-host=host.docker.internal:host-gateway를 붙이거나, Compose에서 extra_hosts로 같은 매핑을 추가하는 방식이 흔합니다. 또 다른 방법은 브리지의 기본 게이트웨이(보통 172.17.0.1 등)를 쓰는 것인데, 환경마다 대역이 달라 먼저 컨테이너 안에서 ip route로 게이트웨이를 확인하고 그 주소를 HOST_IP 자리에 넣는 편이 안전합니다.
network_mode: host를 쓰면 리눅스에서 컨테이너가 호스트 네트워크 스택을 공유해 127.0.0.1이 다시 호스트와 같아질 수 있지만, 격리가 풀리고 이식성이 떨어져 개발 편의와 운영 정책을 함께 봐야 합니다. 본문은 가장 흔한 브리지 + HTTP_PROXY 축에 맞춥니다.
2단계: Clash에서 Allow LAN과 인바운드
컨테이너(또는 VM)에서 호스트 IP로 프록시 포트에 붙으려면, Clash가 127.0.0.1에만 바인딩되어 있으면 외부 인터페이스에서 들어오는 연결을 받지 못합니다. 클라이언트에서 Allow LAN(또는 동등 옵션)을 켜 HTTP·mixed 포트가 0.0.0.0에서 리슨하도록 맞춥니다.
Windows Defender 방화벽 등에서 해당 TCP 포트 인바운드가 막혀 있으면 컨테이너에서도 거절됩니다. 인바운드 규칙을 어디에 열어야 할지는 LAN 프록시·방화벽 가이드와 같은 맥락입니다. Docker Clash 검색으로 이 페이지에 온 경우에도, 프록시 문자열만 바꾸고 이 단계를 빼먹으면 같은 증상이 반복됩니다.
3단계: HTTP_PROXY·HTTPS_PROXY·NO_PROXY 맞추기
호스트 도달 주소를 HOST, 포트를 7890이라 하면, 컨테이너 안에서 쓰는 전형적인 값은 다음과 같습니다.
http://host.docker.internal:7890
Linux에서 host-gateway 매핑을 썼다면 동일하게 host.docker.internal 문자열을 쓸 수 있습니다. 게이트웨이 IP를 직접 쓸 때는 http://172.17.0.1:7890처럼 환경마다 바뀌는 값임을 기억해야 합니다.
docker run 예시는 다음과 같습니다(이미지와 셸은 예시).
docker run --rm -it \
-e HTTP_PROXY="http://host.docker.internal:7890" \
-e HTTPS_PROXY="http://host.docker.internal:7890" \
-e http_proxy="http://host.docker.internal:7890" \
-e https_proxy="http://host.docker.internal:7890" \
-e NO_PROXY="localhost,127.0.0.1,::1,host.docker.internal" \
-e no_proxy="localhost,127.0.0.1,::1,host.docker.internal" \
curlimages/curl:latest \
sh -c 'curl -sS https://api.ipify.org; echo'
SOCKS 포트를 쓰는 경우에는 ALL_PROXY=socks5://HOST:7891 형태를 추가하는 팀도 많습니다. 다만 일부 도구는 HTTP CONNECT 경로가 더 단순해, 먼저 HTTP 프록시 포트로 출구가 바뀌는지 확인하는 것을 권장합니다.
NO_PROXY에 사내 레지스트리·내부 API 호스트명을 넣지 않으면, 원래 직통이어야 할 트래픽까지 프록시로 돌아 실패하는 경우가 생깁니다. 반대로 내부망 전체를 넣었다가 외부 도메인까지 빠져나가지 못하면 규칙을 다시 쪼개야 합니다.
4단계: Docker Compose에서 같은 값 고정하기
팀에서 Docker Compose로 서비스를 올린다면, environment 블록에 위 변수들을 두고 버전 관리합니다. 호스트 IP 대역이 자주 바뀌는 노트북이라면, 스크립트로 게이트웨이를 읽어 .env를 생성하는 방식이 덜 깨집니다.
services:
app:
image: your-image:tag
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
HTTP_PROXY: http://host.docker.internal:7890
HTTPS_PROXY: http://host.docker.internal:7890
NO_PROXY: localhost,127.0.0.1,::1,host.docker.internal,.internal
# ports, volumes ...
여러 프로젝트가 같은 값을 쓰면 x-env-file: .env.proxy처럼 공통 파일로 빼 두는 편이 덜 실수납니다. 컨테이너 프록시 이슈는 종종 「한 레포만」이 아니라 로컬 전역 설정이라서, 팀 내에서 문자열을 통일해 두면 재현이 쉬워집니다.
5단계: docker build·BuildKit이 프록시를 타는 경우
이미지 빌드 단계에서 apt·apk·curl로 외부를 받아온다면, 런타임뿐 아니라 빌드 ARG/환경에도 동일한 프록시가 필요할 수 있습니다. BuildKit을 쓰는 환경에서는 CLI 옵션이나 데몬 설정에서 빌드 타임 프록시를 넘기는 방식이 문서화되어 있으니, 증상이 「실행은 되는데 빌드만 실패」일 때 이 축을 의심합니다.
6단계: DNS·Fake-IP와의 관계
프록시 연결은 되는데 특정 도메인만 이상하다면 Clash 쪽 DNS 모드·Fake-IP와의 상호작용을 봐야 합니다. 컨테이너 내부 리졸버가 호스트와 다르면, 브라우저와 curl의 해석 결과가 갈라지기도 합니다. 개념 정리는 Fake-IP·DNS 가이드를 함께 읽으면 좋습니다. HTTP_PROXY만 맞추고 DNS를 그대로 두면 같은 벽에 다시 부딪히기 쉽습니다.
7단계: 한 번에 검증하는 명령 습관
문제를 기록할 때는 「호스트 브라우저 출구」「컨테이너 curl 출구」「echo $HTTPS_PROXY」를 한 줄로 적어 두면 이후 규칙을 손볼 때 비교가 빨라집니다. 컨테이너 안에서:
env | grep -i proxy
curl -sS https://api.ipify.org; echo
출력 IP가 Clash 노드 쪽과 맞으면, 브리지 네트워크 위에서 호스트 프록시를 실제로 경유한 것입니다. 여전히 집 IP라면 (1) Allow LAN·바인드 (2) 방화벽 (3) 주소 후보 host.docker.internal vs 게이트웨이 IP (4) 포트 번호 순으로 다시 좁힙니다.
그래도 애매할 때: TUN·호스트 측 정책
환경 변수를 주어도 특정 바이너리만 프록시를 무시한다면 애플리케이션 자체 설정이나 Go·Java 런타임의 프록시 인식 방식을 봐야 합니다. 호스트 전체를 커널 레벨에서 모으려면 TUN 모드를 검토할 수 있으나, 다른 VPN과의 충돌·권한 문제를 먼저 읽고 켜는 것이 안전합니다.
한눈에 보는 점검 순서
- 컨테이너의
127.0.0.1이 호스트 Clash와 같지 않다는 전제를 둔다. host.docker.internal또는 브리지 게이트웨이 IP로 호스트에 도달 가능한지 본다.- Clash에서 Allow LAN·리슨 주소·실제 포트 번호를 확인한다.
- 호스트 방화벽에서 해당 포트 TCP 인바운드를 허용한다.
HTTP_PROXY·HTTPS_PROXY·필요 시ALL_PROXY와NO_PROXY를 맞춘다.- 컨테이너 안
curl로 출구 IP를 확인하고, 이상 시 DNS·Fake-IP를 함께 본다.
맺음말
Docker Clash 조합에서 가장 흔한 실수는 「호스트에서 되던 127.0.0.1:7890을 컨테이너에도 그대로 넣는 것」입니다. 브리지 네트워크를 쓰는 한, 호스트의 Clash에 닿으려면 호스트 도달 주소·Allow LAN·방화벽·HTTP_PROXY 계열 환경 변수를 한 세트로 보는 편이 빠릅니다. Clash 계열 클라이언트는 포트·LAN 허용·코어 로그를 한 화면에서 다루기 쉬워, 위 순서를 반복 실험하기에도 편합니다.
코어 설치와 구독 반영이 아직이라면 설치·기본 설정 문서에서 프로필을 먼저 안정화한 뒤, 본문의 Docker 단계로 넘어오는 편이 디버깅 비용이 적습니다. 클라이언트 패키지는 릴리스 페이지만이 아니라 Clash 공식 다운로드 페이지를 기준으로 삼는 편이 안전합니다. → Clash를 무료로 내려받아 호스트와 컨테이너를 같은 절차로 점검해 보세요.