How to Speed Up Docker Image Pulls in China: Mirrors, Proxies, and Registry Hacks

Problem

Pulling Docker images from public registries in mainland China often suffers from slow speeds, intermittent disconnections, and rate‑limiting for anonymous users due to network restrictions.

Solution Overview

Three main ways to improve pull performance:

Configure one or more domestic Docker registry mirrors.

Deploy a self‑hosted registry mirror or proxy (e.g., Cloudflare Workers).

Configure the Docker daemon to use an upstream HTTP/HTTPS proxy.

Authenticate to registries with docker login to avoid anonymous limits.

Domestic Registry Mirrors

As of 2023‑09‑05 the following mirrors are reachable (replace with the actual domain you prefer):

Alibaba Cloud: xxxxx.mirror.aliyuncs.com DockerProxy: dockerproxy.com Baidu Cloud: mirror.baidubce.com DaoCloud: docker.m.daocloud.io Nanjing University: docker.nju.edu.cn Shanghai Jiao Tong University: docker.mirrors.sjtug.sjtu.edu.cn Test a mirror with a pull, for example:

docker pull dockerproxy.com/library/nginx

Configure Mirrors in Docker Daemon

Create or edit /etc/docker/daemon.json and add the desired URLs:

{
  "registry-mirrors": [
    "https://your-mirror-aliyun.mirror.aliyuncs.com",
    "https://dockerproxy.com",
    "https://mirror.baidubce.com",
    "https://docker.m.daocloud.io",
    "https://docker.nju.edu.cn",
    "https://docker.mirrors.sjtug.sjtu.edu.cn"
  ]
}

Reload the daemon and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Self‑Hosted Mirror / Proxy with Cloudflare Workers

The open‑source cloudflare-docker-proxy project (GitHub: https://github.com/ciiiii/cloudflare-docker-proxy) can be used to run a lightweight proxy that forwards Docker requests to the official registries.

Fork the repository.

Deploy the worker (adjust the Deploy button URL to point to your fork).

Edit src/index.js and modify the const routes array to include the domains you want to proxy (e.g., docker, quay, gcr).

Click the Deploy button to create the Worker.

Add a CNAME record in Cloudflare DNS that points your custom domain to workername.username.workers.dev.

In the Workers dashboard, add an HTTP route such as example.com/* that maps to the deployed worker.

After deployment, use the custom domain as a Docker registry mirror.

Docker Daemon Proxy Configuration

If you prefer to route all Docker traffic through an upstream proxy, add a proxies section to /etc/docker/daemon.json:

{
  "proxies": {
    "http-proxy": "http://your-proxy-ip:7890",
    "https-proxy": "http://your-proxy-ip:7890",
    "no-proxy": "*.cn,127.0.0.0/8,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8"
  }
}

Reload and restart Docker as shown above. The no-proxy field accepts CIDR notation.

Authentication to Registries

Create accounts on the registries you need (Docker Hub, Quay.io, GHCR.io, GCR.io, etc.) and log in:

docker login --username your-username --password-stdin

For scripted login, pipe the password:

echo "your-password" | docker login --username your-username --password-stdin

You can also store credentials directly in ~/.docker/config.json:

{
  "auths": {
    "ghcr.io": {"auth": "base64-encoded-credentials"},
    "https://index.docker.io/v1/": {"auth": "base64-encoded-credentials"},
    "quay.io": {"auth": "base64-encoded-credentials"}
  }
}

Generate the base64 string with:

echo -n "your-username:your-password" | base64

References

cloudflare-docker-proxy – https://github.com/ciiiii/cloudflare-docker-proxy

Docker mirror test CI – https://github.com/docker-practice/docker-registry-cn-mirror-test/actions