3.9 KiB
Troubleshooting — alle POC-Fehler und Lösungen
Chronologische Liste aller Probleme, die beim Dokploy-POC aufgetreten sind.
1. App crasht: ECONNREFUSED ::1:5432 / 127.0.0.1:5432
Symptom: Docker-Container startet und stirbt sofort, Log zeigt
Failed to init DB: AggregateError [ECONNREFUSED].
Ursache: Die App (PostgreSQL-Version) nutzte localhost als DB-Host, aber die DB
läuft als separater Docker-Service, nicht im selben Container.
Lösung: DATABASE_URL auf den Service-Namen zeigen lassen, oder (POC-Entscheidung)
auf SQLite umsteigen — keine externe DB nötig.
2. App crasht: ENOTFOUND techno-db-8u3yoi
Symptom: DNS-Lookup des DB-Hostnames schlägt fehl.
Ursache: Der techno-db Docker-Service existierte gar nicht — Dokploy hat ihn nie
erstellt, obwohl die API-Provisionierung „OK" meldete.
Lösung: SQLite-Umstellung (siehe oben).
3. Bad Gateway trotz laufender App
Symptom: Intern läuft die App, aber über die Domain kommt Bad Gateway.
Ursache: Traefik routete auf Port :3000, die App (bzw. nginx:alpine) lauscht aber
auf :80. Dokploy setzt standardmäßig :3000.
Diagnose:
docker exec dokploy-traefik wget -qO- http://<service>:80/ # funktioniert
docker exec dokploy-traefik wget -qO- http://<service>:3000/ # connection refused
Lösung: Traefik-Config korrigieren:
# Config liegt auf dem Host (Bind-Mount)
sed -i 's|http://<service>:3000|http://<service>:80|' /etc/dokploy/traefik/dynamic/<app>.yml
docker kill -s HUP dokploy-traefik # reload
4. Dokploy-API: Unauthorized / Invalid API key
Symptom: Alle API-Calls geben 401, Deploy-Worker loggt Error verifying API key.
Ursache: Der gespeicherte API-Key war abgelaufen/ungültig.
Diagnose + Lösung: Key direkt aus der Dokploy-Postgres-DB lesen:
docker exec dokploy-postgres.1.<id> psql -U dokploy -d dokploy \
-c "SELECT name, key, start FROM apikey;"
Hinweis: Der key-Wert in der DB ist gehasht (BetterAuth). Für neue Keys: über die
Dokploy-UI unter Settings → API Keys neu erzeugen.
5. Deploy-Worker startet keine Container
Symptom: Deployment wird angenommen, aber kein Container wird gebaut/gestartet.
Worker-Logs zeigen service <name> not found.
Ursache: Services wurden manuell umbenannt/gelöscht → Dokploy ist out-of-sync mit dem tatsächlichen Docker-Zustand.
Lösung: Manuell bauen + deployen (später durch die Auto-Deploy-Pipeline ersetzt):
cd /opt/repos/techno-todo
docker build -t techno-todo:<commit> .
docker service update --force --image techno-todo:<commit> <service-name>
6. Gitea-Webhook löst nicht zuverlässig aus
Symptom: Manche Pushes triggern den Deploy, andere nicht.
Ursache: Gitea läuft in einem K8s/Talos-Cluster — ausgehende Verbindungen zu
internen 192.168.0.x-Adressen sind unzuverlässig (CNI/NAT).
Lösung: Cron-Polling-Fallback (idempotentes Deploy-Skript alle 2 Min). Siehe
AUTODEPLOY.md.
7. Race-Condition: alter Commit wird deployed
Symptom: Webhook feuert, aber das Deploy holt noch den alten Commit.
Ursache: git fetch läuft, bevor Gitea den Push vollständig ins Git-Backend
integriert hat.
Lösung: Entweder sleep 3 vor git fetch, oder (besser) idempotentes Skript — der
nächste Cron-Lauf holt den verpassten Commit automatisch nach.
Nützliche Diagnose-Befehle
# Docker-Swarm-Services
docker service ls
docker service logs --tail 50 <service>
# Traefik-Routing
docker exec dokploy-traefik wget -qO- http://localhost:8080/api/http/routers
# Dokploy-Logs (Deploy-Worker)
docker service logs --tail 50 dokploy 2>&1 | grep -iE 'worker|error|deploy'
# Dokploy-DB direkt abfragen
docker exec dokploy-postgres.1.<id> psql -U dokploy -d dokploy -c "\dt"
# Token aus DB extrahieren (Gitea)
docker exec dokploy-postgres.1.<id> psql -U dokploy -d dokploy \
-c "SELECT access_token FROM gitea;"