이 글이 맞는 Docker Hub 타임아웃 증상
Docker Hub 웹사이트는 브라우저에서 열리고 일반적인 웹 검색도 정상인데, docker pull만 멈추거나 실패한다면 단순히 인터넷이 느린 문제로 보기 어렵습니다. Docker 클라이언트는 이미지 이름을 확인한 뒤 레지스트리 인증 서버, 이미지 매니페스트, 여러 레이어 다운로드 엔드포인트에 차례로 접속합니다. 이 과정에서 하나라도 DNS 조회가 잘못되거나, TUN 인터페이스를 우회하거나, Clash 규칙이 DIRECT로 잘못 매칭되면 웹 브라우저는 정상인데 이미지 다운로드만 context deadline exceeded, i/o timeout, TLS handshake timeout으로 끝날 수 있습니다.
이 문서는 Clash TUN 모드를 사용하면서 Docker Hub 연결이 불안정한 Windows·macOS·Linux 환경을 대상으로 합니다. 특정 구독 제공자의 노드 이름이나 하나의 GUI에 의존하지 않고, DNS 확인 → TUN 경로 확인 → Docker 프로세스의 프록시 전달 → 규칙 매칭 검증 순서로 문제를 좁혀 갑니다. 처음부터 글로벌 모드로 모든 트래픽을 보내기보다는, 실제로 Docker가 접속하는 호스트를 확인한 뒤 필요한 도메인만 안정적인 프록시 그룹에 고정하는 방법을 권장합니다.
브라우저는 되는데 Docker 이미지만 실패하는 이유
브라우저와 Docker 데몬은 같은 컴퓨터에서 실행되더라도 네트워크 경로가 다를 수 있습니다. 브라우저는 운영체제의 시스템 프록시를 자동으로 읽거나 자체 프록시 설정을 갖지만, Docker CLI는 환경 변수와 Docker 엔진 설정에 따라 별도의 경로를 사용합니다. 특히 Linux의 Docker 데몬은 현재 로그인한 셸이 아니라 dockerd 서비스로 실행되므로, 셸에서 export HTTPS_PROXY를 입력해도 데몬에는 전달되지 않는 경우가 많습니다.
Docker Hub 접속은 하나의 주소만 사용하는 작업도 아닙니다. 일반적으로 registry-1.docker.io에서 레지스트리 API를 호출하고, auth.docker.io에서 토큰을 받아오며, 이미지 레이어는 CDN 또는 저장소 전용 호스트에서 내려받습니다. 따라서 첫 번째 인증 요청만 성공하고 실제 레이어 다운로드에서 멈추거나, 공개 이미지는 되는데 특정 이미지의 일부 레이어만 실패하는 현상이 나타날 수 있습니다.
또한 TUN은 애플리케이션이 프록시를 직접 인식하지 못하더라도 IP 패킷을 가상 인터페이스로 끌어오는 방식입니다. TUN이 켜져 있다는 사실만으로 모든 Docker 트래픽이 확실히 프록시를 탄다고 단정할 수는 없습니다. 운영체제 라우팅 우선순위, IPv6 경로, DNS 모드, 자동 우회 목록, Docker 브리지 네트워크가 서로 다르면 일부 연결은 TUN을 거치고 일부는 물리 인터페이스로 빠질 수 있습니다.
| 증상 | 우선 의심할 지점 | 확인 방법 |
|---|---|---|
| 인증 단계에서 바로 타임아웃 | DNS 또는 auth.docker.io 규칙 |
Clash 연결 로그에서 호스트와 정책 그룹 확인 |
| 매니페스트는 받지만 레이어에서 멈춤 | CDN 호스트 우회, MTU, 업스트림 불안정 | 실패한 레이어 요청의 실제 SNI와 시간 확인 |
| 호스트에서는 성공하지만 컨테이너에서 실패 | Docker 데몬·브리지의 DNS 또는 프록시 설정 | docker info, 데몬 환경 변수, 컨테이너 DNS 점검 |
| IPv4에서는 되지만 간헐적으로 실패 | IPv6 직접 연결 또는 TUN의 IPv6 처리 | 임시로 IPv6를 비교하고 연결 로그를 대조 |
Docker Hub에서 먼저 확인할 호스트
규칙을 넓게 추가하기 전에 실패 시점의 호스트를 모으는 것이 중요합니다. 기본적으로 다음 도메인은 Docker Hub 로그인·검색·이미지 풀 과정에서 자주 보이지만, 이미지와 리전, Docker 엔진 버전에 따라 실제 레이어 호스트는 달라질 수 있습니다.
registry-1.docker.io: 레지스트리 API와 매니페스트 요청에 사용됩니다.auth.docker.io: 공개 또는 비공개 저장소의 인증 토큰을 발급합니다.hub.docker.com: 웹사이트와 일부 계정·저장소 메타데이터에 사용됩니다.- 레이어 CDN 호스트: 실제 블롭 데이터가 다른 CDN 도메인에서 전달될 수 있으므로 로그에서 반드시 확인해야 합니다.
DOMAIN-SUFFIX,docker.io처럼 범위를 묶는 방식은 빠른 테스트에는 도움이 되지만, Docker와 무관한 도메인까지 같은 정책을 타게 할 수 있습니다. 반대로 registry-1.docker.io만 등록하면 인증 서버나 레이어 CDN이 누락될 수 있습니다. 먼저 로그에서 실제로 관찰된 호스트를 기록하고, 그 뒤 DOMAIN 또는 필요한 범위의 DOMAIN-SUFFIX 규칙을 추가하세요. 규칙의 순서도 중요합니다. 앞쪽에 있는 지역 직결 규칙이나 대형 GEOSITE 규칙이 Docker 규칙보다 먼저 매칭되면, 작성한 프록시 규칙은 실행되지 않습니다.
Clash TUN과 Docker 경로를 단계별로 맞추기
1단계: TUN 기본 상태와 DNS 모드 확인
먼저 Clash 프로필이 실제로 실행 중인지 확인하고, TUN이 활성화된 뒤 가상 인터페이스가 운영체제에 생성되었는지 봅니다. GUI에서 TUN 스위치를 켰더라도 권한 승인에 실패했거나 코어가 재시작 루프에 빠지면 트래픽은 계속 일반 인터페이스로 나갑니다. 연결 로그에 Docker 관련 호스트가 나타나는지 확인하면서 Rule 모드를 사용하세요. 글로벌 모드는 진단용으로 잠깐 비교할 수 있지만, 원인을 찾은 뒤에는 필요한 트래픽만 규칙으로 분리하는 편이 관리하기 쉽습니다.
DNS는 가상 IP(Fake-IP) 또는 호스트 매핑(Redirect 방식) 중 프로필이 지원하는 모드에 맞춰야 합니다. Docker가 받은 DNS 응답과 Clash가 추적하는 도메인 정보가 서로 어긋나면, 도메인 규칙이 기대한 대로 적용되지 않을 수 있습니다. 테스트 단계에서는 운영체제와 Docker가 서로 다른 DNS를 사용하지 않는지 확인하고, 실패 시각에 DNS 요청이 Clash 로그에 기록되는지도 살펴보세요. 무조건 DNS 주소를 여러 개 추가하기보다, 응답 지연과 오염 여부를 비교해 하나의 일관된 경로를 유지하는 것이 안전합니다.
2단계: Docker 관련 규칙을 프록시 그룹에 고정
테스트용으로는 아래와 같은 최소 규칙을 프로필의 사용자 규칙 영역에 넣을 수 있습니다. 실제 정책 그룹 이름은 사용 중인 YAML에 맞게 바꾸고, 규칙을 기본 규칙보다 위에 배치해야 합니다.
rules:
- DOMAIN,auth.docker.io,Docker
- DOMAIN,registry-1.docker.io,Docker
- DOMAIN,hub.docker.com,Docker
- DOMAIN-SUFFIX,docker.io,Docker
- MATCH,Default이 예시는 문제를 분리하기 위한 출발점일 뿐입니다. 레이어 다운로드가 계속 실패하면 연결 로그에 기록된 CDN 호스트를 확인해 같은 정책 그룹에 추가합니다. Docker라는 이름의 그룹에는 지연 시간이 짧고 장시간 다운로드를 견디는 노드를 넣어야 합니다. 순간적인 핑이 빠른 노드보다 TLS 연결을 오래 유지하고 큰 파일을 안정적으로 전송하는 노드가 실제 이미지 풀에서는 더 유리합니다.
3단계: Docker CLI와 Docker 데몬의 프록시를 구분
Docker Desktop은 앱 설정에서 프록시를 관리하는 경우가 많지만, Linux의 Docker 엔진은 systemd 서비스 환경을 별도로 설정해야 합니다. 셸에서 다음처럼 확인하면 현재 터미널이 어떤 프록시 변수를 받는지 알 수 있습니다.
env | grep -i proxy
docker info
docker pull hello-worldCLI가 읽는 프록시와 데몬이 읽는 프록시는 서로 다를 수 있습니다. 데몬에 프록시를 적용할 때는 배포판의 systemd drop-in 또는 Docker 공식 설정 방식을 사용하고, 변경 후 서비스를 재시작합니다. 사내 레지스트리나 로컬 주소가 있다면 NO_PROXY에 해당 도메인과 사설 대역을 넣어 내부 이미지까지 외부 프록시로 보내지 않도록 하세요. 프록시 URL에 인증 정보가 포함된다면 systemd 파일과 셸 기록에 평문으로 남지 않도록 별도 권한 파일이나 안전한 시크릿 관리 방식을 검토해야 합니다.
4단계: 작은 이미지부터 실제 레이어를 검사
설정을 저장한 뒤 곧바로 용량이 큰 이미지로 테스트하지 마세요. 먼저 hello-world나 작은 Alpine 이미지를 받아 인증·매니페스트·레이어의 기본 경로가 모두 살아 있는지 확인합니다. 다음으로 여러 레이어가 있는 이미지를 시도해 장시간 연결이 유지되는지 비교합니다. 첫 번째 명령은 빠르게 성공하지만 큰 이미지에서만 멈춘다면 노드의 대역폭, 연결 유지 시간, MTU 또는 CDN 경로를 의심할 수 있습니다.
실패 시에는 같은 명령을 반복하기보다 매번 Clash 로그를 저장하세요. 매번 다른 정책 그룹이 선택되면 자동 URL 테스트나 부하 분산 그룹이 원인일 수 있습니다. 반대로 항상 같은 그룹에서 동일한 시점에 멈춘다면 해당 업스트림의 전송 품질이나 서버 측 제한을 비교해야 합니다. Docker의 재시도 동작 때문에 실패가 늦게 나타날 수 있으므로, 명령을 시작한 시각과 마지막 로그 시각을 함께 기록하면 분석이 쉬워집니다.
DNS·TUN·MTU를 구분하는 실전 진단
DNS 문제는 대개 호스트 이름을 해석하지 못하거나, 잘못된 주소를 받아 연결 자체가 시작되지 않는 형태로 나타납니다. nslookup 또는 dig로 확인할 때는 단순히 응답이 있다는 사실보다, Clash가 사용하는 DNS와 Docker 데몬이 사용하는 DNS가 같은 정책을 적용하는지를 비교해야 합니다. 이름이 정상적으로 해석되더라도 응답된 IP로 직접 연결하는 과정이 차단될 수 있으므로 DNS 결과만으로 성공을 판정하지 마세요.
TUN 우회는 Clash 로그에 Docker 호스트가 전혀 나타나지 않는 경우 특히 의심할 만합니다. Docker 브리지 인터페이스, 별도의 네트워크 네임스페이스, VPN 클라이언트가 함께 실행 중이면 라우팅 우선순위가 달라질 수 있습니다. 다른 VPN을 잠시 끄고 TUN만 활성화한 상태에서 동일한 이미지를 받아 보면 경로 충돌 여부를 확인할 수 있습니다. 단, 회사나 학교 네트워크에서 정책을 우회하는 것이 허용되는지 먼저 확인해야 합니다.
작은 요청은 성공하지만 큰 레이어에서만 중단되면 MTU와 연결 유지 문제를 비교하세요. TUN, VPN, Docker 브리지에 서로 다른 캡슐화가 겹치면 큰 패킷이 조각화되거나 손실될 수 있습니다. 이때 무작정 MTU 값을 크게 또는 작게 바꾸기보다는 현재 네트워크의 기본값을 기록하고, 한 번에 한 요소만 변경한 뒤 동일한 이미지로 재시험해야 합니다. 변경 전후의 다운로드 속도, 중단 위치, Clash 오류 메시지를 남기면 되돌릴 기준도 분명해집니다.
자주 묻는 질문
브라우저에서 Docker Hub가 열리면 프록시는 정상 아닌가요?
반드시 그렇지는 않습니다. 브라우저는 시스템 프록시를 사용하지만 Docker 데몬은 별도의 서비스 환경과 네트워크 경로를 사용할 수 있습니다. 브라우저 접속 성공은 웹 경로의 가능성을 보여 줄 뿐이며, auth.docker.io와 레이어 CDN이 같은 정책을 타는지는 Clash 로그와 실제 docker pull 결과로 확인해야 합니다.
글로벌 모드에서는 되는데 규칙 모드에서는 왜 실패하나요?
규칙 모드에서 Docker 호스트가 DIRECT 또는 잘못된 그룹으로 매칭되었을 가능성이 큽니다. 글로벌 모드는 진단용 비교에는 유용하지만, 해결책으로 계속 사용하면 국내 저장소와 사내 레지스트리까지 불필요하게 프록시를 거치게 됩니다. 실패한 호스트를 확인한 뒤 사용자 규칙을 더 앞에 배치하세요.
셸에 HTTPS_PROXY를 설정했는데 Docker가 여전히 실패합니다.
Linux에서는 docker pull이 데몬에 요청을 전달하고, 실제 외부 연결은 dockerd가 수행합니다. 따라서 현재 셸의 변수만으로는 부족할 수 있습니다. Docker 서비스에 공식 방식으로 프록시를 설정한 뒤 데몬을 재시작하고, docker info와 연결 로그를 함께 확인하세요.
Docker Hub용 규칙을 만들 때 주의할 보안 사항은 무엇인가요?
프록시 설정 파일에 Docker Hub 비밀번호, 액세스 토큰, 개인 레지스트리 인증 정보를 직접 넣지 마세요. Docker 자격 증명은 운영체제의 credential store나 Docker가 제공하는 안전한 로그인 방식을 사용하고, 공용 로그에 토큰이 출력되지 않는지도 확인해야 합니다. 프록시 그룹 변경과 이미지 다운로드 기록에도 민감한 저장소 이름이 남을 수 있으므로 공유 전 마스킹이 필요합니다.
간단한 웹 프록시 확장 프로그램은 브라우저 탭에는 편하지만 Docker 데몬·컨테이너·레이어 CDN까지 일관되게 다루기 어렵고, 일부 GUI 도구는 TUN 권한이나 규칙 로그가 제한되어 실패 원인을 확인하기 힘듭니다. 반면 Clash는 DNS 정책, TUN 경로, 도메인 규칙, 정책 그룹, 연결 로그를 한 흐름에서 조정할 수 있어 “웹은 되는데 이미지 풀만 실패하는” 상황을 단계적으로 분리하기 좋습니다. Docker Hub의 실제 호스트와 환경에 맞는 규칙을 직접 검증하고 싶다면, 사용 중인 플랫폼에 맞는 Clash 클라이언트를 내려받아 이 절차를 적용해 보세요.