How can I bypass Docker Hub access and use Chinese mirrors instead?

The root of the problem is that even though you’ve configured registry mirrors, Docker still relies on the default Docker Hub endpoint (specifically https://registry-1.docker.io) for parts of its workflow (for example, obtaining access tokens). In short, the mirror configuration only “redirects” image pulls once the flow has started, but the initial authentication request still goes to docker.io. This behavior means that if the GFW is blocking access to docker.io (or its subdomains), then Docker’s workflow will fail even though you have working mirrors.

There are two common workarounds:

1. DNS Interception or Redirection with a Local Reverse Proxy
   You can set up a local reverse proxy (for example, with nginx or a similar tool) that listens on port 443 for the hostname registry-1.docker.io. Then configure your DNS (or use dnsmasq) to resolve registry-1.docker.io to the IP address of your reverse proxy. The proxy would then forward requests to one of the available mirrors.
   Note:
   • Be aware that since TLS is in place, the certificate presented by your proxy must be valid for registry-1.docker.io (or you'll get TLS errors). One common solution is to run the proxy as an insecure registry (configured in Docker with the "insecure-registries" parameter), but that has its own security implications.
   • This approach essentially “tricks” Docker into thinking it is talking to Docker Hub while you are instead proxying to a mirror.

2. Custom Local Mirror Endpoint
   Instead of relying on the default Docker Hub address, you could set up your own private local registry mirror. Once you have a locally hosted registry (or a forwarded mirror) with a valid certificate and proper configuration, you can reference it explicitly when pulling images or by retagging images from the mirror.
   For example, if your mirror’s base URL is mirror.example.cn, then instead of

   docker pull library/ubuntu:latest
   

   you would pull with

   docker pull mirror.example.cn/library/ubuntu:latest
   

   This approach bypasses the need for Docker to automatically contact docker.io for token authentication.
   Note:
   • This requires you to keep the mirror synchronized and configure your workflows to use the local endpoint.
   • It may not be as transparent as the official registry-mirror configuration.

Why the Registry Mirrors Setting Isn’t Enough

Even though your /etc/docker/daemon.json shows mirrors are configured, Docker’s internal flow does two things:

• It first contacts registry-1.docker.io (or related endpoints) to obtain authentication tokens.
• It then tries fetching the image, at which point the mirror should kick in.

Since the first step is failing, the entire image pull fails. Simply adding /etc/hosts entries for docker.io does not work if you don’t cover subdomains like registry-1.docker.io (and even if you do, the TLS handshake will most likely fail unless you also handle the certificate validation).

Recommended Steps

1. Use a Reverse Proxy:

   • Set up a reverse proxy (e.g., nginx) that listens for requests on registry-1.docker.io and forwards them to one of your mirrors.
   • Configure your local DNS (or modify /etc/hosts for testing) so that registry-1.docker.io resolves to the reverse proxy’s IP.
   • Optionally configure Docker to treat the proxy as an insecure registry if you cannot satisfy TLS certificate requirements.

   A sample nginx configuration (assuming you use it as an insecure proxy) might look like this:

   NGINXCopied
   server {
       listen 443;
       server_name registry-1.docker.io;
       
       # Use a self-signed or internal cert (or disable cert checking in Docker)
       ssl_certificate     /path/to/cert.pem;
       ssl_certificate_key /path/to/key.pem;
   
       location / {
           proxy_pass https://registry.docker-cn.com;
           proxy_set_header Host registry-1.docker.io;
       }
   }

   Then update your /etc/hosts:

   192.168.X.Y registry-1.docker.io
   

   Replace 192.168.X.Y with the IP address of your reverse proxy.

2. Or Use a Local Mirror Endpoint Explicitly:

   • Mirror your desired images to a local registry and re-tag them so they can be pulled directly from your local mirror.

Conclusion

Due to Docker’s design, the configured mirrors are only used after the initial authentication step, which still contacts Docker Hub. To work around a blocked Docker Hub, you must either intercept/redirect those authentication calls (using DNS and a reverse proxy) or bypass the default behavior entirely by using your own registry endpoint in your pull commands.