Fehlerbehebung

Zielgruppe: Ops im Vor-Ort-Einsatz. Die Einträge folgen dem Muster Symptom → Ursachen → Prüfung → Fix. Jeder Befehl ist so, dass du ihn direkt ins Terminal paste kannst.

Für systemische Referenzen siehe deployment.md, upgrade.md, backup-and-restore.md.

Inhaltsverzeichnis

Container / Host
DNS & TLS
WireGuard
Home-Gateway
RDP
Datenbank
Logging & Debugging
Bekannte Ops-Gotchas
Wann um Hilfe fragen

Container / Host

GateControl-Container startet nicht / crasht nach Start

Ursachen:

.env fehlt oder enthält ungültige Pflichtwerte (GC_ADMIN_PASSWORD, GC_WG_HOST).
Port 53 auf 127.0.0.1 ist belegt (anderer DNS-Resolver auf dem Host).
Port 80/443/51820 sind von einem anderen Dienst belegt.
Docker-Volume korrumpiert (seltene SQLite-Lock-Leaks).
Neue Version hat ein Migrations-Problem (siehe upgrade.md §10).

Prüfung:

docker logs --tail 100 gatecontrol

Such nach:

ERROR: GC_ADMIN_PASSWORD is not set or still default → .env prüfen.
ERROR: GC_WG_HOST is not set or still the example value → .env prüfen.
ERROR: 127.0.0.1:53 is already bound — dnsmasq cannot start → Port-53-Holder:
```
ss -lntup | grep ':53 '
```
Typische Kandidaten: named/bind9, unbound, dnsmasq (aus NetworkManager oder libvirt), pihole direkt auf dem Host.
Error: SQLITE_CORRUPT → aus Backup restoren (siehe backup-and-restore.md).

Fix:

Nach Env-Änderung: docker compose up -d --force-recreate gatecontrol.
Port-Konflikt: gegen-Prozess stoppen oder auf andere Ports mappen (bei GateControl nicht ohne Weiteres möglich — siehe network_mode: host).

Wenn der Container loopt und du nichts Konkretes siehst:

docker inspect gatecontrol --format '{{ .State.Status }} — exit {{ .State.ExitCode }} — {{ .State.Error }}'

Health-Check bleibt auf `starting`

Ursachen:

Caddy wartet noch auf Zertifikate (erster Start, Let's-Encrypt-HTTP-01 läuft).
Datenbank-Migrations dauern (große Bestands-DB, Index-Rebuild).
Node hängt bei Init-Schritt (z. B. DNS-Hosts-File-Build).

Prüfung:

docker logs --tail 50 gatecontrol
docker exec gatecontrol curl -s http://127.0.0.1:3000/health

checks.db: false → Migrations nicht durch, weiter im Log schauen. checks.wireguard: false → wg0 ist noch nicht oben, wg show wg0 sollte das bestätigen.

Fix:

Erst 60–90 Sekunden warten. Wenn der Zustand stabil bleibt, vermutlich Fehlerzustand — siehe oben.

Hohe CPU/RAM-Last

Ursachen:

Uptime-Monitoring läuft auf vielen Zielen mit kurzem Intervall.
Request-Tracing (debug_enabled) ist auf einer Route mit viel Traffic an.
Traffic-Snapshot-Interval zu kurz (GC_TRAFFIC_INTERVAL).
Zu viele gleichzeitige Caddy-Reloads (jeder Peer/Route-Save triggert einen /load).

Prüfung:

docker stats gatecontrol --no-stream
docker exec gatecontrol top -b -n 1 | head -20

Process-Namen im Output: node (Admin-Server), caddy, dnsmasq, wg-quick, supervisord. Wer über 60 % CPU sustained braucht, ist der Ausreißer.

node hoch → in UI prüfen welche Routen debug_enabled=1 haben und notfalls einzeln ausschalten. caddy hoch → viele aktive Verbindungen/Uptime-Checks — /api/v1/caddy/status schauen.

Fix:

Monitoring-Intervalle hochdrehen (Default 60 s ist konservativ, unter 15 s problematisch).
debug_enabled ausschalten wenn fertig debuggt.
GC_TRAFFIC_INTERVAL auf 120 s setzen.

DNS & TLS

Zertifikat wird nicht ausgestellt

Ursachen (die häufigsten):

DNS-Record zeigt nicht auf die Server-IP oder ist noch nicht propagiert.
Cloudflare-Proxy-Mode (orange Wolke) ist an und HTTP-01-Challenge wird abgefangen.
Port 80 ist vom Host blockiert (ufw) oder von einem anderen Dienst belegt.
Let's-Encrypt-Rate-Limit getroffen (50 Cert/Woche pro Domain).
GC_CADDY_EMAIL ist leer — Caddy nutzt dann ZeroSSL-Fallback, wenn ZeroSSL-Account nicht registrierbar ist, kein Cert.

Prüfung:

# DNS
dig +short A gate.example.com

# Port 80 von außen
curl -I http://gate.example.com/.well-known/acme-challenge/test

# Caddy-interner Zustand
docker exec gatecontrol curl -s http://127.0.0.1:2019/config/ | jq '.apps.tls'

# Caddy-Log (ACME-Events)
docker logs gatecontrol 2>&1 | grep -i acme | tail -20

Fix:

Cloudflare-Proxy: orange → grau, dann Caddy neu laden:

docker exec gatecontrol caddy reload --config /app/config/Caddyfile

Für Staging-Tests (kein Rate-Limit-Risiko): in .env GC_CADDY_ACME_CA=https://acme-staging-v02.api.letsencrypt.org/directory.
Rate-Limit getroffen: 7 Tage warten oder DNS-Challenge einrichten (out of scope hier).

Weiterführend: siehe Caddy-Server-Log + /data/caddy/ für lokale ACME-State-Dateien.

Admin-UI nicht erreichbar obwohl Container healthy

Ursachen:

Caddy läuft, aber das Routing für den Admin-Host ist kaputt (externe Custom-Route auf die Admin-Domain gelegt).
Firewall blockt Port 443 auf Host-Ebene.
DNS-Record zeigt noch auf den alten Server.

Prüfung:

# Von innen
docker exec gatecontrol curl -sk https://localhost/ -I
# Sollte 200/301 vom Node-Admin geben.

# Von außen
curl -I https://gate.example.com/

# Caddy-Routen
docker exec gatecontrol curl -s http://127.0.0.1:2019/config/ \
  | jq '.apps.http.servers'

Fix:

Wenn jemand versehentlich die Admin-Domain als Custom-Route angelegt hat: in der UI oder direkt in der DB die Route löschen und Caddy neu laden.
Für ufw: siehe deployment.md §10.

Routen geben 502

Ursachen:

Backend (Target-IP:Port) ist nicht erreichbar.
Backend ist nur über VPN erreichbar und der referenzierte Peer hat keinen Handshake.
Backend verlangt HTTPS, Route ist aber auf HTTP konfiguriert (oder umgekehrt).
Health-Check-Failure schaltet die Route hart auf "down".

Prüfung:

# Von innen Richtung Backend testen
docker exec gatecontrol curl -v http://<target-ip>:<port>/

# Wenn Backend per Peer → Peer-Handshake prüfen
docker exec gatecontrol wg show wg0 latest-handshakes

# Caddy-Log für 502
docker logs gatecontrol 2>&1 | grep -E 'dial|502|upstream' | tail -20

Fix:

Peer erst online bringen (siehe "Handshake schlägt fehl" weiter unten).
Wenn Backend-HTTPS: in Route-Config Backend HTTPS aktivieren und backend_tls_insecure setzen falls Selbstsigniert.
Health-Check-Failure per UI checken (Route-Detail → Uptime-Status).

WireGuard

Peer kriegt keine IP / Config fehlerhaft

Ursachen:

Peer wurde in UI angelegt, aber Server hat die Config noch nicht reloadet.
Allowed-IPs-Konflikt (zwei Peers auf derselben IP).
GC_WG_SUBNET falsch konfiguriert — VPN-Subnetz und Peer-IP-Block passen nicht.

Prüfung:

docker exec gatecontrol wg show wg0
docker exec gatecontrol cat /etc/wireguard/wg0.conf | grep -A 2 AllowedIPs

Fix:

In der UI Peer neu speichern → triggert einen wg syncconf.
Bei IP-Konflikten: Peer-IPs in der UI neu vergeben.

Handshake schlägt fehl

Symptome: Peer sagt "verbunden", aber wg show wg0 zeigt bei dem Peer latest handshake: 0 oder "(none)", transfer: 0 B received.

Ursachen:

Port 51820/UDP auf Server-Firewall blockiert.
Symmetrisches NAT beim Client (Mobilfunk-Carrier).
MTU-Problem — Handshake funktioniert, aber Daten-Pakete werden fragmentiert und fallen.
Client hat falschen Public-Key oder Endpunkt.

Prüfung:

# Port-Test vom Client
nc -uvz gate.example.com 51820

# Server-Firewall
iptables -L INPUT -n -v | grep 51820
ufw status | grep 51820

# Paket-Capture auf dem Server
docker exec gatecontrol tcpdump -ni any udp port 51820 -c 20

# MTU auf wg0
docker exec gatecontrol ip link show wg0

Fix:

UDP 51820 in ufw/iptables freigeben: ufw allow 51820/udp.
MTU runter: GC_WG_MTU=1380 in .env, Container recreate, Client-Config neu verteilen.
Client-seitig: Endpunkt + Server-Public-Key gegen UI abgleichen.

Peer ist online, aber kein Traffic

Symptome: wg show zeigt Handshake, transfer zählt hoch. Aber Client sagt "kein Internet/keine Server-Erreichbarkeit".

Ursachen:

MASQUERADE-Regel fehlt oder zeigt auf falsches Interface.
net.ipv4.ip_forward = 0 (sehr selten — entrypoint.sh dreht das hoch, aber eingeschränkte Host-Namespaces können das überschreiben).
Split-Tunnel-Config auf dem Client lässt 0.0.0.0/0 aus.

Prüfung:

docker exec gatecontrol iptables -t nat -L POSTROUTING -n -v | grep 10.8.0
docker exec gatecontrol sysctl net.ipv4.ip_forward
# Soll: net.ipv4.ip_forward = 1
docker exec gatecontrol ip route get 1.1.1.1

Ist das Interface in der MASQUERADE-Regel (-o eth0 oder -o ens18) das tatsächliche Egress-Interface? ip route zeigt das Default-Interface. Stimmt das nicht überein, greift NAT nicht.

Fix:

GC_NET_INTERFACE explizit setzen (Default ist auto-detect). Wert muss mit ip route show default übereinstimmen.
entrypoint.sh rewrited existierende wg0.conf-PostUp-Regeln beim Start, wenn das Interface nicht mehr existiert — siehe Zeile 149 ff.
Bei Synology/OVH: oft ist das Interface ens18 oder eth0.VLAN, nicht plain eth0.

Multiple-VPN-Konflikte

Symptom: Client verbindet sich, hat aber parallel noch eine andere VPN/DNS-Verbindung aktiv (Corporate-VPN, Tailscale, …). Folge: DNS-Auflösung zeigt inkonsistent, API-Hostname löst auf die falsche IP.

Ursache: Android/iOS-Client cacht den alten DNS-Eintrag über den Tunnel- Wechsel hinweg.

Fix:

Client-Seite: VPN vor dem GateControl-Connect beenden und DNS-Cache flushen.
GateControl-Android-Client-Codebase löst das programmatisch mit preResolveDns() vor Tunnel-Start und vpnSafeDns in OkHttp — das ist Client-Seite, nicht Server-Seite. Aber gut zu wissen beim Debug.

Home-Gateway

Ein Home-Gateway ist ein separater Docker-Container, der auf einer NAS/RPi/Mini-PC im Heimnetz läuft und einen ausgehenden Tunnel zum GateControl-Server aufbaut. Konzept: concepts/home-gateway.md.

Gateway-Card bleibt "offline" trotz laufendem Container

Ursache (seit v1.50.1 gefixt, aber relevant für ältere Instanzen): Früher hat die UI eigene Self-Check-Flags als Wahrheit genommen; seit v1.50.1 ist route_reachability (empirisch aus gemessenem Traffic) der Primärwert.

Wenn's heute noch "offline" zeigt:

Heartbeat kommt nicht an.
route_reachability ist veraltet.

Prüfung:

# Gateway-Peers + letzter Heartbeat
docker exec gatecontrol sqlite3 /data/gatecontrol.db <<'SQL'
SELECT p.name, p.peer_type, gm.last_seen_at, gm.last_config_hash, gm.last_health
FROM peers p
LEFT JOIN gateway_meta gm ON gm.peer_id = p.id
WHERE p.peer_type = 'gateway';
SQL

# WireGuard-Handshake
docker exec gatecontrol wg show wg0 latest-handshakes

Fix:

Wenn Heartbeat NULL oder alt ist: am Gateway-Host die Companion-Logs prüfen (docker logs gateway). Typisch: Token revoked oder GC_BASE_URL in Gateway-.env falsch.
Wenn Handshake vor kurzem, Heartbeat aber alt: Gateway-Container startet zyklisch neu — Logs am Gateway-Host prüfen.

Config-Hash out of sync

Symptom: UI zeigt "Gateway konfiguration nicht synchron" oder die Heartbeat-Response enthält Hash-Mismatch-Warnungen.

Ursache: Caddy-/load-Race bei schneller Änderung der L4-Routen am Server. Der Server rechnet den Hash vor dem Push, Caddy committet asynchron, Gateway hat zwischendurch den alten Hash gesehen.

Self-Heal: Der Server reconciled automatisch nach 60 s (bei jedem Heartbeat-Zyklus, der ein Mismatch sieht). Wenn nach 2 Minuten nicht aufgelöst:

Prüfung:

# Server-Sicht
docker exec gatecontrol curl -s http://127.0.0.1:3000/api/v1/gateways \
  -H "Cookie: <admin-session>" | jq '.[].config_hash_status'

Fix:

Auf dem Server: kleines Edit an beliebiger L4-Route speichern → erzwingt einen Full-Config-Push.
Zuletzt: Gateway-Container neu starten (docker compose restart gateway am NAS).

Heartbeat kommt nicht an

Ursachen:

WG-Tunnel zum Gateway ist down (Handshake seit > 3 min).
Gateway-Token revoked oder ausgelaufen.
Firewall am Server blockt Heartbeat-HTTPS (selten — geht durch Caddy).
Gateway-.env hat falschen GC_BASE_URL.

Prüfung:

# Am NAS
docker logs gateway --tail 50
docker exec gateway wg show

Fix:

Peer in UI öffnen → Gateway-Pairing neu ausstellen → neue .env deployen, Container recreate.
Siehe auch backup-and-restore.md §5.

Gateway-Traffic hat hohe Latenz / RDP-Abbrüche

Ursache: MTU-Thema. Das vollständige Path-MTU-Discovery geht durch WG-Tunnel oft nicht durch, weil ICMP-Pakete im Weg filtered werden.

Fix: MSS-Clamping ist ab v1.41 im Entrypoint default an (TCPMSS --clamp-mss-to-pmtu auf FORWARD-Chain). Wenn das nicht reicht:

# In .env
GC_WG_MTU=1380

dann Container recreate. Synology-Firewall erlaubt zusätzliche Manipulation nicht — dort ist manuelles Tuning am NAS-seitigen wg-Tunnel nötig.

RDP

RDP-Verbindung bricht nach Login ab

Ursache: Fast immer MTU/MSS. Der Login läuft noch mit kleinen TLS- Handshakes, sobald die Desktop-Session größere Frames schickt (Fenster- Updates), fallen Pakete.

Prüfung:

docker exec gatecontrol ip link show wg0 | grep mtu
# wg0 sollte mtu 1420 oder 1380 zeigen.

Fix:

GC_WG_MTU=1380 auf Server-Seite.
Am Home-Gateway analog.
MSS-Clamping ist default an (siehe oben). Wenn trotzdem Probleme: auf dem NAS-Router zusätzlich MSS-Clamping setzen.

RDP-Credentials funktionieren nicht

Ursache: Master-Key-Rotation ist aktiv und die letzte Rotation wurde am Gateway noch nicht quittiert.

Prüfung:

# Pending rotations
docker exec gatecontrol curl -s http://127.0.0.1:3000/api/v1/rdp/rotation/pending \
  -H "Cookie: <admin-session>" | jq

Fix:

In der UI zum RDP-Host gehen → Rotation bestätigen.
Oder per API: POST /api/v1/rdp/:id/rotation/ack.

Wake-on-LAN triggert nicht

Ursachen:

MAC-Adresse im RDP-Host-Profil falsch oder leer.
MAC-Cache am Gateway ist kalt — Gateway kennt den Host-MAC nur, wenn er mindestens einmal kommuniziert hat.
Zielhost ist per Broadcast im Heimnetz nicht erreichbar (Managed-Switch filtert Broadcasts).

Prüfung:

# UI: RDP-Host-Detail → zeigt konfigurierte MAC
# Oder direkt aus DB:
docker exec gatecontrol sqlite3 /data/gatecontrol.db \
  "SELECT name, wol_enabled, wol_mac_address FROM rdp_routes;"

Fix:

MAC manuell im UI eintragen.
Vorher den Host einmal online bringen und kurz pingen (damit der Gateway den MAC discovered).
Als Broadcast-Adresse explizit die Subnetz-Broadcast setzen (z. B. 192.168.1.255 statt 255.255.255.255).

Datenbank

SQLite Lock-Errors

Symptom: Log-Einträge SQLITE_BUSY: database is locked, UI-Request timeouten sporadisch.

Ursachen:

Mehrere Prozesse schreiben parallel (nicht passieren sollte — Node ist single-writer).
WAL-Checkpoint ist blockiert, weil ein Long-Running-Read (Backup, Export) das WAL offen hält.
Disk langsam/voll.

Prüfung:

docker exec gatecontrol ls -lh /data/gatecontrol.db*
df -h

Erwartung: .db, .db-wal, .db-shm. WAL sollte selten > 50 MB sein.

Fix:

Checkpoint erzwingen:

docker exec gatecontrol sqlite3 /data/gatecontrol.db "PRAGMA wal_checkpoint(TRUNCATE);"

Disk-Platz freimachen.
Im Zweifel: Container neu starten, löst 99 % dieser Probleme.

Migrations failed

Symptom: Container crasht nach Upgrade mit Stack-Trace im Log, der mit Migration failed: <name> anfängt.

Prüfung:

docker logs gatecontrol 2>&1 | grep -B 2 -A 20 'Migration failed'

# Aktueller Migrations-Stand in DB
docker exec gatecontrol sqlite3 /data/gatecontrol.db \
  "SELECT version, name, applied_at FROM migration_history ORDER BY version DESC LIMIT 10;"

Fix:

Fehlschlagende Migration dokumentieren, Issue checken.
Rollback auf vorherige Version (siehe upgrade.md §6).
Wenn Rollback wegen neu-hinzugefügter Spalten fehlschlägt: Backup restoren auf frisches Volume der alten Version.

DB korrupt

Symptom: SQLITE_CORRUPT, disk image is malformed, Container crasht.

Ursachen:

Host-OS-Crash während Write (nicht-gracefulled Power-Off).
Disk-Failure.
Container hart gekillt während DDL (sehr selten).

Prüfung:

docker exec gatecontrol sqlite3 /data/gatecontrol.db "PRAGMA integrity_check;"

Fix:

Aus JSON-Backup neu aufsetzen (siehe backup-and-restore.md §4).
Alternativ: DB-Datei umbenennen, Container neu starten, Schema wird frisch angelegt, dann Restore. /data/.encryption_key behalten, sonst lassen sich Peer-Private-Keys nicht entschlüsseln.

Logging & Debugging

Wo liegen die Logs

App-Log (Node + Caddy + dnsmasq + supervisord) →

docker logs gatecontrol
docker logs -f gatecontrol      # follow
docker logs --since 10m gatecontrol

Caddy-Access-Log → /data/caddy/access.log (nur wenn in Caddy-Config explizit aktiviert).
Auto-Update-Log → /var/log/gatecontrol-update.log (nur wenn du update.sh per Cron eingebunden hast).
Activity-Log in DB → /api/v1/logs oder in UI Einstellungen → Logs.

Log-Level hochdrehen

# In .env
GC_LOG_LEVEL=debug

docker compose up -d --force-recreate gatecontrol

Gibt Node-Pino-Debug-Zeilen aus. Vorsicht: auf prod dauerhaft laufend zuviel Volume. Nach dem Debug zurück auf info.

Einzelne Route debuggen

In der UI an der Route das Flag Debug-Tracing einschalten (debug_enabled=1). Dann pro Request ein Trace-Eintrag in die Trace-Tabelle. Lesen per:

curl -sS -H "Authorization: Bearer $GC_API_TOKEN" \
  "https://gate.example.com/api/v1/routes/<route-id>/trace?limit=50" | jq

Achtung: das kostet Performance — wieder aus machen, sobald du den Fall isoliert hast.

Caddy-Config inspizieren

docker exec gatecontrol curl -s http://127.0.0.1:2019/config/ | jq
docker exec gatecontrol caddy validate --config /data/caddy/runtime.json

WireGuard-State

docker exec gatecontrol wg show wg0
docker exec gatecontrol wg show wg0 dump
docker exec gatecontrol cat /etc/wireguard/wg0.conf

Bekannte Ops-Gotchas

Sammlung aus Produktiv-Incidents, die mehrmals aufgeschlagen sind.

Synology-Gateway-Routing mit /32-Subnetz

Wenn der Windows-/Desktop-Client seine Address = 10.8.0.6/32 (statt /24) interpretiert, berechnet die Kill-Switch-Logik des Clients nur die eigene IP als "VPN-Subnetz" statt 10.8.0.0/24. Dann scheitern Kill-Switch und DNS auf Server-Ebene (Routen zu 10.8.0.1 werden als off-VPN abgelehnt). Wenn Nutzer berichten, dass der Kill-Switch die VPN-Route killt, ist die Ursache fast immer die /32-Berechnung clientseitig — das ist Client-Code-Problem, nicht Server.

Node läuft als root im Container

Node braucht Root, weil es das WireGuard-CLI (wg, wg-quick) aufrufen muss, um das Interface zu verwalten. Das ist Design, kein Bug. Security-Scanner flaggen das — ignorieren.

COEP deaktiviert, bcryptjs + argon2 parallel

Bewusste Design-Entscheidungen:

COEP (Cross-Origin-Embedder-Policy) ist aus, weil Caddy-Admin-UI iframe- Previews rendert. Wird als Accepted-Risk geführt.
bcryptjs + argon2 parallel weil Bestands-Passwörter (alte Installationen) noch bcrypt sind und erst beim nächsten Login auf argon2 upgegradet werden.

Das taucht in Security-Reviews regelmäßig auf — nicht als Finding melden.

Systemd-resolved vs. dnsmasq

systemd-resolved bindet auf 127.0.0.53:53 und kollidiert nicht mit dem container-internen dnsmasq (der auf 127.0.0.1:53 und 10.8.0.1:53 bindet). Andere Host-DNS-Dienste (bind9, unbound, NetworkManager-dnsmasq, libvirt- dnsmasq) auf 127.0.0.1:53 schießen den Container-Start mit klarer Meldung ab — siehe Container / Host "Container startet nicht".

Cloudflare-Proxy aus = Pflicht für HTTP-01

Orange Wolke bei Cloudflare fängt Port-80-Traffic ab. Let's-Encrypt-HTTP-01 sieht dann nicht den Server sondern Cloudflare. Entweder Proxy aus (grau) oder DNS-Challenge konfigurieren.

Wann um Hilfe fragen

Wenn du den Fall nicht selbst eingegrenzt kriegst, sammle ein Diagnostic-Bundle:

mkdir -p /tmp/gc-diag-$(date -u +%F) && cd /tmp/gc-diag-$(date -u +%F)

# Container-Logs (letzte 500 Zeilen)
docker logs --tail 500 gatecontrol > app.log 2>&1

# Container-Metadaten (State, Config, Mounts)
docker inspect gatecontrol > inspect.json

# Versionen
docker image inspect ghcr.io/callmetechie/gatecontrol:latest \
  --format '{{ index .RepoDigests 0 }} / {{ .Created }}' > image-version.txt

# WireGuard
docker exec gatecontrol wg show wg0 > wg-show.txt 2>&1
docker exec gatecontrol wg show wg0 dump > wg-dump.txt 2>&1

# Caddy-Config
docker exec gatecontrol curl -s http://127.0.0.1:2019/config/ > caddy-config.json

# Health-Check
curl -s http://127.0.0.1:3000/health > health.json

# Host-Metadaten
uname -a > host.txt
ip route > routes.txt
ss -lntup > ports.txt

# Anonymisieren (optional, aber gute Idee):
sed -i -E 's/[a-zA-Z0-9+/]{43}=/REDACTED_PUBKEY/g' wg-*.txt caddy-*.json

tar czf ../diag-bundle.tar.gz -C .. "gc-diag-$(date -u +%F)"

Dazu relevante CHANGELOG-Zeilen (welche Version läuft, was war die letzte Änderung) und Screenshots von UI-Warnungen. Damit kann jemand aus der Ferne in 5 Minuten einordnen, wo das Problem steckt, statt eine halbe Stunde lang Rückfragen zu stellen.

Für die Standard-Referenz der API und Konzepte:

API.md — Endpoint-Referenz
USER-GUIDE.md — Feature-Bedienung
concepts/home-gateway.md — Gateway-Architektur
concepts/routing.md — Route-Model

Inhaltsverzeichnis

Container / Host

GateControl-Container startet nicht / crasht nach Start

Health-Check bleibt auf starting

Hohe CPU/RAM-Last

DNS & TLS

Zertifikat wird nicht ausgestellt

Admin-UI nicht erreichbar obwohl Container healthy

Routen geben 502

WireGuard

Peer kriegt keine IP / Config fehlerhaft

Handshake schlägt fehl

Peer ist online, aber kein Traffic

Multiple-VPN-Konflikte

Home-Gateway

Gateway-Card bleibt "offline" trotz laufendem Container

Config-Hash out of sync

Heartbeat kommt nicht an

Gateway-Traffic hat hohe Latenz / RDP-Abbrüche

RDP

RDP-Verbindung bricht nach Login ab

RDP-Credentials funktionieren nicht

Wake-on-LAN triggert nicht

Datenbank

SQLite Lock-Errors

Migrations failed

DB korrupt

Logging & Debugging

Wo liegen die Logs

Log-Level hochdrehen

Einzelne Route debuggen

Caddy-Config inspizieren

WireGuard-State

Bekannte Ops-Gotchas

Synology-Gateway-Routing mit /32-Subnetz

Node läuft als root im Container

COEP deaktiviert, bcryptjs + argon2 parallel

Systemd-resolved vs. dnsmasq

Cloudflare-Proxy aus = Pflicht für HTTP-01

Wann um Hilfe fragen

Cookie Settings

Health-Check bleibt auf `starting`