증상 확인: Docker Hub 이미지만 내려받기 실패하는 이유
Docker Hub 이미지 다운로드 오류는 브라우저에서 웹 페이지가 열리는지와 별개로 발생할 수 있습니다. docker pull nginx를 실행했을 때 명령이 계속 대기하거나, context deadline exceeded, Client.Timeout exceeded while awaiting headers, EOF, TLS handshake timeout 같은 메시지가 나타나는 것이 대표적인 패턴입니다. 어떤 경우에는 이미지 목록 조회는 성공하지만 실제 레이어를 내려받는 단계에서 멈추고, 다른 경우에는 로그인 토큰을 받는 과정부터 unauthorized 또는 연결 재설정 오류가 발생합니다.
Docker Desktop의 브라우저나 일반 앱은 시스템 프록시 설정을 따르지만, Docker 데몬은 별도의 네트워크 네임스페이스와 백그라운드 프로세스로 실행됩니다. 따라서 Clash의 시스템 프록시를 켰다는 이유만으로 Docker Hub 트래픽까지 자동으로 처리된다고 단정할 수 없습니다. Linux의 dockerd, Docker Desktop의 Linux VM, WSL2 백엔드가 실제 연결 주체가 될 수 있으므로 먼저 어느 환경에서 데몬이 동작하는지 구분해야 합니다.
이 글에서는 Clash TUN 투명 프록시를 중심으로 Docker Hub의 DNS 조회, 인증 토큰, 레지스트리 API, 이미지 레이어 CDN이 어떤 경로를 거치는지 확인합니다. 특정 네트워크의 제한을 무단으로 우회하라는 뜻이 아니라, 본인이 관리하거나 사용 권한을 가진 환경에서 합법적인 네트워크 정책과 서비스 약관을 지키며 연결 경로를 진단하는 절차입니다.
Docker Hub 연결 구조와 Clash TUN이 처리하는 방식
Docker Hub는 하나의 주소만 사용하는 서비스가 아닙니다. Docker CLI가 이미지 이름을 해석하면 먼저 레지스트리 API에 연결하고, 인증이 필요한 경우 토큰 서비스에서 임시 자격 증명을 받은 뒤, 매니페스트와 각 레이어를 요청합니다. 레이어 파일은 레지스트리 본체가 아니라 별도의 저장소나 CDN 주소로 전달될 수 있습니다. 그래서 registry-1.docker.io만 프록시로 보내고 토큰 또는 레이어 호스트를 누락하면 「로그인은 되지만 pull만 실패」하는 현상이 생깁니다.
일반적인 HTTP 프록시는 애플리케이션이 프록시 환경 변수를 읽어야 작동합니다. 예를 들어 셸에서 HTTP_PROXY를 지정해도 해당 변수는 현재 셸과 그 자식 프로세스에만 전달되며, 이미 실행 중인 시스템 서비스인 dockerd에는 적용되지 않을 수 있습니다. 반면 Clash TUN은 가상 네트워크 인터페이스를 만들고 라우팅된 IP 패킷을 가로채므로, 애플리케이션이 프록시를 지원하지 않아도 데몬 트래픽을 정책에 따라 분류할 수 있습니다.
다만 TUN이 모든 문제를 자동으로 해결하는 것은 아닙니다. DNS가 로컬에서 먼저 해석되면 잘못된 주소가 캐시될 수 있고, Docker Desktop이 별도 VM 안에서 실행되면 호스트의 인터페이스와 VM의 라우팅이 다를 수 있습니다. 또한 TUN과 Docker 브리지 네트워크가 같은 사설 대역을 사용하면 충돌이 발생할 수 있습니다. 따라서 DNS 모드, TUN 스택, 자동 라우트, 방화벽 권한, Docker 실행 위치를 함께 살펴봐야 합니다.
먼저 확인할 실행 환경
- Linux 네이티브 Docker:
dockerd가 호스트에서 실행되므로 Clash TUN의 라우팅과 방화벽 규칙을 직접 확인합니다. - Docker Desktop: Docker 엔진이 Linux VM 안에서 동작할 수 있습니다. 호스트에서
docker pull을 실행해도 실제 외부 연결은 VM 프로세스가 담당할 수 있습니다. - WSL2: Windows와 WSL2 사이의 가상 어댑터, DNS 프록시, 자동 생성 resolv.conf가 서로 영향을 줍니다. Windows에서 TUN을 켜도 WSL2의 경로가 예상과 다를 수 있습니다.
- 원격 Docker 컨텍스트:
docker context ls에서 원격 엔진을 사용 중이면 현재 PC의 Clash가 아니라 원격 서버의 네트워크를 고쳐야 합니다.
Clash TUN과 DNS 기본 설정 점검
처음부터 복잡한 규칙을 모두 넣기보다, Clash가 정상적으로 TUN 인터페이스를 만들고 DNS 질의를 일관되게 처리하는지 확인하세요. 사용 중인 코어가 Mihomo 계열이라면 프로필의 구조가 다음과 비슷한지 살펴볼 수 있습니다. 아래 값은 예시이며, 실제 환경의 인터페이스 이름과 DNS 정책에 맞게 조정해야 합니다.
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-filter:
- '*.lan'
- '*.local'
- 'localhost.ptlogin2.qq.com'
nameserver:
- https://dns.cloudflare.com/dns-query
- https://dns.google/dns-query
fallback:
- https://1.1.1.1/dns-query
- https://8.8.8.8/dns-query
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53
fake-ip은 도메인과 연결을 정책 엔진이 일관되게 추적하는 데 도움이 되지만, 모든 환경에서 정답은 아닙니다. Docker 내부 DNS, 사내 도메인, 로컬 레지스트리, VPN이 제공하는 전용 도메인이 있다면 fake-ip-filter에 예외를 추가해야 합니다. 반대로 DNS가 여러 경로로 분산되면 Docker가 얻은 IP와 Clash가 분류한 도메인 정보가 어긋날 수 있으므로, 테스트 중에는 DNS 설정을 자주 바꾸지 말고 변경 후 캐시를 정리하면서 비교하세요.
설정 저장 후에는 Clash 로그에서 TUN 시작 성공 여부를 확인하고, 운영체제에 새 가상 인터페이스가 생성되었는지 봅니다. Linux에서는 ip addr와 ip route, Windows에서는 네트워크 어댑터 목록과 route print를 사용할 수 있습니다. 이어서 다음과 같이 이름 해석과 HTTPS 연결을 따로 검사합니다.
getent hosts registry-1.docker.io
curl -I https://registry-1.docker.io/v2/
curl -I https://auth.docker.io/token
/v2/ 요청에서 401 Unauthorized가 반환되는 것은 반드시 실패가 아닙니다. 레지스트리가 인증을 요구한다는 정상적인 응답일 수 있습니다. 중요한 것은 연결이 즉시 끊기는지, TLS 협상이 완료되는지, 응답 헤더가 도착하는지입니다. curl은 성공하지만 docker pull만 실패한다면 Docker 데몬의 실행 환경이나 프록시·인증서 설정을 별도로 의심해야 합니다.
docker network inspect bridge로 현재 대역을 확인하고, 임의로 네트워크를 삭제하기보다 백업 후 충돌 여부를 먼저 기록하세요.Docker Hub 레지스트리와 레이어 CDN 규칙 작성
규칙 순서는 결과를 좌우합니다. 넓은 GEOIP, IP-CIDR, MATCH 규칙이 Docker 관련 도메인보다 위에 있으면 앞의 규칙에서 이미 결정되어 뒤의 프록시 규칙이 실행되지 않습니다. 따라서 Docker Hub 전용 규칙은 일반 지역 규칙보다 위, 마지막 기본 규칙보다 충분히 위에 배치하는 것이 좋습니다.
초기에는 확인된 도메인만 좁게 등록하세요. docker.io 전체를 무조건 한 그룹으로 보내는 방법은 간단하지만, 조직 내부 레지스트리나 로컬 개발 주소까지 예상하지 못한 경로로 보낼 수 있습니다. 다음은 Docker Hub의 대표적인 요청 축을 나누어 보는 출발점입니다.
| 요청 축 | 예시 호스트 | 점검 포인트 |
|---|---|---|
| 레지스트리 API | registry-1.docker.io |
매니페스트 조회와 이미지 이름 해석 |
| 인증 토큰 | auth.docker.io |
로그인·토큰 발급·401 응답 확인 |
| 웹 및 계정 | hub.docker.com, www.docker.com |
브라우저 로그인과 CLI 인증을 혼동하지 않기 |
| 레이어 저장소 | 로그에 나타난 CDN 또는 저장소 호스트 | 대용량 레이어 다운로드와 TLS 유지 시간 |
proxy-groups:
- name: DOCKER-HUB
type: select
proxies:
- PROXY
- DIRECT
rules:
- DOMAIN,registry-1.docker.io,DOCKER-HUB
- DOMAIN,auth.docker.io,DOCKER-HUB
- DOMAIN-SUFFIX,docker.io,DOCKER-HUB
- DOMAIN-SUFFIX,docker.com,DOCKER-HUB
- MATCH,FINAL
레이어 다운로드가 실패하면 로그에서 실제 요청 호스트를 찾아 한 건씩 추가합니다. 광역 DOMAIN-SUFFIX,amazonaws.com 같은 규칙을 바로 넣는 것은 권장하지 않습니다. 다른 클라우드 API와 패키지 저장소까지 같은 그룹으로 묶여 오탐과 속도 저하가 생길 수 있기 때문입니다. Docker Hub의 CDN 주소가 매번 달라진다면 해당 호스트를 무리하게 영구 등록하기보다, 공식 레지스트리 미러 또는 조직이 관리하는 프라이빗 레지스트리를 검토하는 편이 운영상 더 안정적입니다.
변경 후에는 Clash의 규칙 캐시와 DNS 캐시를 새로고침하고, 작은 이미지로 먼저 재현합니다. 예를 들어 docker pull hello-world가 성공한 다음 실제 업무 이미지로 확대하세요. 이미지가 이미 일부 레이어를 받은 상태라면 결과가 착시처럼 보일 수 있으므로, 처음에는 새로운 태그나 로컬 캐시에 없는 이미지를 선택하는 것이 좋습니다.
Docker 데몬·TLS·라우팅 오류를 단계별로 분석하기
문제 해결은 「노드를 바꾸기」보다 실패 지점을 분리하는 방식이 빠릅니다. 다음 순서로 하나씩 기록하면 Clash 규칙 문제와 Docker 자체 문제를 구분하기 쉽습니다.
- Docker 컨텍스트 확인:
docker context show와docker info로 현재 연결된 엔진, 서버 주소, Docker 버전을 확인합니다. 원격 엔진이라면 로컬 TUN 로그에 요청이 없을 수 있습니다. - DNS 결과 기록:
getent hosts,nslookup또는 운영체제의 DNS 도구로 레지스트리와 인증 호스트가 해석되는 주소를 기록합니다. 서로 다른 DNS 서버가 응답하는 상태에서는 비교가 어렵습니다. - Clash rule hit 확인: 로그에서
registry-1.docker.io,auth.docker.io와 레이어 호스트가 실제로 DOCKER-HUB 그룹에 매칭되는지 확인합니다. 규칙이 보이지 않으면 Docker 트래픽이 TUN에 도달하지 않았을 가능성이 있습니다. - 인증과 다운로드 분리:
docker login은 성공하지만docker pull이 실패하는지, 로그인 전후가 같은지 비교합니다. 인증서 오류라면 토큰 발급과 레이어 다운로드의 오류 메시지가 다르게 나타날 수 있습니다. - 작은 이미지와 큰 이미지 비교: 작은 이미지가 성공하고 큰 레이어에서만 timeout이 발생하면 출구의 대역폭, MTU, 연결 유지 시간 또는 CDN 규칙을 점검합니다.
- 직접 연결과 프록시 연결 비교: 정책이 허용하는 범위에서 같은 시간에 DIRECT와 DOCKER-HUB를 비교합니다. 한쪽만 실패하는지 확인해야 무작정 모든 트래픽을 프록시로 보내는 실수를 피할 수 있습니다.
TLS 오류가 나타난다고 해서 곧바로 Docker 인증서를 수정하면 안 됩니다. 시스템 시간 오류, 중간 TLS 검사 장비, 오래된 CA 저장소, 잘못된 프록시 체인도 같은 메시지를 만들 수 있습니다. Linux에서는 date, CA 패키지, Docker 서비스 로그를 확인하고, Windows·Docker Desktop에서는 Desktop 진단 로그와 WSL2 시간·DNS 상태를 함께 확인하세요. 회사가 승인한 TLS 검사 인증서가 필요한 환경이라면 개인적으로 인증서를 내려받아 Docker 이미지에 복사하지 말고 보안 담당자의 공식 배포 절차를 따르십시오.
또 하나 자주 놓치는 항목은 MTU입니다. TUN, VPN, WSL2, Docker 브리지 터널이 여러 겹이면 작은 HTTPS 요청은 되지만 큰 레이어 전송에서 재전송이 늘어날 수 있습니다. 이때는 네트워크 담당자가 정한 MTU 값을 기준으로 조정하고, 변경 전후에 동일 이미지의 다운로드 시간과 실패 지점을 기록합니다. 무작정 MTU를 낮추면 처리량이 오히려 감소할 수 있으므로 한 번에 하나의 변수만 바꾸는 것이 좋습니다.
재발 방지: 규칙 관리와 운영 체크리스트
Docker Hub가 한 번 작동했다고 설정을 그대로 방치하면 다음 이미지 공급자 변경이나 Clash 프로필 갱신 때 다시 실패할 수 있습니다. 먼저 Docker 관련 규칙을 별도 구역에 모으고, 그룹 이름을 DOCKER-HUB처럼 명확하게 지정하세요. 구독 프로필을 갱신할 때 이 규칙이 사라지지 않도록 로컬 오버라이드나 검증된 Rule Provider를 사용하고, 자동 업데이트 후에는 규칙 순서와 그룹 이름을 확인하는 절차를 둡니다.
운영 서버에서는 모든 컨테이너 트래픽을 개인용 프록시로 보내는 구성이 적절하지 않을 수 있습니다. 이미지 pull만 프록시가 필요하다면 Docker 데몬의 공식 프록시 설정이나 조직이 운영하는 레지스트리 미러가 더 예측 가능합니다. 반대로 개발 노트북에서 여러 CLI와 컨테이너가 동일한 네트워크 제한을 받는다면 TUN으로 통합하되, 사내 도메인·로컬 레지스트리·클라우드 내부 주소는 명시적으로 DIRECT 또는 전용 경로에 남겨야 합니다.
- 로그 보관: 실패 시각, 이미지 태그, 오류 메시지, 매칭된 규칙, 사용한 그룹을 함께 기록합니다.
- 캐시 구분: Docker 로컬 레이어 캐시가 성공처럼 보이게 만들지 않도록 새 태그나 다른 테스트 이미지를 사용합니다.
- 보안 유지: Docker Hub 액세스 토큰과 구독 URL을 로그·스크린샷·공개 이슈에 남기지 않습니다.
- 대체 경로 준비: 중요한 배포는 승인된 프라이빗 레지스트리, 이미지 미러, 사내 캐시를 함께 검토합니다.
자주 묻는 질문: Docker Hub와 Clash TUN
시스템 프록시를 켰는데도 Docker pull이 실패하는 이유는 무엇인가요?
Docker 데몬은 현재 사용 중인 셸과 별도의 서비스로 실행되며, Docker Desktop이나 WSL2에서는 별도 VM이 연결을 담당할 수 있습니다. 그래서 시스템 프록시가 브라우저에 적용되어도 데몬에는 전달되지 않을 수 있습니다. Docker 컨텍스트, 데몬 로그, Clash TUN rule hit를 차례로 확인하고, 필요한 경우 공식 Docker 데몬 프록시 설정과 TUN 중 하나를 기준 경로로 선택하세요.
registry-1.docker.io만 규칙에 넣으면 충분한가요?
대부분의 환경에서는 충분하지 않습니다. 인증 토큰을 발급하는 auth.docker.io와 실제 레이어를 제공하는 호스트가 별도로 사용될 수 있습니다. 레이어 다운로드 단계에서 실패한다면 Clash 연결 로그의 실제 SNI와 Host를 확인해 최소 범위로 규칙을 보강하세요.
Docker에는 fake-ip와 redir-host 중 어떤 DNS 모드가 더 좋은가요?
정답은 실행 환경에 따라 다릅니다. fake-ip은 도메인 기반 분류에 유리하지만 Docker 내부 DNS와 로컬 네트워크 예외를 세밀하게 관리해야 합니다. redir-host는 일부 애플리케이션과의 호환성이 편할 수 있으나 DNS 결과가 정책과 어긋날 수 있습니다. 같은 이미지와 같은 노드로 두 모드를 비교하고, DNS 오류와 rule hit를 함께 기록해 선택하세요.
TLS handshake timeout이 계속되면 인증서를 다시 설치해야 하나요?
대부분은 아닙니다. 먼저 시스템 시간이 정확한지, Clash 노드와 Docker 데몬이 서로 다른 프록시를 중첩 사용하지 않는지, 회사 TLS 검사 정책이 있는지, MTU와 대역폭이 충분한지 확인하세요. 공식적으로 승인된 인증서 배포가 필요한 경우에만 관리자 절차에 따라 CA를 설치해야 하며, 검증되지 않은 인증서를 임의로 신뢰 저장소에 추가해서는 안 됩니다.
일부 유사 프록시 클라이언트나 전통적인 VPN 도구는 브라우저와 일반 앱의 연결에는 편리하지만, Docker 데몬·WSL2·가상 네트워크처럼 별도 라우팅을 사용하는 트래픽을 일관되게 분류하지 못하거나, 레지스트리·토큰·CDN을 한 번에 확인할 로그가 부족한 경우가 있습니다. 반면 Clash TUN은 가상 인터페이스, DNS 가로채기, 도메인 규칙, rule hit 로그를 함께 제공하므로 Docker Hub의 어느 요청이 실패했는지 좁혀 볼 수 있고, Docker Hub만 전용 그룹에 연결하면서 사내 레지스트리와 로컬 네트워크는 별도로 유지할 수 있습니다. 이런 방식으로 설정을 직접 점검해 보고 싶다면 다운로드 페이지에서 사용 중인 운영체제에 맞는 클라이언트를 확인한 뒤, 테스트 환경에서 TUN과 Docker 규칙을 단계적으로 적용해 보세요.