PDNS Manager

Troubleshooting

Sammlung der Sachen, die in der Praxis am häufigsten haken. Wenn dein Problem hier nicht steht und du es löst, gerne ein Issue auf GitHub mit Lösung – dann landet es hier.

Compose meldet „DB_PASSWORD ist leer …" beim Start

Seit v2.3.3 eingebaute Schutz-Schiene: ohne gesetzte Passwörter wird die DB nicht initialisiert. Lösung:

./setup.sh                          # legt eine vollständige .env an
# oder manuell:  cp .env.example .env  und Passwörter eintragen
docker compose up -d

Backend logt „JWT_SECRET_KEY ist leer"

echo "JWT_SECRET_KEY=$(openssl rand -hex 64)" >> .env
docker compose up -d

Container starten nicht / hängen

docker compose logs -f
docker compose down
docker compose up -d

MariaDB braucht beim allerersten Start ein paar Sekunden, bis sie healthy ist. Das Backend wartet automatisch (depends_on: condition: service_healthy).

Backend startet, Frontend zeigt weiße Seite

Seit v2.3.7 prüft das Backend-Image beim Build, dass index.html, assets/ und ein gebautes JS-Bundle vorhanden sind – wenn nicht, bricht der Build ab. Wenn du trotzdem ein leeres Bild bekommst:

  • Browser-Cache leeren oder Inkognito-Tab probieren.
  • Im Browser-DevTools im Tab Network schauen, ob /assets/index-*.js einen 200 oder 404 hat.
  • Bei 404: Backend-Image neu bauen mit ./update.sh --rebuild.

Login geht nicht („429 Too Many Requests")

Das Login-Rate-Limit hat zugeschlagen. Standardlösung: ein paar Minuten warten, dann das richtige Passwort verwenden. Der Header Retry-After in der Antwort sagt dir genau wie lange.

Login geht nicht, kein 429 – Cookie wird nicht gesetzt

  • HTTPS davor? Dann muss AUTH_COOKIE_SECURE=true in der .env stehen.
  • Reverse-Proxy nicht richtig konfiguriert? X-Forwarded-Proto, X-Forwarded-For mitgeben.
  • SameSite-Probleme? Default lax sollte reichen; nur wenn das Panel über eine andere Domain eingebettet ist (z. B. iframe), brauchst du none + secure.

„Captcha ungültig" beim Login (Lockout)

Wenn du das Captcha falsch konfiguriert hast und dich aussperrst, hilft direktes SQL: 

docker compose exec -T mariadb mysql -u root -p"$DB_ROOT_PASSWORD" dns_manager <<SQL
UPDATE system_settings SET value='false' WHERE key_name='captcha.enabled';
SQL

Danach wieder einloggen, Captcha sauber konfigurieren, Test-Button drücken und wieder aktivieren.

Admin-Passwort vergessen

docker compose exec backend python -c "
from app.core.database import async_session
from app.models.models import User
from app.core.auth import hash_password
import asyncio

async def reset():
    async with async_session() as db:
        admin = await db.get(User, 1)   # User-ID 1 = erster Admin
        admin.hashed_password = hash_password('neues-passwort')
        await db.commit()
        print('Passwort zurueckgesetzt.')

asyncio.run(reset())
"

PowerDNS-Verbindung scheitert (Verbindungstest rot)

  • HTTP 401: API-Key in pdns.conf stimmt nicht mit dem im Panel hinterlegten überein.
  • Connection refused: webserver=yes? webserver-address bindet auf das richtige Interface? Aus Sicht des Backend-Containers erreichbar?
  • 403 Forbidden: webserver-allow-from blockt deinen Container. Aus dem Container schauen: docker compose exec backend curl -v http://pdns:8081/api/v1/servers.
  • Timeout: Firewall, Routing, oder PowerDNS hängt – schau in dessen journalctl -u pdns.

Records sind im Panel angelegt, aber `dig` zeigt sie nicht

  • Hat dig wirklich diesen PowerDNS gefragt? Mit @<ip> explizit angeben.
  • SOA-Serial gestiegen? dig SOA <zone> @<ip> +short – wenn nicht, hat PowerDNS den Schreibvorgang vielleicht abgelehnt; check Backend-Log.
  • Cache des Resolvers? Klassisches „TTL überstehen" oder Resolver-Cache flushen.

DNSSEC: Resolver gibt SERVFAIL

Drei häufigste Ursachen:

  1. DS beim Registrar fehlt oder ist veraltet → in den DNSSEC-Schlüsseln im Panel den aktuellen DS ablesen, beim Registrar setzen.
  2. NS-Records beim Registrar zeigen auf die falschen Server (z. B. noch alte Provider-NS).
  3. Auto-Signing aus, RRSIG abgelaufen → einen Record minimal ändern und zurückändern, das triggert Re-Signing.

Test-Tool: dnsviz.net – zeigt die ganze Validation-Chain mit konkreten Fehlern.

Webhook kommt nicht an oder wird abgelehnt

  • URL ist privat (RFC1918, Localhost)? Standardmäßig blockiert. WEBHOOK_ALLOW_PRIVATE_URLS=true setzen.
  • HTTPS-Endpoint hat ein selbstsigniertes Zertifikat? Aktuell nicht akzeptiert – nutze ein gültiges Zertifikat oder einen internen ACME.
  • Empfänger validiert die Signatur falsch und schickt 4xx → check, dass du den rohen Body für HMAC nutzt.

Update bricht ab oder Container kommt nicht hoch

  • DB-Migration konnte nicht laufen → check docker compose logs backend auf den genauen Fehler.
  • Plattenplatz voll → df -h, alte Container-Images aufräumen mit docker system prune -a.
  • Im Notfall: auf den vorherigen Tag zurück (git checkout v2.3.7 && docker compose build backend && docker compose up -d) und das DB-Backup einspielen, dann das Update mit dem Maintainer absprechen.