2026년 중국 내 Docker 미러 가이드: 5분 만에 pull 타임아웃 해결하기

2026-06 업데이트: Docker Hub 사용 제한과 pull-through cache에 관한 Docker 공식 문서에 맞춰 내용을 다시 조정했습니다. 이제는 특정 공개 미러 하나만 맹신하지 말고 먼저 네트워크 계층을 판단한 다음 커뮤니티 미러, HTTP 프록시, 기업 내부망 캐시 중에서 선택할 것을 권합니다. 놓치기 쉬운 변화도 하나 있습니다. Docker Hub는 2025년 4월 1일부터 pull 속도를 제한하고 있습니다(비로그인 IP당 시간당 10회, 무료 계정은 로그인 후 시간당 100회). 따라서 타임아웃이 아니라 429 오류가 발생했다면 미러를 급하게 바꾸기 전에 먼저 docker login을 실행해야 합니다.

지난주 금요일 오후 3시, 터미널의 docker pull nginx:latest 명령을 바라보고 있었습니다. 커서가 꼬박 10분 동안 깜박이다가 결국 빨간색 i/o timeout 오류를 내놓았습니다. 솔직히 처음 겪은 일도 아닙니다. 올해 6월부터 이런 일이 점점 잦아졌습니다. 네트워크에는 문제가 없고 브라우저에서 웹 페이지도 빠르게 열리는데 Docker 이미지만 내려받을 수 없었습니다.

인터넷의 튜토리얼을 두루 찾아보며 추천받은 Alibaba Cloud와 NetEase Cloud 미러를 설정했지만 여전히 소용이 없었습니다. 나중에야 2024년 6월 6일 중국 내 Docker 미러 가속기 대부분이 사실상 전멸했다는 사실을 알게 됐습니다. Alibaba Cloud, Tencent Cloud, Baidu Cloud뿐 아니라 여러 대학의 미러 사이트까지 서비스를 아예 중단했거나 내부망에서만 접속할 수 있게 바뀌었습니다.

혹시 이런 기분을 느껴 본 적이 있나요? 2023년에 작성된 ‘Docker 이미지 다운로드가 느린 문제를 완벽히 해결하는 방법’ 같은 튜토리얼을 보고 daemon.json을 그대로 설정한 다음 Docker를 재시작합니다. 기대에 차 다시 docker pull을 실행하지만 결과는 여전히 timeout입니다. 정말 답답한 일입니다.

다행히 아직 운영 중이고 직접 테스트해 사용할 수 있었던 커뮤니티 미러가 몇 곳 있습니다. 이 글에서는 2025년 12월 현재 어떤 Docker 미러를 사용할 수 있는지, daemon.json을 어떻게 설정하는지, 문제가 생겼을 때 어떻게 진단하는지 알려 드리겠습니다. 바로 시작하겠습니다.

Docker 미러가 대규모로 작동을 멈춘 이유

해결책을 알아보기 전에 무슨 일이 있었는지 먼저 짚을 필요가 있습니다. 잘 사용하던 Alibaba Cloud 미러가 아무 이유 없이 갑자기 중단됐을 리는 없기 때문입니다.

2024년 6월 6일은 분기점이었습니다. 그날부터 중국 내 주요 Docker Hub 미러 가속 서비스가 잇달아 서비스를 중단하거나 제한한다고 발표했습니다. Alibaba Cloud, NetEase Cloud, Tencent Cloud, Baidu Cloud 같은 대형 기업의 미러는 거의 하룻밤 사이에 모두 작동하지 않게 됐습니다. 난징대학교, 상하이교통대학교, 중국과학기술대학교 등이 운영하던 대학 미러 사이트도 폐쇄되거나 교내망 전용으로 바뀌었습니다.

솔직히 그 소식을 처음 봤을 때는 꽤 놀랐습니다. 여러 해 동안 사용한 미러가 갑자기 사라진 것입니다. 이후 알아보니 주된 원인은 정책과 비용이라는 이중 부담이었습니다. 한편으로는 규정 준수를 고려해야 했고, 다른 한편으로는 고가용성 미러 가속 서비스를 유지하는 데 실제로 많은 비용이 들었습니다.

지금 오래된 미러에 접속하면 404가 나오거나 연결 시간이 초과됩니다. daemon.json에 아직 registry.cn-hangzhou.aliyuncs.com이나 hub-mirror.c.163.com을 넣어 두었다면 사실상 설정하지 않은 것과 같습니다.

Docker Hub에 직접 연결하면 어떨까요? 기술적으로는 가능하지만 중국 내 네트워크 환경에서는 Docker Hub에 직접 접속하는 속도가 믿기 어려울 정도로 느립니다. 수백 MB짜리 이미지를 하나 받는 데 30분 이상 걸리고 timeout도 흔하게 발생합니다.

2025년 12월에도 사용할 수 있는 미러

대기업의 미러는 중단됐지만 일부 커뮤니티와 개인이 무료 Docker 이미지 가속 서비스를 계속 운영하고 있습니다. 최근 여러 서비스를 직접 테스트해 2025년 12월 현재 사용할 수 있는 미러 목록을 정리했습니다.

사용 가능한 미러 목록

중점 추천: 직접 사용해 본 결과 Xuanyuan 미러와 DaoCloud가 비교적 안정적이었습니다. Xuanyuan 미러의 무료 버전인 docker.xuanyuan.me도 이미 꽤 빠릅니다. 더 안정적인 서비스가 필요하다면 프로 버전에 가입해 사용해 보세요.

사용할 때 알아둘 점

1. 모두 커뮤니티가 자체 비용으로 운영하는 서비스입니다. 이전의 Alibaba Cloud나 Tencent Cloud처럼 대기업이 보장하는 서비스가 아니므로 언제든 중단될 수 있습니다. 소중히 사용하고 남용하지 마세요.

2. 모든 이미지를 가속할 수 있는 것은 아닙니다. 일부 미러는 nginx, mysql, redis 같은 자주 쓰는 베이스 이미지만 제공하거나 화이트리스트 제한을 둡니다. 잘 알려지지 않은 이미지를 받을 때 timeout이 발생한다면 미러 자체의 문제라고 단정하지 말고 다른 미러나 Docker Hub 직접 연결을 시도하세요.

3. 여러 미러를 설정하는 것이 좋습니다. daemon.json에는 여러 registry-mirrors를 설정할 수 있고 Docker가 순서대로 시도합니다. 첫 번째가 실패하면 자동으로 두 번째로 fallback하므로 성공률이 높아집니다.

참고로 이 미러 주소들은 GitHub의 dongyubin/DockerHub 프로젝트에서 찾았습니다. 이 저장소는 사용 가능한 미러 목록을 계속 업데이트하므로 북마크해 두는 것을 권합니다.

daemon.json 설정 따라 하기

미러 주소를 확보했으니 이제 설정할 차례입니다. JSON 파일 하나를 수정한 뒤 Docker 서비스를 재시작하면 됩니다. 세 가지 주요 운영체제로 나눠 설명하겠습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

Linux 시스템(가장 일반적)

서버와 개발 PC 대부분이 Linux이므로 가장 중요한 부분입니다.

1. 설정 파일 생성 또는 편집

설정 파일 경로: /etc/docker/daemon.json(파일이 없으면 새로 만듭니다.)

sudo mkdir -p /etc/docker
sudo vi /etc/docker/daemon.json

2. 설정 작성

아래 JSON을 복사해 넣습니다. 예비용으로 미러 세 개를 설정했습니다.

{
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io",
    "https://docker.1ms.run"
  ]
}

저장한 뒤 종료합니다(vi 편집기에서 ESC를 누르고 :wq를 입력한 뒤 Enter를 누릅니다).

3. Docker 서비스 재시작

sudo systemctl daemon-reload
sudo systemctl restart docker

첫 번째 명령은 systemd 설정을 다시 불러오고 두 번째 명령은 Docker를 재시작합니다. 두 명령을 모두 실행해야 하며, 그렇지 않으면 설정이 적용되지 않습니다.

macOS 시스템(Docker Desktop)

Mac을 사용한다면 Docker Desktop의 그래픽 설정 화면에서 더 간단하게 설정할 수 있습니다.

1. Docker Desktop 설정 열기

메뉴 막대에서 Docker 아이콘 → Settings(또는 Preferences)를 클릭합니다.

2. Docker Engine 설정 찾기

왼쪽 메뉴에서 Docker Engine을 선택하면 JSON 편집기가 표시됩니다.

3. JSON 설정 수정

JSON 설정에 registry-mirrors 필드를 추가합니다. 기존 설정이 있다면 쉼표를 넣는 것을 잊지 마세요.

{
  "registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ],
  "기존의 다른 설정": "변경하지 않음"
}

4. 적용 후 재시작

오른쪽 아래의 Apply & Restart 버튼을 클릭하면 Docker가 자동으로 재시작되고 설정이 적용됩니다.

Windows 시스템(Docker Desktop)

Windows의 설정 방법은 macOS와 거의 같으며 Docker Desktop의 그래픽 화면을 사용합니다.

1. 설정 열기

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

작업 표시줄의 Docker 아이콘을 마우스 오른쪽 버튼으로 클릭한 뒤 Settings를 선택합니다.

2. Docker Engine으로 이동

왼쪽 메뉴에서 Docker Engine을 선택합니다.

3. JSON 설정 수정

마찬가지로 registry-mirrors 필드를 추가하며 설정 내용은 macOS와 같습니다.

4. 적용 후 재시작

Apply & Restart를 클릭하고 Docker 재시작이 끝날 때까지 기다립니다.

설정 시 주의 사항

• JSON 형식이 올바른지 확인하세요. 가장 흔한 오류는 쉼표를 더 넣거나 빠뜨리는 것입니다. JSON 형식 검사 도구로 확인하는 것이 좋습니다.
• 중단된 미러를 설정하지 마세요. daemon.json에 Alibaba Cloud나 NetEase Cloud 주소가 남아 있다면 삭제하세요. 이제 사용할 수 없습니다.
• 예비 미러를 여러 개 설정하세요. 앞서 설명했듯 미러 하나만 사용하면 불안정할 수 있습니다. 예비 주소 2~3개를 설정하면 성공률을 높일 수 있습니다.

설정 적용 여부 확인

설정을 마친 뒤 곧바로 이미지를 받지 말고 먼저 설정이 적용됐는지 확인하세요. 설정이 잘못됐다면 다시 작업해야 하기 때문입니다.

방법 1: docker info 명령으로 확인

가장 빠른 검증 방법은 docker info 명령을 실행하고 Registry Mirrors 항목을 찾는 것입니다.

docker info | grep -A 5 "Registry Mirrors"

설정에 성공했다면 다음과 비슷한 출력이 표시됩니다.

Registry Mirrors:
  https://docker.xuanyuan.me/
  https://docker.m.daocloud.io/
  https://docker.1ms.run/

설정한 미러 주소가 보인다면 구성이 적용된 것입니다. 보이지 않는다면 daemon.json 형식이 올바른지, Docker 서비스를 재시작했는지 확인하세요.

방법 2: 이미지를 실제로 받아 테스트

설정만 확인해서는 충분하지 않습니다. 이미지를 실제로 받아 봐야 속도를 알 수 있습니다.

docker pull nginx:latest

nginx를 선택한 이유는 거의 모든 미러가 제공하는 가장 일반적인 베이스 이미지이기 때문입니다.

설정에 성공했다면 다운로드 진행률이 빠르게 올라가고 수십 초 만에 완료될 것입니다(nginx 이미지는 약 100MB가 조금 넘습니다). 이전에 10분 동안 기다리다 timeout이 발생했던 것과 비교하면 훨씬 빠르지 않나요?

방금 Xuanyuan 미러에서 nginx를 받아 테스트했는데 0%에서 100%까지 30초도 걸리지 않았습니다. 속도는 상당히 만족스러웠습니다.

그래도 매우 느리면 어떻게 하나요?

설정 후에도 속도가 느리거나 timeout이 계속된다면 당황하지 말고 아래의 자주 발생하는 문제 해결 방법을 확인하세요.

자주 발생하는 문제 해결

설정이 올바르더라도 때때로 예상치 못한 문제가 생깁니다. 직접 겪었던 문제와 해결책을 정리했으니 시행착오를 줄이는 데 도움이 되길 바랍니다.

문제 1: 설정 후 docker info에 미러가 표시되지 않음

증상: docker info | grep "Registry Mirrors"를 실행해도 아무 출력이 없거나 빈 값만 표시됩니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

가능한 원인과 해결 방법:

1. daemon.json 형식 오류 - 가장 흔한 원인입니다. JSON 형식은 매우 엄격하므로 쉼표 하나가 더 있거나 따옴표 하나가 빠져도 작동하지 않습니다.

   • 해결 방법: JSONLint 같은 도구로 daemon.json 형식이 올바른지 확인합니다.
   • 흔한 오류: 배열의 마지막 요소 뒤에 쉼표를 추가하거나 닫는 중괄호를 빠뜨리는 경우입니다.

2. Docker 서비스를 재시작하지 않음 - 설정 파일을 수정해도 재시작하지 않으면 적용되지 않습니다.

   • 해결 방법: Linux에서는 sudo systemctl restart docker를 실행하고 Docker Desktop에서는 Apply & Restart를 클릭합니다.

3. 파일 권한 문제 - daemon.json 파일 권한이 잘못돼 Docker가 읽을 수 없는 경우입니다.

   • 해결 방법: sudo chmod 644 /etc/docker/daemon.json을 실행해 파일 권한을 변경합니다.

문제 2: 설정 후에도 timeout 발생

증상: docker info에는 미러가 정상적으로 표시되지만 docker pull은 여전히 시간 초과됩니다.

가능한 원인과 해결 방법:

1. 다운로드하려는 이미지가 가속기 화이트리스트에 없음 - 앞서 설명했듯 모든 이미지를 가속할 수 있는 것은 아닙니다.

   • 해결 방법: nginx, redis 같은 일반적인 이미지를 받아 테스트합니다. 이런 이미지를 받을 수 있다면 설정에는 문제가 없으므로 다른 미러나 프록시를 사용하세요.

2. 미러가 일시적으로 작동하지 않음 - 커뮤니티 미러는 트래픽 부담이나 유지보수로 잠시 사용할 수 없을 수 있습니다.

   • 해결 방법: daemon.json에 여러 미러를 설정하면 Docker가 자동으로 fallback합니다. 또는 잠시 기다렸다 다시 시도하세요.

3. 로컬 네트워크 문제 - 방화벽, 프록시 설정, DNS 조회가 모두 문제를 일으킬 수 있습니다.

   • 해결 방법: ping docker.xuanyuan.me를 실행해 ping이 통하는지 확인하고 방화벽 규칙도 검사합니다.

문제 3: Docker 서비스 재시작 실패

증상: systemctl restart docker 실행 후 오류가 발생하고 Docker가 시작되지 않습니다.

가능한 원인과 해결 방법:

1. daemon.json 오류로 Docker 시작 실패 - JSON 형식이 잘못되면 Docker 서비스를 시작할 수 없습니다.
   • 해결 방법: journalctl -u docker.service로 Docker 로그를 확인해 오류 메시지를 찾습니다.
   • 긴급 복구: daemon.json의 이름을 바꾸거나 파일을 삭제한 뒤 Docker를 재시작해 서비스를 먼저 복구하고 설정 문제를 차근차근 확인합니다.

sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo systemctl restart docker

문제 4: 일부 특수 이미지를 받을 수 없음

증상: nginx, redis 같은 일반적인 이미지는 받을 수 있지만 특정 프로젝트의 사설 이미지나 특정 registry 이미지는 받지 못합니다.

해결 방법:

• 이미지 가속기는 Docker Hub의 공개 이미지에만 적용됩니다. 이미지가 gcr.io, quay.io 같은 사설 registry에 있다면 가속기가 도움이 되지 않습니다.
• 이런 경우 다음 방법을 고려할 수 있습니다.
  1. HTTP 프록시 설정: daemon.json에 http-proxy와 https-proxy를 설정합니다.
  2. VPN 또는 프록시 서비스를 사용합니다.
  3. 중국 내 이미지 미러링 사이트를 찾습니다(일부 커뮤니티는 gcr.io 이미지를 미러링합니다).

그래도 해결되지 않을 때의 대안

위의 모든 방법을 시도해도 해결되지 않는다면 다음 방법을 고려할 수 있습니다.

1. Docker 프록시 사용 - daemon.json에 HTTP 프록시를 설정해 Docker가 프록시를 통해 외부 네트워크에 접속하도록 합니다.
2. 로컬 사설 이미지 저장소 구축 - Harbor 같은 도구로 사설 저장소를 구축하고 필요한 이미지를 수동으로 동기화합니다.
3. 다른 시간에 다시 시도 - 네트워크 사용량이 많은 시간대의 문제일 수 있으므로 다른 시간에 시도하면 해결될 수 있습니다.

문제가 생겨도 당황하지 마세요. 어느 단계에서 문제가 발생했는지 차분하게 분석하고 하나씩 확인하면 분명 해결할 수 있습니다.

결론

여기까지 핵심 내용을 거의 모두 살펴봤습니다. 간단히 정리하면 다음과 같습니다.

핵심 요점:

• 2024년 6월 6일 이후 Alibaba Cloud, NetEase Cloud, Tencent Cloud 등 주요 Docker 미러가 모두 작동을 멈췄습니다.
• 현재 사용할 수 있는 미러는 Xuanyuan 미러, DaoCloud처럼 주로 커뮤니티가 운영하는 서비스입니다.
• daemon.json 파일을 수정해 registry-mirrors 설정을 추가한 다음 Docker를 재시작하면 됩니다.
• 성공률을 높이려면 여러 미러를 예비용으로 설정하세요.
• 문제가 발생하면 먼저 JSON 형식, Docker 서비스 상태, 네트워크 연결을 확인하세요.

커뮤니티 미러가 이전의 대기업 서비스만큼 안정적이지는 않지만 당장의 문제는 해결할 수 있습니다. 솔직히 이 미러들이 언제까지 운영될지는 저도 모릅니다. 앞서 언급한 GitHub 프로젝트(dongyubin/DockerHub)를 북마크해 두는 것이 좋습니다. 사용 가능한 미러 목록이 계속 업데이트됩니다.

이 글로 Docker 이미지 다운로드가 느린 문제를 해결했다면 같은 문제를 겪는 다른 분들에게도 공유해 주세요. 문제가 있다면 댓글로 남겨 주세요. 확인하는 대로 답변하겠습니다.

마지막으로 한 번 더 말씀드립니다. 커뮤니티가 자체 비용으로 운영하는 무료 리소스를 소중히 사용하고 남용하지 마세요. 누구에게나 쉽지 않은 일입니다.

2026년 가용성 판단표

더 읽어보기: 이미지 문제를 관측 가능한 절차로 바꾸기

• Docker Hub 공식 사용 및 제한 문서
• Docker 미러 속도 테스트와 자동 전환
• Docker에서 호스트 네트워크에 접근하는 방법
• Docker 로그 관리 및 문제 해결