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:
Liu Xiang Qian
2025-11-02 11:38:53 +08:00
parent df7386c028
commit aca0af519d
2 changed files with 184 additions and 0 deletions

View File

@@ -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`