📖 튜토리얼 2026년 4월 20일 ⏱ 약 18분 분량

2026 Docker Desktop이 Windows 11에서 Clash를 안 탈 때: HTTP/HTTPS 프록시·daemon.json·DNS로 이미지 풀·컨테이너 빌드 맞추기

같은 PC에서 Windows 11에 Clash(또는 Clash Verge 등)를 켜 두었는데도 Docker Desktop만 docker pull이나 docker compose 빌드가 실패하거나, Dockerfile 안 apt·apk가 프록시를 전혀 안 타는 경우가 있습니다. WSL2 터미널에서 Git·npm을 맞춘 경험이 있어도 Docker는 또 다른 네트워크 스택을 쓰기 때문에 증상이 겹치지 않을 수 있습니다. 이 글은 「개념 소개」가 아니라 Clash 포트 확인 → Docker Desktop UI 프록시 → Docker 엔진 daemon.json → 빌드·Compose 시 HTTP_PROXY → DNS·레지스트리 이름 해석 순으로, 호스트와 엔진이 같은 출구를 보도록 정렬하는 실무 순서입니다. WSL2와의 차이는 WSL2·Git·npm 프록시 글과 짝을 이루도록 구성했습니다.

① 왜 브라우저는 되는데 Docker만 실패할까

Docker Desktop for Windows는 사용자 앱이 아니라 백그라운드 Linux VM(또는 WSL2 백엔드)에 Docker 엔진을 올립니다. 그래서 Windows에서 시스템 프록시를 켜도, 그 신호가 엔진이 이미지를 받는 경로까지 그대로 전달되지 않는 경우가 많습니다. Chrome이나 Edge는 OS 프록시를 읽지만, docker CLI가 끌어오는 레이어는 엔진 쪽 설정·환경에 더 가깝습니다.

또 Dockerfile 빌드 단계는 RUN apt-get update 같은 명령이 빌드 컨테이너 안에서 실행되므로, 호스트의 HTTP_PROXY가 자동으로 들어가지 않으면 「레지스트리는 되는데 빌드 안 패키지 매니저만 직접 나간다」는 패턴이 나옵니다. 먼저 「풀(pull) 실패인지 / 빌드 중 apt만 실패인지」를 가르는 것이 시간을 아낍니다.

Clash를 처음 설치했다면 Windows 11 Clash Verge 첫 설정에서 시스템 프록시·TUN 차이를 먼저 맞춰 두는 편이 이후 포트 번호를 고정하기 쉽습니다.

② 1단계: Windows에서 Clash가 열어 둔 HTTP(S) 포트 확인

대부분의 프로필은 mixed-port 또는 port·socks-port 조합으로 로컬 프록시를 띄웁니다. 클라이언트 화면이나 YAML에서 HTTP·HTTPS에 해당하는 숫자를 메모합니다. 예시로 7890이 자주 보이지만, 본인 환경의 값을 써야 합니다.

엔진 VM이 호스트의 프록시 포트로 TCP 연결을 열 때, Clash에서 Allow LAN(로컬망 허용)이 꺼져 있으면 루프백이 아닌 주소에서 오는 연결이 거절될 수 있습니다. 휴대폰과 PC를 같은 Wi‑Fi로 묶는 시나리오와 맥락이 비슷하므로 LAN·방화벽 글도 함께 참고하면 됩니다.

③ 2단계: Docker Desktop UI에서 수동 프록시

Docker Desktop 설정에 Resources → Proxies(또는 버전에 따라 Manual proxy configuration) 항목이 있습니다. 여기에 Windows 호스트의 Clash 프록시를 가리키는 URL을 넣으면, 데스크톱이 엔진에 넘겨 주는 경로가 정리됩니다.

호스트 주소로는 host.docker.internal을 쓰는 방식이 널리 쓰입니다. 예를 들어 HTTP 프록시가 7890이면 다음과 같은 형태입니다(포트는 본인 값으로 바꿉니다).

http://host.docker.internal:7890

host.docker.internal은 Windows 쪽 Docker Desktop이 호스트 IP로 해석해 주는 특수 이름입니다. 방화벽이나 보안 소프트웨어가 로컬 프록시 포트를 가로막는 경우도 있으니, 막히면 Windows Defender 방화벽 규칙을 한 번 점검합니다.

④ 3단계: Docker 엔진 `daemon.json`에 프록시(끌어오기·데몬 트래픽)

UI만으로 부족하거나, 문서·팀 표준에 따라 엔진 JSON을 직접 쓰는 경우가 있습니다. Docker Desktop에서는 Settings → Docker Engine 편집 화면에 넣는 JSON이 곧 엔진 설정과 합쳐지므로, 아래 proxies 블록을 그대로 추가하는 방식이 가장 흔합니다. (호스트에 .docker\daemon.json 파일을 두는 배포 방식을 쓰는 팀도 있으나, 데스크톱 사용자는 UI 편집기를 우선하면 됩니다.) Docker 문서에 따라 default 프록시에 httpProxy·httpsProxy·noProxy를 지정합니다.

{
  "proxies": {
    "default": {
      "httpProxy": "http://host.docker.internal:7890",
      "httpsProxy": "http://host.docker.internal:7890",
      "noProxy": "localhost,127.0.0.1,::1"
    }
  }
}

위 숫자 7890은 예시입니다. 실제 Clash HTTP·HTTPS 프록시 포트와 일치해야 합니다. JSON을 수정한 뒤에는 Docker Desktop을 재시작하거나 엔진을 다시 불러오는 절차가 필요할 수 있습니다. 이미 다른 키(registry-mirrors 등)가 있다면 같은 파일에 병합하고, 쉼표·중괄호 오류가 없는지 확인합니다.

이 설정은 데몬이 이미지 레이어를 받을 때와 같이 엔진이 직접 내는 아웃바운드에 영향을 줍니다. 그래도 컨테이너 빌드의 각 RUN 줄이 자동으로 같은 프록시를 쓰는 것은 아니라는 점이 다음 절로 이어집니다.

⑤ 4단계: 빌드 시 `apt`·패키지 매니저에 프록시 주기

Dockerfile에서 apt-get·apk·yum 등이 실패하면, 레이어 캐시 문제가 아니라 빌드 컨텍스트의 네트워크 문제일 가능성이 큽니다. 이때는 빌드 인자로 HTTP_PROXY·HTTPS_PROXY를 넘기고, Dockerfile에서 ARG로 받아 ENV에 반영하는 패턴이 흔합니다.

# Example (adjust proxy URL to your host:port)
docker build \
  --build-arg HTTP_PROXY=http://host.docker.internal:7890 \
  --build-arg HTTPS_PROXY=http://host.docker.internal:7890 \
  -t myimage .

docker compose를 쓰면 build.args에 같은 값을 넣거나, .env에 프로시 변수를 정의해 빌드 단계와 일치시킬 수 있습니다. 팀마다 host.docker.internal 대신 고정 IPv4를 쓰기도 하는데, 그 경우에도 호스트의 Clash 포트를 가리키기만 하면 됩니다.

BuildKit을 쓰는 최신 빌드에서는 캐시·네트워크 동작이 조금 달라질 수 있으므로, 한 번 실패하면 DOCKER_BUILDKIT=0으로 비교 실험해 보는 것도 진단에 도움이 됩니다. 다만 장기적으로는 프록시 URL을 정확히 넣는 쪽이 맞습니다.

⑥ 5단계: DNS 불일치·레지스트리 이름 해석·Clash DNS

docker pull이 타임아웃이 아니라 「이름을 모르겠다」는 식이면 DNS 쪽입니다. Docker Desktop의 Docker Engine 설정 JSON에 "dns": ["8.8.8.8","1.1.1.1"] 같은 항목을 추가해 엔진이 쓰는 해석기를 고정할 수 있습니다. 다만 회사망에서는 내부 DNS를 깨면 안 되므로 정책을 먼저 확인합니다.

Clash에서 fake-ip·DoH·코어의 dns 블록을 쓰면, 호스트 브라우저와 엔진 VM이 보는 응답이 달라질 수 있습니다. 그래서 「브라우저는 되는데 pull만 실패」가 DNS·경로 혼합으로 이어지기도 합니다. 이때는 TUN·DNS 심화 글의 체크 순서를 참고해, 규칙 로그·해석 경로를 한 번에 맞추는 편이 빠릅니다.

특정 레지스트리(docker.io, ghcr.io 등)만 프록시 그룹으로 보내고 싶다면 Clash 규칙에서도 정리할 수 있습니다. 이는 GitHub·개발 트래픽 분류 글과 같은 맥락에서, 레지스트리 호스트를 DOMAIN-SUFFIX로 묶는 패턴으로 확장합니다.

⑦ 6단계: 증상별로 빠르게 좁히기

아래처럼 나누면 원인을 빠르게 줄일 수 있습니다.

docker pull만 실패: UI 프록시·daemon.json proxies·DNS·Clash 규칙 순서
빌드 중 apt만 실패: --build-arg HTTP_PROXY·Dockerfile ARG/ENV·compose build 설정
간헐적 끊김: 노드·TLS·MTU보다 먼저 프록시가 빠졌는지 확인
사내 프록시와 Clash가 동시에 있을 때: PAC·WPAD·보안 에이전트가 우선하는지 IT 정책 확인

원격 저장소와 컨테이너 빌드를 안정적으로 쓰려면, 「호스트 Clash 포트」를 숫자로 고정하고, Docker Desktop·daemon.json·빌드 인자에 같은 URL을 반복해 넣는 것이 가장 재현성이 높습니다.

⑧ 정리: 같은 PC라도 Docker는 “다른 네트워크”다

Windows 11에서 Clash를 켠 상태로 Docker Desktop을 쓸 때, 핵심은 브라우저와 같은 전제를 두지 말 것입니다. HTTP·HTTPS 프록시 포트를 확인하고, host.docker.internal 또는 팀이 정한 호스트 주소로 엔진·빌드·docker compose를 한 줄에 맞춘 뒤, DNS와 fake-ip·레지스트리 규칙을 점검하면 이미지 풀과 컨테이너 빌드가 동시에 안정화되는 경우가 많습니다.

클라이언트 설치와 버전 안내는 릴리스 페이지만 쫓기보다 Clash 입문 튜토리얼과 사이트 다운로드 페이지를 함께 보는 편이 덜 헷갈립니다. 규칙형 Clash는 앱별로 출구를 나눌 수 있어, 개발용 레지스트리와 일반 웹을 동시에 다루기에도 유리합니다. 다른 유형의 VPN과 비교할 때는 Clash와 VPN의 차이도 참고하면 선택 기준이 분명해집니다. → Clash를 무료로 내려받고, Windows 11에서 Docker와 같은 프록시 정책을 맞춰 보세요.