docs(gitea): expand DNS troubleshooting for act_runner clone hangs

Document root cause (Docker embedded DNS 127.0.0.11 forwarding flakiness
on QNAP), permanent fix (--dns-search .), and three alternatives
(host network, dockerd daemon.json, pre-warm action cache).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitea/gitea_compose_qnap_all_in_one.md

@@ -235,6 +235,76 @@ Zusätzlich: QNAP **Storage & Snapshots** → Volume-Snapshots für `/share/Cont
 - Fehler `docker: command not found` → Job-Container hat kein Docker-CLI. Runner-Label muss ein Image verwenden, das `docker` mitbringt (z.B. `catthehacker/ubuntu:act-latest`). `node:*`-Images reichen nicht, weil dort nur Node installiert ist
 - Fehler `Get "https://github.com/..." ... dial tcp: lookup github.com on 127.0.0.11:53: server misbehaving` → Docker-interner DNS im `gitea_gitea`-Netz forwarded unzuverlässig. Fix: `container.options: "--dns 8.8.8.8 --dns 1.1.1.1"` in der Runner-Config setzen, damit Job-Container externen DNS direkt nutzen
 
+**DNS-Timeouts / hängende `git clone` ohne Fehlermeldung:**
+
+Symptom: Job steht minutenlang bei `cloning https://github.com/actions/checkout` bzw. `actions/setup-node` ohne weiteren Output; kein `server misbehaving`, kein Timeout. Gleichzeitig scheitern parallele Jobs im selben Run sporadisch sofort mit `lookup github.com on 127.0.0.11:53: server misbehaving`.
+
+Ursachen (mehrere verketten sich):
+
+1. `127.0.0.11` ist Dockers embedded DNS-Resolver. Er forwarded an die Upstream-Resolver der Docker-Daemon-Config. Auf QNAP ist dieser Upstream häufig ein (langsamer/überlasteter) ISP-DNS oder fehlschlagender Provider-Resolver.
+2. `--dns 8.8.8.8 --dns 1.1.1.1` in `container.options` injiziert die DNS-Server in `/etc/resolv.conf` **innerhalb** des Job-Containers — das behebt `server misbehaving`, aber nur wenn der Daemon die Option korrekt anwendet (`act_runner` ≥ 0.2.11).
+3. Parallele Job-Starts erzeugen kurzzeitig 5–10 gleichzeitige DNS-Lookups → Upstream drosselt → hängende TCP-Connects ohne sauberes Fail.
+
+**Dauerhafter Fix:**
+
+```yaml
+# config.yaml des act_runner
+container:
+  network: gitea_gitea
+  options: "--dns 8.8.8.8 --dns 1.1.1.1 --dns-search ."
+  # `--dns-search .` entfernt jede geerbte Search-Domain → keine verirrten NXDOMAIN-Retries
+```
+
+**Alternative 1 — Host-Network:**
+
+```yaml
+container:
+  network: host
+  # options: "" entfernen, --dns ist dann irrelevant
+```
+
+Nachteil: Jobs können auf Host-Ports zugreifen (Security-Impact bei Multi-Tenant).
+
+**Alternative 2 — Dockerd default-dns fixieren (macht auch andere Container robuster):**
+
+In `/etc/docker/daemon.json` auf dem QNAP:
+
+```json
+{
+  "dns": ["8.8.8.8", "1.1.1.1", "9.9.9.9"],
+  "dns-opts": ["ndots:1", "timeout:2", "attempts:3"]
+}
+```
+
+Dann Docker-Daemon restart (Container Station → Advanced → Restart Docker). Wirkt auf alle Container, auch ohne `--dns`-Option pro Job.
+
+**Alternative 3 — Pre-warm der Action-Repos (umgeht den Clone):**
+
+`act_runner` cached bereits geklonte Action-Repos unter `/data/cache/actions`. Einmal manuell anstoßen:
+
+```bash
+docker exec -it act_runner sh -c '
+  mkdir -p /data/cache/actions/github.com/actions &&
+  cd /data/cache/actions/github.com/actions &&
+  git clone --depth 1 --branch v4 https://github.com/actions/checkout &&
+  git clone --depth 1 --branch v4.0.4 https://github.com/actions/setup-node &&
+  git clone --depth 1 --branch v4 https://github.com/actions/cache &&
+  git clone --depth 1 --branch v4 https://github.com/actions/upload-artifact
+'
+```
+
+Danach laufen Jobs ohne DNS-Dependency zu github.com durch (solange der Cache nicht gelöscht wird).
+
+**Debug-Check:**
+
+```bash
+# DNS aus Job-Container-Sicht verifizieren
+docker run --rm --network gitea_gitea --dns 8.8.8.8 alpine:3 \
+  sh -c 'apk add --no-cache bind-tools && dig +short github.com'
+```
+
+Liefert das sofort eine IP, ist DNS OK. Hängt es → DNS-Upstream-Problem (Alternative 2 oder 3 nötig).
+
 **`uses: actions/checkout@v4` schlägt fehl:**
 
 - `GITEA__actions__DEFAULT_ACTIONS_URL=https://github.com` gesetzt?