서론: Docker pull 타임아웃의 정체
웹 브라우저에서는 해외 사이트가 정상적으로 열리는데 docker pull만 멈추거나 i/o timeout, Client.Timeout exceeded, context deadline exceeded 오류가 발생한다면 Docker 자체의 문제가 아닐 수 있습니다. 가장 흔한 원인은 브라우저가 사용하는 시스템 프록시와 Docker 데몬이 사용하는 네트워크 경로가 서로 다르기 때문입니다.
Clash는 브라우저 요청을 규칙에 따라 프록시 노드로 보낼 수 있지만, Docker CLI가 실제로 통신하는 주체는 백그라운드에서 실행되는 Docker 데몬입니다. 따라서 Clash의 시스템 프록시를 켰다는 이유만으로 Docker Hub의 이미지 레이어 다운로드까지 자동으로 프록시 처리된다고 보기는 어렵습니다. 특히 Windows의 Docker Desktop, Linux의 docker.service, macOS의 Docker Desktop은 각각 별도의 프록시 설정을 요구할 수 있습니다.
핵심 요약
브라우저가 정상이라는 사실은 Clash 노드가 살아 있다는 의미일 뿐입니다. Docker 데몬이 Clash의 포트와 규칙을 실제로 사용하고 있는지 별도로 확인해야 합니다.
1먼저 오류 원인과 연결 상태 확인
설정을 바로 수정하기 전에 문제가 DNS인지, 노드 품질인지, Docker 데몬의 프록시 상속 문제인지 구분해야 합니다. 원인을 잘못 판단하면 Clash 설정을 여러 번 바꾸어도 해결되지 않습니다.
- Docker 버전 확인: 터미널에서
docker version과docker info를 실행합니다. Docker CLI만 설치되어 있고 데몬이 실행되지 않은 상태라면 네트워크 오류처럼 보이는 다른 메시지가 표시될 수 있습니다. - Docker Hub 도메인 확인: 브라우저에서
https://registry-1.docker.io/v2/를 열어 봅니다. 인증이 필요하다는 응답이 나오더라도 서버에 도달했다는 뜻이므로, 완전한 연결 실패와 구분해야 합니다. - 간단한 이미지로 재현: 큰 이미지 대신
docker pull hello-world를 사용합니다. 작은 이미지도 실패하면 인증이나 레이어 용량보다 경로와 프록시 설정을 먼저 살펴보는 것이 좋습니다. - Clash 로그 확인: Clash Verge Rev 또는 사용 중인 클라이언트의 연결 로그에서
registry-1.docker.io,auth.docker.io,production.cloudflare.docker.com요청이 보이는지 확인합니다.
| 증상 | 가능성이 높은 원인 | 우선 조치 |
|---|---|---|
| 브라우저는 정상, pull만 실패 | Docker 데몬이 프록시를 사용하지 않음 | 데몬 프록시 설정 |
| 인증 단계에서 반복 실패 | auth.docker.io 분기 누락 또는 DNS 문제 |
관련 도메인과 DNS 확인 |
| 레이어 다운로드 중 멈춤 | 노드 품질, MTU, 대용량 연결 불안정 | 다른 노드와 TUN 설정 테스트 |
| 모든 컨테이너 네트워크도 실패 | Docker 네트워크 또는 데몬 환경 문제 | Docker 서비스와 방화벽 점검 |
2Clash의 프록시 포트와 노드 점검
Docker에 입력할 주소는 Clash 화면에 표시되는 구독 주소가 아니라 로컬에서 Clash가 열어 둔 프록시 포트입니다. 일반적으로 HTTP 프록시는 7890, SOCKS5는 7891을 사용하는 경우가 많지만, 사용자가 변경했거나 클라이언트 버전에 따라 다를 수 있으므로 반드시 실제 값을 확인해야 합니다.
- HTTP 포트: Docker 엔진의 환경 변수나 Docker Desktop 프록시 입력란에서는 보통
http://127.0.0.1:7890형식으로 사용합니다. - SOCKS5 포트: Docker 데몬이 SOCKS5를 직접 지원하지 않거나 환경에 따라 동작이 제한될 수 있습니다. 가능하면 Clash의 HTTP 또는 Mixed 포트를 우선 사용하세요.
- Mixed 포트: HTTP와 SOCKS5 요청을 함께 처리하는 포트입니다. 클라이언트에서 Mixed 포트를 활성화했다면 Docker에는 해당 포트를 HTTP 프록시 주소로 입력할 수 있습니다.
- LAN 접근 허용: Docker가 별도 가상 머신이나 WSL2 환경에서 실행된다면
127.0.0.1이 Windows 호스트를 의미하지 않을 수 있습니다. 이때는 Clash의 LAN 허용과 호스트 IP 확인이 필요합니다.
주의사항
Clash의 LAN 허용을 켤 때는 프록시 포트를 인터넷 전체에 공개하지 마세요. 방화벽에서 신뢰하는 로컬 네트워크만 허용하고, 사용이 끝나면 다시 차단하는 것이 안전합니다.
노드도 함께 확인해야 합니다. Docker Hub는 인증 요청, 매니페스트 조회, 여러 개의 이미지 레이어 다운로드를 연속으로 수행하므로 순간적으로 빠른 노드보다 연결 유지가 안정적인 노드가 더 적합합니다. Clash의 지연 시간 테스트 결과만 보지 말고 실제로 작은 이미지와 중간 크기 이미지를 차례로 받아 보세요.
3Docker Hub 전용 분기 규칙 작성
프록시 포트를 지정했는데도 요청이 DIRECT로 빠지면 Docker pull은 여전히 실패할 수 있습니다. Docker Hub는 하나의 도메인만 사용하는 서비스가 아니므로 레지스트리, 인증 서버, 이미지 레이어 저장소를 함께 고려해야 합니다. 설정 파일의 rules에 전용 프록시 그룹을 만들고 관련 규칙을 일반적인 글로벌 규칙보다 위에 배치하세요.
Docker-Proxy는 실제 설정 파일에 존재하는 프록시 그룹 이름으로 바꾸어야 합니다. 그룹 이름이 PROXY 또는 Global이라면 그 이름을 사용하세요. 규칙을 추가한 뒤에는 설정을 저장하고 프로필을 다시 적용해야 하며, 구독 업데이트 때 사용자 규칙이 덮어써지지 않는지도 확인해야 합니다.
성공 팁
Clash 로그에서 Docker 관련 요청이 동일한 전용 그룹으로 전달되는지 확인하세요. 로그에 요청 자체가 나타나지 않는다면 규칙 문제가 아니라 Docker 데몬이 Clash를 거치지 않는 상황일 가능성이 큽니다.
규칙 순서와 도메인 누락 확인
Clash 규칙은 위에서 아래 순서로 평가됩니다. Docker 도메인보다 앞에 있는 GEOIP,CN,DIRECT, MATCH,DIRECT 또는 특정 도메인 차단 규칙이 먼저 적용되면 의도한 프록시 그룹에 도달하지 않습니다. 전용 규칙은 충분히 위쪽에 두고, 마지막의 MATCH는 항상 가장 아래에 유지하세요.
4Docker 데몬에 프록시 연결하기
핵심은 Docker CLI가 아니라 Docker 데몬에 프록시를 지정하는 것입니다. 플랫폼마다 설정 위치가 다르므로 자신의 실행 환경에 맞는 방법을 선택해야 합니다. 프록시 주소에는 Clash의 HTTP 또는 Mixed 포트를 사용하고, 포트가 실제로 열려 있는지 먼저 확인하세요.
- Docker Desktop의 Settings에서 프록시 관련 메뉴를 엽니다.
- 수동 프록시 설정을 선택하고 HTTP 프록시에
http://host.docker.internal:7890또는 환경에 맞는 Clash 호스트 주소를 입력합니다. - HTTPS 프록시도 같은 주소를 사용하고, Docker Desktop을 재시작합니다.
docker info의HTTP Proxy와HTTPS Proxy항목을 확인한 뒤 pull을 다시 실행합니다.
WSL2를 사용한다면 Windows 호스트의 Clash 포트가 WSL2에서 접근 가능한지 별도로 테스트해야 합니다.
Linux에서는 Docker 서비스에 drop-in 설정을 추가하는 방식이 일반적입니다.
Docker가 별도 서버에서 실행되고 Clash는 다른 컴퓨터에서 실행되는 경우에는 127.0.0.1 대신 Clash가 실행 중인 호스트의 사설 IP를 입력해야 합니다. 또한 해당 포트가 방화벽에서 허용되어야 합니다.
macOS의 Docker Desktop은 Linux 데몬이 가상 환경에서 실행됩니다. 따라서 macOS 시스템 프록시가 자동으로 상속되지 않을 수 있습니다. Docker Desktop의 Resources 또는 Proxies 설정에서 HTTP와 HTTPS 프록시를 직접 지정한 뒤 애플리케이션을 재시작하세요. 입력 주소는 환경에 따라 host.docker.internal 또는 Clash가 제공하는 호스트 접근 주소를 사용합니다.
5DNS, TLS, MTU 문제 추가 점검
데몬 프록시를 설정했는데도 lookup registry-1.docker.io 또는 TLS handshake 오류가 계속된다면 DNS와 가상 네트워크의 특성을 확인해야 합니다. 브라우저는 Clash의 DNS를 사용하지만 Docker 데몬은 호스트의 기본 DNS를 사용할 수 있습니다. 이 차이 때문에 도메인 해석 결과가 달라지거나 연결이 오래 지연될 수 있습니다.
- DNS 모드 확인: Clash에서 사용할 원격 DNS와 fake-ip 설정을 확인합니다. Docker 관련 도메인에 fake-ip 예외가 필요한 환경이라면
fake-ip-filter에 관련 도메인을 추가해 비교 테스트를 진행하세요. - 시간과 인증서 확인: 호스트의 날짜와 시간이 크게 어긋나면 Docker Registry의 TLS 인증서 검증이 실패할 수 있습니다.
- MTU 테스트: TUN 모드에서 작은 요청은 성공하지만 큰 레이어만 중단된다면 MTU가 경로와 맞지 않을 수 있습니다. TUN의 MTU를 조금 낮춰 재시도하되, 값을 무작정 크게 변경하지 마세요.
- IPv6 비교: IPv6 경로가 불안정한 네트워크에서는 레지스트리 연결이 간헐적으로 타임아웃될 수 있습니다. IPv4 우선 설정으로 비교하여 원인을 좁힐 수 있습니다.
인증서 오류에 대한 주의
TLS 검증을 끄거나 인증서 확인을 무조건 비활성화하는 방식은 권장하지 않습니다. Docker Hub의 인증 정보를 노출하고 중간자 공격에 취약해질 수 있으므로, 먼저 프록시 주소와 DNS 경로를 바로잡으세요.
6설정 적용 후 검증 절차
설정 파일을 바꾼 뒤에는 한 번에 모든 문제를 추측하지 말고 단계별로 확인하는 것이 가장 빠릅니다. 먼저 Docker 데몬을 재시작하고, Clash 로그 창을 열어 둔 상태에서 작은 이미지를 요청합니다.
로그인 단계에서 실패하면 auth.docker.io 규칙과 인증 정보를 확인하고, 로그인 후 레이어에서 실패하면 production.cloudflare.docker.com 같은 저장소 도메인이 프록시를 통과하는지 확인하세요. 같은 이미지가 한 노드에서는 성공하고 다른 노드에서는 실패한다면 YAML보다 노드 품질이나 해당 노드의 대용량 연결 정책이 원인일 가능성이 높습니다.
반대로 Clash 로그에 아무 요청도 보이지 않는다면 Docker 데몬이 설정을 읽지 않았을 수 있습니다. Linux에서는 systemctl show --property=Environment docker로 환경 변수를 확인하고, Docker Desktop에서는 설정 저장 후 완전한 재시작을 진행하세요. 프록시를 제거한 뒤에도 동일한 오류가 발생하는지 비교하면 Clash와 Docker 자체의 문제를 분리하는 데 도움이 됩니다.
완료 기준
Docker Hub 인증, 매니페스트 조회, 이미지 레이어 다운로드가 모두 성공하고 Clash 로그에 관련 요청이 올바른 프록시 그룹으로 기록되면 기본 설정이 완료된 것입니다.
자주 묻는 질문
브라우저는 되는데 Docker만 실패하는 이유는 무엇인가요?
브라우저는 시스템 프록시나 Clash 확장 기능을 사용하지만 Docker pull은 Docker 데몬이 별도의 프로세스로 처리하기 때문입니다. 데몬에 HTTP와 HTTPS 프록시를 직접 지정하고 서비스를 재시작해야 합니다.
SOCKS5 포트를 Docker에 입력해도 되나요?
Docker 환경과 버전에 따라 SOCKS5 지원 여부가 다를 수 있습니다. 호환성 문제를 줄이려면 Clash의 HTTP 또는 Mixed 포트를 사용하고, 주소를 http://로 명시하는 방법이 일반적으로 더 안정적입니다.
Docker Hub 규칙에는 어떤 도메인이 필요한가요?
최소한 registry-1.docker.io와 auth.docker.io를 확인해야 합니다. 실제 레이어가 다른 저장소로 연결될 수 있으므로 Clash 로그에 표시되는 최종 다운로드 도메인도 함께 규칙에 추가하세요.
TUN 모드만 켜면 데몬 프록시 설정이 필요 없나요?
TUN 모드가 Docker 데몬의 트래픽까지 확실히 가로채는 환경이라면 동작할 수 있지만, Docker Desktop과 가상 머신, WSL2에서는 예외가 많습니다. 재현성과 문제 해결을 위해 데몬 프록시를 명시하고 TUN은 보조 수단으로 사용하는 편이 좋습니다.