도커 허브 pull이 멈출 때: Hub·레지스트리 미러 도메인을 Clash(mihomo)로 분기·DNS를 맞추는 실측 (2026)

1. pull이 멈출 때 자주 보는 패턴

검색으로 들어오는 표현은 「docker pull 안 됨」「이미지 다운로드 멈춤」「TLS connection timeout」처럼 짧게 찍히기도 합니다. 현장에서는 먼저 증상을 세 가지 축으로 나누는 편이 빠릅니다. 첫째, 이름 해석이 실패해 첫 SYN조차 안 나가는 경우입니다. 둘째, 연결은 되는데 TLS 이전이나 직후에 멈추는 경우로, 느린 노드·패킷 손실·중간 장비의 inspection 타이밍을 의심합니다. 셋째, 매니페스트는 받았는데 레이어 blob를 받는 단계에서만 끊기는 경우로, 이때는 CDN·스토리지 호스트가 별도 정책 그룹으로 빠졌는지 봅니다.

Clash 계열에서 분기가 어긋나면 브라우저로 hub.docker.com을 열었을 때는 페이지가 보이지만 데몬 pull만 실패하는 모순이 생기기도 합니다. 웹 프론트와 레지스트리 API가 완전히 같은 경로를 타지 않기 때문입니다. 그래서 이 문제는 「프록시를 켰다」로 끝내기보다, 어떤 FQDN이 어떤 아웃바운드로 나갔는지 로그로 확인하는 쪽이 재발을 줄입니다.

2. Docker 엔진이 어떤 호스트를 두드리나

docker pull library/nginx 같은 단순한 명령도 내부적으로는 메타데이터 조회·인증·레이어 페치가 단계별로 일어납니다. 운영 중인 Docker 버전과 로그인 여부에 따라 세부 호스트명은 조금씩 달라질 수 있지만, 실무에서 먼저 의심하는 축은 registry-1.docker.io 계열과 auth.docker.io·토큰 발급, 그리고 실제 바이너리를 끌어오는 CDN·스토리지 레이어입니다. 즉 한 줄의 pull이 단일 IP와의 대화가 아니라 여러 TLS 세션의 연쇄라는 점이 Clash 규칙을 설계할 때의 전제입니다.

엔진이 /etc/docker/daemon.json에 registry-mirrors를 갖고 있다면, 메타는 여전히 Hub 경로를 보더라도 실제 레이어는 미러 쪽 호스트로 향할 수 있습니다. 이때 미러가 사내 주소라면 DIRECT 규칙을 앞에 두고, 공용 미러라면 보안·규정 검토 후 Hub와 같은 정책 그룹에 묶는 편이 디버깅에 유리합니다. 반대로 미러만 직통으로 열어 두고 Hub 본선은 막혀 있으면 매니페스트 단계에서 실패하는 모순도 나올 수 있습니다.

3. 규칙에 넣기 좋은 도메인 출발점

아래 목록은 「항상 이 이름만 쓴다」가 아니라 로그에 실제로 찍힌 FQDN을 기준으로 덧대는 출발점입니다. Hub는 인프라를 바꾸면 호스트명이 늘거나 줄 수 있으니, 한 번 막힐 때마다 mihomo의 connection 로그나 데몬 debug 로그에 나온 이름을 규칙 세트에 합치는 습관이 장기적으로 이득입니다. 실무에서 자주 묶는 접미는 docker.io, docker.com 계열입니다. 웹 콘솔용 hub.docker.com, 레지스트리 본선 registry-1.docker.io, 인증 auth.docker.io, 그리고 클라우드플레어를 앞에 둔 배포 도메인(예: production.cloudflare.docker.com 등, 버전에 따라 상이)을 같은 정책 그룹 후보로 둡니다.

사내 Harbor·GitLab Container Registry로만 일한다면 docker.io 자체를 아예 건드리지 않을 수도 있습니다. 반대로 공용 Hub만 쓰는 팀이라면 미러 주소가 Tencent·Netease·Mirror 주소 등 지역 미러로 바뀌는데, 이 호스트들은 규정상 허용되는지와 TLS 인증서 검증이 정상인지 먼저 확인한 뒤 규칙에 넣어야 합니다. 미러 업체가 바뀌면 FQDN도 바뀌므로, 문서에 고정 문자열만 복사해 두기보다 운영 Runbook에 「로그에서 이름을 발췌해 rule-provider를 갱신한다」는 절차를 남기는 편이 안전합니다. 대용량 Hub와 비슷하게 CDN이 갈라지는 사례는 Hugging Face Hub 글에서도 같은 논리로 다룹니다.

4. mihomo rules 스니펫

실제 프로필에서는 정책 그룹 이름을 자신의 proxy-groups에 맞춰 바꿉니다. 핵심은 DOMAIN-SUFFIX로 광역을 잡되, 사내 미러·내부 레지스트리는 더 위에 DIRECT나 전용 그룹을 두어 예외를 명시하는 것입니다. PROCESS-NAME으로 dockerd만 보내는 트릭도 있으나, 데몬이 자식 프로세스나 다른 바이너리 이름을 쓰는 배포판이 있어 도메인 규칙과 병행하는 편이 안정적입니다.

# Example only — replace DOCKER-HUB with your proxy group name
rules:
  - DOMAIN-SUFFIX,docker.io,DOCKER-HUB
  - DOMAIN-SUFFIX,docker.com,DOCKER-HUB
  - DOMAIN,registry-1.docker.io,DOCKER-HUB
  - DOMAIN,auth.docker.io,DOCKER-HUB

규칙 순서나 GEOIP 매칭이 뒤섞이면 의도와 다른 노드로 새기 쉽습니다. 프로젝트 전반의 분기 철학은 규칙·정책 그룹 가이드와 맞춰 두면, 나중에 rule-provider만 갱신해도 Hub 축이 따라오게 만들 수 있습니다.

5. daemon.json 레지스트리 미러와 Clash의 관계

registry-mirrors는 엔진이 Hub 대신 또는 Hub와 병행해 레이어를 가져올 미러 엔드포인트를 가리킵니다. 미러가 정상이라면 지리적으로 가까운 회선으로 내려받기 시간이 줄어들 수 있지만, 미러 호스트 자체도 공인 DNS와 TLS를 타므로 Clash에서 막히면 pull은 여전히 실패합니다. 즉 「미러만 켜면 Clash 설정은 끝」이 아니라, 미러 FQDN을 Hub와 같은 정책 그룹에 넣거나, 사내 망이면 DIRECT 예외를 앞에 두는 식으로 대칭으로 정리해야 합니다.

# /etc/docker/daemon.json example — verify mirror URL with your org policy
{
  "registry-mirrors": ["https://mirror.example.com"]
}

설정 변경 후에는 데몬 재시작이 필요합니다. Docker Desktop 사용자는 GUI의 Docker Engine JSON 편집 경로가 다를 수 있으니 플랫폼 문서를 따릅니다. 미러와 Hub를 섞어 쓸 때 인증 토큰이 어긋나 pull이 401로 끊기면, 로그인 상태·크리덴셜 헬퍼·미러가 토큰 전달을 지원하는지까지 확인해야 합니다. 이때도 실패 호스트명은 결국 레지스트리·auth·CDN 중 하나입니다.

6. DNS·fake-ip·데몬 리졸버

DNS가 어긋나면 규칙이 아무리 좋아도 「이름은 있는데 IP가 이상하다」가 됩니다. 호스트 Clash에서 fake-ip를 쓰는데 리눅스 데몬이 systemd-resolved나 /etc/resolv.conf를 통해 Clash 밖의 서버로 직접 묻고 있으면, 규칙 매칭용 이름과 실제 소켓의 목적지가 달라질 수 있습니다. 반대로 데몬만 호스트 게이트웨이 DNS를 쓰고 브라우저는 DoH를 쓰면 증상이 갈라지기도 합니다. DNS·fake-ip·redir-host 글의 절차를 Hub 시나리오에 맞게 단축해 적용하는 것을 권합니다.

TUN 모드를 켠 상태에서 데몬 트래픽이 tun0를 타는지, 브리지에서 호스트로 나간 뒤 다시 라우팅되는지는 OS마다 다릅니다. macOS·Windows는 데스크톱 클라이언트의 시스템 프록시/TUN 조합에 따라 docker pull이 사용자 영역과 다른 경로를 탈 수 있으니, 실패 시점의 인터페이스와 게이트웨이를 netstat·GUI 상태 표시로 한 번 확인하는 것이 좋습니다. CI 리눅스에서는 호스트 전체가 이미 Clash TUN 아래에 있다면 데몬도 같은 테이블을 따르지만, Docker-in-Docker나 중첩 네임스페이스면 또 한 겹 벗겨야 합니다.

7. 실측 점검 순서

첫째, docker pull --debug나 데몬 로그 레벨을 올려 어느 단계에서 멈추는지 타임스탬프와 함께 남깁니다. 둘째, 같은 시각에 mihomo 대시보드나 로그에서 어떤 FQDN이 어떤 policy·어떤 노드로 나갔는지 대조합니다. 셋째, 문제 호스트에 대해 호스트 쉘에서 curl -vI https://registry-1.docker.io/v2/처럼 TLS만 따로 찍어 보고, Clash를 잠시 끄거나 DIRECT 그룹으로 바꿔 대조 실험을 합니다. 넷째, 미러를 켠 경우 docker info에 미러가 반영됐는지와 미러 FQDN이 규칙에 포함됐는지 확인합니다.

8. 자주 묻는 질문

아래는 본문을 읽은 뒤에도 남는 짧은 질문에 대한 요약입니다. 구조화 데이터에는 동일 Q&A가 JSON-LD로도 실려 검색 결과에 도움이 될 수 있습니다.

docker pull만 느리고 브라우저는 정상일 수 있나요?

가능합니다. 데몬은 레지스트리·CDN·인증 호스트를 순서로 두드리므로, 웹만 직통이고 레지스트리 FQDN이 다른 정책 그룹이나 노드로 새면 pull만 지연·타임아웃이 납니다.

레지스트리 미러를 켜면 Clash 규칙이 필요 없나요?

미러 호스트 역시 인터넷을 타므로 네트워크가 막혀 있으면 동일하게 분기·DNS가 필요합니다. 미러는 Hub 부하 분산과 지역 가까운 경로를 제공할 뿐만 아니라, 규정·신뢰 검증 없이 URL만 복사해 쓰면 보안 리스크도 커집니다.

HTTP_PROXY만 맞췄는데 왜 pull은 그대로인가요?

Docker 데몬은 기본적으로 컨테이너용 HTTP_PROXY와 별개 경로로 레지스트리에 붙습니다. 컨테이너 빌드·런타임 프록시는 호스트 Clash HTTP_PROXY 글 축에 가깝고, pull 안정화는 데몬·TUN·시스템 라우팅 쪽을 함께 봐야 합니다.