Clash에서 Docker Hub 이미지 pull이 시간 초과될 때 해결법

Docker Hub pull 시간 초과가 Clash 문제처럼 보이는 이유

브라우저는 잘 열리는데 docker pull만 멈춘다면, 먼저 Docker 명령을 실행한 터미널과 이미지를 실제로 내려받는 Docker 데몬을 구분해야 합니다. 터미널의 HTTP_PROXY 환경 변수는 일부 명령줄 프로그램에 적용되지만, 이미지 요청을 처리하는 데몬까지 자동으로 전달되지는 않습니다. Docker Desktop은 별도 가상 환경에서 데몬을 실행하므로 호스트의 프록시와 네트워크 경로가 다를 수도 있습니다. 따라서 Clash에서 노드를 바꾸기 전에, 요청이 실제로 어느 프로세스에서 나가고 있는지 확인하는 편이 빠릅니다.

Docker Hub 이미지 pull 과정은 하나의 호스트에만 연결되지 않습니다. 인증 토큰 요청, 레지스트리 매니페스트 조회, 이미지 레이어 다운로드가 서로 다른 호스트나 CDN 경로를 거칠 수 있습니다. 예를 들어 로그에 auth.docker.io, registry-1.docker.io 또는 레이어 다운로드 주소가 차례로 보일 수 있습니다. 앞부분은 성공했지만 큰 레이어를 받는 단계에서 멈추면, 전체 pull이 시간 초과된 것처럼 나타납니다. Clash 규칙이 이 요청들을 서로 다른 정책으로 보내거나 Docker 데몬이 프록시를 전혀 사용하지 않는 경우도 같은 증상을 만듭니다.

실패 단계와 실행 환경부터 확인하기

같은 “시간 초과” 메시지라도 발생 지점은 다를 수 있습니다. 매니페스트를 읽기 전에 멈추는지, 인증 단계에서 거부되는지, 특정 레이어 다운로드 중 진행률이 정지하는지 살펴보세요. 다음 명령은 재현 결과와 오류 문맥을 확인하는 출발점입니다.

docker pull alpine:latest
docker info
docker context show

운영 이미지로 검사할 때는 최신 태그보다 팀에서 실제 사용하는 이미지와 태그를 지정하는 것이 좋습니다. 최신 태그는 이미지가 바뀔 수 있어 이전 실패와 결과를 비교하기 어렵습니다. docker info로 데몬이 응답하는지 확인하고, docker context show로 로컬 데몬이 아닌 원격 Docker context를 선택한 상태는 아닌지 확인하세요. 원격 데몬을 쓰고 있다면 로컬 Clash의 설정을 바꿔도 원격 서버의 다운로드 경로에는 영향이 없습니다.

Docker Desktop에서는 설정 화면의 프록시 항목과 실행 중인 데몬 상태를 확인합니다. Linux Docker Engine은 셸이 아니라 서비스로 동작하므로, 터미널에서 프록시 변수를 출력하는 것만으로 데몬 설정이 확인되지는 않습니다. Windows나 macOS에서 WSL, 가상 머신, 원격 빌드 환경을 함께 사용한다면 어느 환경의 데몬이 요청을 보내는지도 먼저 적어 두세요. 환경이 불분명하면 설정을 여러 곳에 동시에 바꾸기보다 한 번에 한 계층씩 검증합니다.

Clash 모드와 규칙 매칭 점검

Clash가 실행 중이고 브라우저 트래픽이 프록시를 통과한다고 해서 Docker 연결도 같은 경로를 탄다는 뜻은 아닙니다. 규칙 모드에서는 요청의 호스트나 IP에 따라 정책이 정해지고, 글로벌 모드에서는 대부분의 연결이 선택한 프록시 그룹으로 전달됩니다. 우선 Clash의 연결 목록을 열어 pull을 다시 시도하고, 새로 생긴 연결이 있는지 확인하세요. 아무 연결도 없다면 Docker 데몬이 Clash를 경유하지 않는 경로일 가능성이 큽니다. 연결이 보인다면 각 항목의 규칙 결과와 선택된 노드를 확인합니다.

로그에 Docker Hub 관련 연결이 보이는데 DIRECT로 표시된다면 규칙 우선순위와 매칭 대상을 점검합니다. 포괄적인 규칙을 앞에 무작정 추가하기보다는 실제 로그에서 확인한 호스트를 기준으로 좁게 보완하세요. 프록시 정책과 직접 연결이 섞여 있으면 인증은 통과해도 레이어를 받는 연결만 실패할 수 있습니다. 다만 호스트가 로그에 보인다는 이유만으로 광범위한 도메인 접미 규칙을 추가하면, 관계없는 서비스까지 같은 노드로 보내게 될 수 있습니다.

로그가 기록되지 않거나 데몬 트래픽이 규칙 모드의 프록시로 들어오지 않는다면, TUN 모드가 필요한 환경인지 검토할 수 있습니다. TUN은 애플리케이션이 시스템 프록시를 따르지 않을 때 네트워크 트래픽을 처리하는 방법 중 하나지만, 관리자 권한과 가상 네트워크 어댑터, 다른 VPN과의 충돌이 원인이 될 수도 있습니다. 이미 다른 터널을 사용 중이라면 테스트 동안 중복 연결을 피하고, TUN을 켠 뒤 Clash 로그에 Docker 연결이 나타나는지 다시 확인하세요. 글로벌 모드에서 잠깐 비교해 증상이 바뀌는지 보는 것도 규칙 문제와 프록시 경로 문제를 나누는 데 도움이 됩니다.

Docker 데몬이 Clash 프록시를 사용하도록 설정하기

로그에서 Docker 요청이 Clash에 도달하지 않는다면 데몬 측 프록시를 확인합니다. 사용할 주소는 Docker 데몬이 실행되는 환경에서 실제로 접근할 수 있어야 합니다. 같은 Linux 호스트에서 데몬과 Clash가 실행 중이면 로컬 주소를 쓸 수 있지만, Docker Desktop의 가상 환경이나 별도 서버에서는 호스트의 127.0.0.1이 Clash가 실행 중인 컴퓨터를 가리키지 않을 수 있습니다. 데몬에서 접근 가능한 호스트 주소와 Clash의 HTTP 또는 mixed 포트를 확인한 다음 적용하세요.

Docker Desktop은 버전에 따라 설정 화면의 프록시 관리 기능과 메뉴 이름이 다를 수 있으므로, 해당 버전에서 제공하는 네트워크·프록시 설정을 우선 사용합니다. Linux Engine에서는 지원되는 데몬 구성 또는 서비스 환경 변수로 프록시를 지정할 수 있습니다. 시스템 서비스에 환경 변수를 적용하는 방식을 선택했다면 설정 파일을 저장한 뒤 systemd 설정을 다시 읽고 Docker 서비스를 재시작해야 변경이 적용됩니다. 사용 중인 Docker 버전의 공식 문서에서 설정 키와 적용 위치를 확인하고, 임의로 여러 설정 방식을 섞지 마세요.

다음은 Linux 서비스에 프록시 환경 변수를 전달하는 형식의 예입니다. 주소와 포트는 실제 Clash 설정에 맞게 바꾸고, 프록시를 거치지 않아야 하는 사내 레지스트리나 로컬 주소가 있다면 예외 목록도 환경에 맞게 지정합니다.

[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,.internal"

이 예시를 서비스 설정에 적용한 뒤에는 데몬을 재시작하고 docker info 또는 데몬 로그에서 설정이 반영됐는지 확인합니다. 설정 파일을 바꿨는데도 새 요청이 이전 경로를 쓰는 경우, Docker Desktop을 완전히 재시작하거나 서비스 재시작이 실제로 수행됐는지 점검하세요. 프록시 URL에 사용자 이름이나 비밀번호를 넣어야 한다면 설정 파일의 읽기 권한과 자격 증명 노출 위험도 고려해야 합니다.

터미널 프록시 변수와 DNS를 따로 검사하기

docker pull을 실행한 셸에서 프록시 변수를 설정하는 방법은 일부 Docker 명령이나 빌드 단계에 도움이 될 수 있지만, 일반적인 로컬 Engine에서는 이미지 레이어를 받는 데몬 설정과 별개입니다. 셸에서 HTTP_PROXY가 설정됐다는 사실만으로 데몬도 같은 프록시를 사용한다고 판단하지 마세요. 반대로 컨테이너 안에서 실행되는 패키지 설치가 실패한다면, 이는 이미지 pull과는 다른 네트워크 단계일 수 있습니다. 먼저 이미지 자체를 내려받는 요청과 컨테이너 빌드·실행 중의 요청을 분리해 재현합니다.

DNS도 단계적으로 확인합니다. 운영체제나 Docker Desktop이 사용하는 DNS 경로가 Clash의 DNS 설정과 다르면, 도메인 이름은 해석되더라도 기대와 다른 주소로 연결될 수 있습니다. Clash 로그에서 도메인 기반 규칙이 매칭되는지 확인하고, 이름 해석 실패와 TCP 연결 시간 초과를 구별하세요. Docker 데몬 설정이나 네트워크 환경을 바꾼 뒤에는 같은 이미지로 다시 시도해 결과를 비교해야 합니다. DNS 캐시가 남아 있을 수 있으므로, 단순히 규칙을 저장한 직후의 한 번의 시도만으로 결론을 내리지 않는 편이 좋습니다.

docker pull로 수정 결과를 검증하고 안전하게 되돌리기

설정을 바꾼 뒤에는 같은 이미지와 태그로 재시도하고, Clash 연결 로그와 Docker 데몬 로그를 동시에 비교합니다. 요청이 의도한 정책 그룹으로 들어오는지, 인증과 매니페스트 조회가 지나가는지, 큰 레이어의 다운로드가 끝까지 이어지는지 확인하세요. 한 번 성공했다고 바로 규칙을 넓히기보다는 여러 차례 반복해 재현성을 확인합니다. 문제가 사라지면 마지막으로 바꾼 설정만 기록해 두어 다음 프로필 갱신이나 Docker 업데이트 뒤에도 원인을 추적할 수 있게 합니다.

반대로 변경 후 연결이 더 나빠지면 새 규칙이나 프록시 설정을 하나씩 되돌립니다. 특히 모든 트래픽을 프록시로 보내는 임시 테스트를 상시 설정으로 남기지 말고, 업무망이나 사내 레지스트리 정책을 확인하세요. 노드 변경, DNS 변경, 데몬 프록시 추가를 한꺼번에 하면 어떤 조치가 효과가 있었는지 알기 어렵습니다. 테스트는 한 항목씩 진행하고, 서비스 재시작이나 TUN 변경처럼 다른 애플리케이션에 영향을 줄 수 있는 조치는 작업 전 현재 상태를 기록해 두는 것이 안전합니다.

자주 묻는 질문

브라우저에서 Docker Hub가 열리는데 왜 pull은 실패하나요? 브라우저와 Docker 데몬은 프록시 설정과 네트워크 경로를 공유하지 않을 수 있습니다. 특히 셸의 프록시 변수는 데몬에 자동 적용되지 않으므로, Clash 로그와 데몬 프록시 설정을 따로 확인하세요.

Clash 글로벌 모드에서는 되는데 규칙 모드에서만 실패합니다. 이유가 무엇인가요? Docker 인증, 레지스트리, 레이어 다운로드가 서로 다른 호스트를 사용할 수 있습니다. 일부 연결만 다른 정책이나 직접 연결로 빠지는지 로그에서 비교하고, 관측한 호스트를 기준으로 규칙을 보완하세요.

TUN을 켜면 항상 해결되나요? 그렇지 않습니다. TUN은 시스템 프록시를 따르지 않는 트래픽을 처리하는 선택지이지만, 데몬이 실행되는 가상 환경이나 주소 도달성, 권한, 다른 VPN과의 충돌에 따라 결과가 달라집니다. 연결 로그에 요청이 나타나는지부터 확인해야 합니다.

노드를 바꾸는 것만으로 충분한가요? 노드 품질이 원인일 수 있지만, 데몬이 Clash를 거치지 않거나 규칙이 잘못 매칭되면 노드 교체만으로는 해결되지 않습니다. 오래된 클라이언트는 TUN 및 정책 관리가 불편할 수 있고, 터미널 프록시 변수만 설정하는 방식도 데몬에는 적용되지 않을 수 있습니다. Clash V.CORE에서는 노드 상태와 프록시 모드, 규칙 경로를 한 흐름으로 점검하기 쉬우므로 Docker Hub pull 문제를 반복해서 추적해야 한다면 다운로드해 환경에 맞게 확인해 보세요.