Clash는 브라우저나 운영체제의 트래픽을 프록시로 전달하더라도 Docker 이미지 다운로드까지 자동으로 처리하지는 않습니다. docker pull을 실행하는 터미널과 이미지를 가져오는 Docker 데몬은 서로 다른 프로세스이기 때문입니다. 따라서 브라우저에서는 인터넷이 잘되는데 Docker Hub에서만 i/o timeout, context deadline exceeded 또는 다운로드 중 멈춤이 발생할 수 있습니다. 이 글에서는 Docker 데몬이 Clash 프록시를 사용하도록 설정하는 방법부터 규칙, TUN 모드, 로그를 통한 확인 절차까지 단계별로 살펴봅니다.
Docker Hub pull이 시간 초과되는 이유
일반적인 터미널 명령은 현재 셸의 HTTP_PROXY, HTTPS_PROXY 환경 변수를 참고할 수 있습니다. 하지만 이미지 다운로드 요청은 대개 Docker CLI가 Docker 데몬에 전달하고, 실제 레지스트리 통신은 데몬이 수행합니다. 셸에 프록시 변수를 설정했어도 데몬에는 전달되지 않을 수 있으므로, 터미널에서 웹사이트가 열리는지만으로 Docker 연결 상태를 판단할 수 없습니다.
또한 Docker Hub pull은 하나의 주소에만 접속하지 않습니다. 레지스트리 API, 인증 서비스, 이미지 레이어를 제공하는 스토리지나 CDN으로 요청이 이어질 수 있습니다. 처음에는 인증이 성공해도 레이어 다운로드 단계에서 멈춘다면, 해당 단계의 연결이 프록시를 타지 않거나 Clash 규칙에서 직접 연결로 분류됐을 가능성이 있습니다.
- 터미널만 프록시 사용: 셸 변수는 설정했지만 Docker 데몬에는 적용되지 않은 경우입니다.
- 일부 도메인만 프록시 사용: 레지스트리 접속은 되지만 인증이나 이미지 레이어 호스트가 다른 경로로 나가는 경우입니다.
- 노드 또는 경로 불안정: 선택한 노드가 Docker Hub 관련 연결을 처리하지 못하거나 전송 중 연결을 끊는 경우입니다.
- 가상 머신 네트워크 문제: Docker Desktop의 데몬이 호스트와 다른 네트워크 환경에서 실행되어 호스트의 프록시 주소에 접근하지 못하는 경우입니다.
docker login 성공 여부와 docker pull 성공 여부는 별개입니다. 로그인이 되더라도 이미지 레이어를 내려받는 도중 타임아웃이 날 수 있으므로, 실패한 단계와 실제 요청 호스트를 함께 확인하세요.먼저 Clash 프록시와 연결 상태 확인하기
Clash 또는 Mihomo가 실행 중인지 확인하고, 현재 선택한 프록시 노드가 정상인지 점검합니다. 로컬 HTTP 혼합 포트는 설치 방식과 설정에 따라 다를 수 있습니다. 아래 예제의 7890은 흔히 사용되는 값일 뿐이므로, Clash 대시보드나 설정 파일에서 실제 포트를 확인해 바꿔야 합니다. 혼합 포트가 HTTP 프록시 요청을 지원하는지 확인하고, SOCKS 전용 포트와 혼동하지 않도록 합니다.
curl -I -x http://127.0.0.1:7890 https://registry-1.docker.io/v2/
연결이 정상이라면 응답 코드가 401 Unauthorized로 표시될 수 있습니다. 이는 레지스트리까지 도달했지만 인증이 필요하다는 뜻이며, 네트워크 연결 자체가 성공했다는 유용한 신호입니다. 반대로 연결 거부가 나오면 Clash가 종료됐거나 포트가 잘못됐을 수 있습니다. 이 단계에서 타임아웃이 발생한다면 노드를 바꾸거나 Clash 연결 로그에서 해당 요청이 어떻게 처리되는지 확인하세요.
GUI 클라이언트를 사용하는 경우 연결 로그에서 registry-1.docker.io, auth.docker.io처럼 Docker Hub와 관련된 호스트를 검색합니다. 요청이 표시되면 매칭된 규칙과 최종 프록시 그룹을 살펴봅니다. 연결 로그에 요청이 전혀 없다면 Docker 데몬이 로컬 Clash 포트에 도달하지 못했거나, 데몬이 별도의 네트워크 환경에서 동작할 가능성이 있습니다.
Docker 데몬에 프록시 설정 적용하기
Linux에서 systemd로 Docker를 실행한다면 서비스에 프록시 환경 변수를 지정할 수 있습니다. 먼저 Clash의 로컬 프록시 포트를 확인한 다음 Docker 서비스의 드롭인 설정을 만듭니다. 아래 주소는 같은 Linux 호스트에서 Docker 데몬과 Clash가 실행되는 경우의 예시입니다.
sudo systemctl edit docker
편집기가 열리면 다음 내용을 입력하고 저장합니다. 실제 포트가 다르다면 두 변수의 주소를 모두 수정하세요.
[Service] Environment="HTTP_PROXY=http://127.0.0.1:7890" Environment="HTTPS_PROXY=http://127.0.0.1:7890" Environment="NO_PROXY=localhost,127.0.0.1,::1"
설정을 저장한 후 systemd 설정을 다시 읽고 Docker 서비스를 재시작합니다. 서비스 재시작은 실행 중인 컨테이너에 영향을 줄 수 있으므로 운영 환경에서는 작업 시간을 고려하세요.
sudo systemctl daemon-reload sudo systemctl restart docker sudo systemctl show --property=Environment docker docker info
출력에서 프록시 환경 변수가 설정됐는지 확인합니다. Docker 버전과 출력 형식에 따라 docker info에 프록시 항목이 표시될 수 있습니다. 프록시가 적용됐는데도 실패한다면 Docker 서비스 로그를 확인해 데몬이 실제로 연결을 시도하는지 살펴보세요.
sudo journalctl -u docker --since "10 minutes ago" --no-pager
~/.docker/config.json의 proxies 설정은 컨테이너나 빌드 단계에 프록시 환경 변수를 전달하는 용도일 수 있습니다. 이것만으로 Docker 데몬의 레지스트리 연결이 프록시를 사용한다고 단정하지 마세요. 이미지 pull 자체가 실패한다면 데몬 설정을 확인해야 합니다.
Docker Desktop과 Clash를 함께 사용하는 경우
Windows와 macOS의 Docker Desktop은 데몬을 호스트와 분리된 가상화 환경에서 실행합니다. 이때 127.0.0.1은 해당 데몬 환경 자체를 가리킬 수 있어, 호스트에서 실행 중인 Clash를 가리키지 않을 수 있습니다. 호스트의 Clash 포트를 그대로 지정했는데 연결이 되지 않는다면 이 차이를 우선 확인하세요.
Docker Desktop 설정에서 프록시 관련 항목을 찾아 수동 프록시를 지정하거나, 사용 중인 버전에서 지원하는 시스템 프록시 연동을 활성화합니다. 메뉴 이름과 설정 위치는 버전에 따라 다를 수 있으므로 현재 설치된 Docker Desktop의 설정 화면을 기준으로 확인하세요. Clash의 로컬 포트가 Docker Desktop에서 접근 가능한 주소에 바인딩되어 있는지도 중요합니다. 무작정 0.0.0.0으로 열면 같은 네트워크의 다른 장치가 프록시에 접근할 수 있으므로, 방화벽과 접근 범위를 먼저 고려해야 합니다.
Docker Desktop 설정을 바꾼 뒤에는 앱에서 설정 적용 또는 재시작을 완료한 다음 테스트합니다. 데몬이 실행되는 가상 네트워크에서 호스트 주소에 접근할 수 없는 경우에는 포트가 올바르더라도 실패합니다. 반대로 호스트 브라우저에서만 프록시가 잘되는 상황은 Docker Desktop의 데몬 연결을 검증하지 못합니다.
Clash 규칙과 TUN 모드 점검하기
Clash 규칙이 Docker Hub 요청을 DIRECT로 보내고 있다면, 시스템 프록시를 설정해도 예상과 다른 결과가 생길 수 있습니다. 규칙 모드에서 연결 로그를 열어 Docker 관련 요청에 어떤 규칙이 적용됐는지 확인합니다. 프록시로 처리해야 하는 요청이 직접 연결로 표시된다면, 사용자 규칙을 기본 최종 규칙보다 앞에 배치하는 방법을 검토하세요.
rules: - DOMAIN-SUFFIX,docker.io,Proxy - DOMAIN-SUFFIX,docker.com,Proxy - MATCH,手動選択
Proxy와 마지막 규칙의 그룹 이름은 예시입니다. 실제 설정에 존재하는 프록시 그룹 이름으로 교체해야 하며, 규칙은 첫 번째로 일치하는 항목이 적용되므로 Docker 관련 규칙을 MATCH보다 앞에 두어야 합니다. 배포된 설정이 구독이나 규칙 제공자에 의해 관리된다면 원본을 직접 수정하기보다 클라이언트의 규칙 추가 기능 또는 설정 오버라이드를 사용하세요.
타임아웃이 이미지 레이어 다운로드에서만 발생하면 로그에 표시되는 실제 호스트도 확인합니다. Docker Hub는 레이어를 별도의 스토리지나 CDN에서 전달할 수 있어, docker.io 규칙만으로 모든 다운로드 호스트가 자동으로 매칭된다고 보장할 수 없습니다. 로그에서 실패한 도메인을 확인한 뒤 필요한 경우에만 해당 도메인을 추가하고, 광범위한 도메인 규칙을 무분별하게 넣지 마세요.
TUN 모드는 애플리케이션이 프록시 환경 변수를 지원하지 않거나 데몬 트래픽을 시스템 수준에서 처리해야 할 때 도움이 될 수 있습니다. 다만 TUN을 켜도 Docker 데몬의 네트워크 네임스페이스, Docker Desktop의 가상 네트워크, 라우팅 규칙에 따라 연결이 달라질 수 있습니다. TUN을 활성화한 뒤에는 Clash 로그에서 요청 유입 여부와 최종 규칙을 다시 확인하고, 시스템 프록시 방식과 동시에 적용했을 때 문제가 복잡해지지 않는지 점검하세요.
pull 명령과 오류별 진단 방법
설정을 바꾼 뒤에는 작은 공개 이미지를 지정해 테스트하고, 실패 단계와 오류 메시지를 기록합니다. 태그를 생략하면 기본 태그가 사용되므로 재현 가능한 테스트를 위해 명시적인 태그를 적는 것이 좋습니다.
docker pull hello-world:latest
| 증상 | 우선 확인할 항목 | 다음 조치 |
|---|---|---|
connect: connection refused | 프록시 포트, Clash 실행 상태, 데몬에서 접근 가능한 주소 | 실제 혼합 포트를 확인하고 Docker Desktop에서는 호스트 주소 접근 여부를 점검합니다. |
i/o timeout 또는 context deadline exceeded | 데몬 프록시, Clash 연결 로그, 선택 노드 | 로그의 목적지와 매칭 규칙을 확인하고 다른 노드로 재시험합니다. |
401 Unauthorized | 레지스트리 인증 또는 로그인 상태 | 네트워크 연결은 된 것일 수 있으므로 계정 권한과 인증 정보를 확인합니다. |
| 로그인 후 레이어 다운로드만 실패 | 레이어 호스트의 규칙, CDN 연결, 전송 중 연결 종료 | Clash 로그에서 실패한 호스트를 확인하고 노드와 규칙을 각각 분리해 시험합니다. |
x509 또는 인증서 오류 | TLS 검사, 잘못된 시스템 시간, 사용자 지정 인증서 | 인증서 검증을 끄지 말고 신뢰 체인과 시스템 시각을 점검합니다. |
원인을 빠르게 좁히려면 한 번에 하나만 바꾸는 것이 좋습니다. 먼저 로컬 Clash 포트를 통한 curl 요청을 확인하고, 다음으로 Docker 데몬의 프록시 변수를 검증합니다. 그 후 동일한 pull을 다시 실행하면서 연결 로그와 Docker 로그를 비교합니다. 노드를 바꿔 성공한다면 데몬 설정은 유지하고 노드 품질이나 해당 경로의 연결 안정성을 조사할 수 있습니다.
자주 묻는 질문
셸에서 HTTPS_PROXY를 설정했는데 왜 docker pull은 실패하나요?
docker pull의 네트워크 요청은 CLI가 아니라 Docker 데몬이 수행할 수 있습니다. 현재 셸의 환경 변수만 바꾸면 데몬에 설정이 전달되지 않을 수 있습니다. Linux에서는 Docker systemd 서비스 설정을, Docker Desktop에서는 앱의 프록시 설정을 확인하세요.
Docker Hub 규칙에 docker.io만 추가하면 충분한가요?
항상 그렇지는 않습니다. 인증 서비스와 이미지 레이어 전달 호스트가 별도로 나타날 수 있습니다. Clash 연결 로그에서 실제 요청 도메인과 매칭된 규칙을 확인하고, 실패한 호스트에 필요한 범위로 규칙을 추가하세요.
TUN 모드를 켜면 Docker pull 문제가 무조건 해결되나요?
아닙니다. TUN은 시스템 트래픽을 처리하는 선택지이지만, Docker Desktop의 가상 네트워크나 데몬 라우팅까지 자동으로 해결해 주지는 않습니다. 프록시 환경 변수 방식과 비교해 한 번에 하나씩 시험하고 로그로 결과를 확인하세요.
프록시 주소를 localhost로 지정했는데 연결이 거부됩니다. 왜 그런가요?
Docker 데몬이 호스트와 분리된 환경에서 실행되면 데몬이 보는 127.0.0.1은 호스트의 Clash가 아닐 수 있습니다. Docker Desktop에서 접근 가능한 호스트 주소와 프록시 설정 방식을 확인하고, 불필요하게 로컬 포트를 외부에 공개하지 않도록 주의하세요.
Docker Hub pull 시간 초과는 대개 Clash 노드 자체보다 Docker 데몬이 프록시를 사용하고 있는지, 요청이 올바른 규칙을 통과하는지에서 원인을 찾을 수 있습니다. 로컬 프록시 연결, 데몬 설정, 매칭 로그, 실제 pull 결과를 순서대로 확인하면 변경 범위를 좁힐 수 있습니다. 먼저 최소 설정으로 연결을 검증한 뒤 필요한 규칙이나 TUN 설정을 더해 안정적으로 다운로드되는 구성을 완성하세요.