mirror of
https://github.com/NoFxAiOS/nofx.git
synced 2026-07-14 08:16:56 +08:00
docs: Add Docker image pull failure troubleshooting (China)
Added comprehensive troubleshooting guide for Docker image pull failures in mainland China, based on Issue #168. Problem: - Users in China cannot pull Docker images from Docker Hub - ERROR: load metadata for docker.io/library/... - Timeouts and connection failures Solutions Added: 1. Configure Docker registry mirrors (Recommended) - List of working China mirrors - Step-by-step configuration for Linux/macOS/Windows - Verification commands 2. Use VPN - Taiwan nodes recommended - Global mode required 3. Offline image download - Image proxy websites - Manual import instructions Both English and Chinese versions updated. Fixes: #168 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: tinkle-community <tinklefund@gmail.com>
This commit is contained in:
@@ -138,6 +138,98 @@ Look at the AI's Chain-of-Thought reasoning section.
|
||||
|
||||
### 3. Connection & API Issues
|
||||
|
||||
#### ❌ Docker Image Pull Failed (China Mainland)
|
||||
|
||||
**Error:** `ERROR [internal] load metadata for docker.io/library/...`
|
||||
|
||||
**Symptoms:**
|
||||
- `docker compose build` or `docker compose up` hangs
|
||||
- Timeout errors: `timeout`, `connection refused`
|
||||
- Cannot pull images from Docker Hub
|
||||
|
||||
**Root Cause:**
|
||||
Access to Docker Hub is restricted or extremely slow in mainland China.
|
||||
|
||||
**Solution 1: Configure Docker Registry Mirror (Recommended)**
|
||||
|
||||
1. **Edit Docker configuration file:**
|
||||
```bash
|
||||
# Linux
|
||||
sudo nano /etc/docker/daemon.json
|
||||
|
||||
# macOS (Docker Desktop)
|
||||
# Settings → Docker Engine
|
||||
```
|
||||
|
||||
2. **Add China registry mirrors:**
|
||||
```json
|
||||
{
|
||||
"registry-mirrors": [
|
||||
"https://docker.m.daocloud.io",
|
||||
"https://docker.1panel.live",
|
||||
"https://hub.rat.dev",
|
||||
"https://dockerpull.com",
|
||||
"https://dockerhub.icu"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
3. **Restart Docker:**
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl restart docker
|
||||
|
||||
# macOS/Windows
|
||||
# Restart Docker Desktop
|
||||
```
|
||||
|
||||
4. **Rebuild:**
|
||||
```bash
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Solution 2: Use VPN**
|
||||
|
||||
1. Connect to VPN (Taiwan nodes recommended)
|
||||
2. Ensure **global mode** instead of rule-based mode
|
||||
3. Re-run `docker compose build`
|
||||
|
||||
**Solution 3: Offline Image Download**
|
||||
|
||||
If above methods don't work:
|
||||
|
||||
1. **Use image proxy websites:**
|
||||
- https://proxy.vvvv.ee/images.html (offline download available)
|
||||
- https://github.com/dongyubin/DockerHub (mirror list)
|
||||
|
||||
2. **Manually import images:**
|
||||
```bash
|
||||
# After downloading image files
|
||||
docker load -i golang-1.25-alpine.tar
|
||||
docker load -i node-20-alpine.tar
|
||||
docker load -i nginx-alpine.tar
|
||||
```
|
||||
|
||||
3. **Verify images are loaded:**
|
||||
```bash
|
||||
docker images | grep golang
|
||||
docker images | grep node
|
||||
docker images | grep nginx
|
||||
```
|
||||
|
||||
**Verify registry mirror is working:**
|
||||
```bash
|
||||
# Check Docker info
|
||||
docker info | grep -A 10 "Registry Mirrors"
|
||||
|
||||
# Should show your configured mirrors
|
||||
```
|
||||
|
||||
**Related Issue:** [#168](https://github.com/tinkle-community/nofx/issues/168)
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Backend Won't Start
|
||||
|
||||
**Error:** `port 8080 already in use`
|
||||
|
||||
Reference in New Issue
Block a user