English Version

Zurück zur Übersicht

Watchdog: Fehlerbehebung

Logs aller Container zeigst Du mit make stage-logs bzw. make live-logs. Auf Live schreibt die App im Produktionsmodus nur Fehler (und Deprecations) als JSON nach stderr.

Anmeldung

Die Anmeldung schlägt immer fehl

• Prüfen: Steht in der Env-Datei noch APP_ADMIN_PASSWORD_HASH=not-set oder ein leerer Wert? Wurde der Hash durch Docker Compose verändert?
• Lösung: Setze einen echten Bcrypt-Hash. In .env.stage und .env.live muss jedes $ zu $$ verdoppelt sein, in .env.local setzt Du den Hash in einfache Anführungszeichen. Starte danach die Container neu, damit sie die Env-Datei neu einlesen.

Checks laufen nicht

Ein Dashboard-Check bleibt auf PENDING

• Prüfen: Läuft der Container scheduler und der Container worker? Sind Client und Check aktiv? Ist als Runner Dashboard (Network) gewählt?
• Lösung: Starte die fehlenden Container (docker compose -f compose.live.yml up -d scheduler worker). Aktiviere Client und Check. Im Entwicklungsmodus (lokal, Stage) schreibt der Scheduler je Minute die Zeile Dispatch due checks tick mit evaluated und dispatched in die Log-Datei var/log/dev.log. Im lokalen Stack erscheint sie auch in der Container-Ausgabe, weil der Scheduler dort mit -vv läuft.

Ein Agenten-Check bleibt auf PENDING

• Prüfen: Ist der Agent unter Agents Online? Ist der Runner des Checks Agent (Local) und ein Agent zugewiesen? Ist der Client aktiv?
• Lösung: Siehe den nächsten Abschnitt. Mit Run now löst Du einen Lauf aus, der Agent holt ihn beim nächsten Tick ab.

Der Agent zeigt Offline oder Never seen

• Prüfen: Logs des Agent-Containers. Typische Meldungen sind Dashboard URL is required, Agent token is required und Agent token rejected by dashboard (401).
• Lösung: Setze WATCHDOG_DASHBOARD_URL und WATCHDOG_AGENT_TOKEN. Ein abgelehntes Token ersetzt Du über Regenerate Token. Ein Agent ohne Token beendet sich sofort und wird von Docker immer wieder neu gestartet. Stelle sicher, dass der Agent die Dashboard-URL erreicht (Firewall, HTTPS).

Das Ergebnis eines Agenten-Checks fehlt nach einem Ausfall des Dashboards

• Prüfen: Hat der Agent fünfmal hintereinander die Check-Liste nicht laden können?
• Lösung: Der Agent leert in diesem Fall seine Liste und führt erst nach dem nächsten erfolgreichen Abruf (spätestens nach dem Konfigurations-Intervall von 5 Minuten) wieder Checks aus. Es ist keine Aktion nötig.

E-Mails

Es kommen keine Alarm-E-Mails an

• Prüfen: Hat der Client unter Alert contacts mindestens einen Kontakt? Läuft der Container worker? Stimmen MAILER_DSN und MAILER_FROM? Gab es überhaupt einen Statuswechsel (siehe Benachrichtigungen)?
• Lösung: Ordne Kontakte zu und starte den Worker. Auf Stage und lokal siehst Du die Mails in Mailpit. Fehlgeschlagene Zustellungen zeigt php bin/console messenger:failed:show im App-Container.

Nach einer Störung kommt keine Wiederherstellungs-Mail

• Prüfen: Hat der Check zwischen FAIL und OK den Status UNKNOWN geliefert, etwa wegen fehlender Konfiguration oder weil der Docker-Socket nicht erreichbar war?
• Lösung: Behebe die Ursache des UNKNOWN. Eine Wiederherstellungs-Mail gibt es nur beim direkten Wechsel von WARN oder FAIL auf OK.

Einzelne Check-Typen

Docker-Check: Docker socket not available at /var/run/docker.sock

• Prüfen: Ist der Socket im Container eingebunden, der den Check ausführt?
• Lösung: Binde /var/run/docker.sock:/var/run/docker.sock:ro ein. Beim Agenten ist die Zeile in den Compose-Dateien auskommentiert.

Docker-Check: Docker API error: Cannot connect to Docker socket: Permission denied

• Prüfen: Läuft der Container als Benutzer ohne Zugriff auf die Socket-Gruppe?
• Lösung: Ergänze group_add mit der Gruppen-ID des Sockets (stat -c %g /var/run/docker.sock auf dem Host), wie bei Worker und Scheduler.

Festplatten-, Datei- oder Log-Check: Path not found oder File not found

• Prüfen: Ist /:/host/root:ro eingebunden und HOST_ROOT=/host/root gesetzt? Existiert der Pfad auf dem Host?
• Lösung: Setze Volume und Variable. Die Vorlage docker-compose.agent.yml enthält HOST_ROOT nicht.

Prozess-Check meldet immer FAIL

• Prüfen: Hat der Agent-Dienst pid: host?
• Lösung: Ergänze die Zeile und starte den Agenten neu.

SSL-Check meldet Connection to <Host>:443 failed

• Prüfen: Ist der Host erreichbar, passt der Port und ist die Kette von einer öffentlich vertrauten CA? Zertifikate einer privaten CA scheitern an der Prüfung.
• Lösung: Setze den Port in den Check-Einstellungen. Für private CAs bietet das Formular die Option Allow self-signed, die sich in der Oberfläche aber nicht speichern lässt (siehe SSL-Zertifikat).

DNS-Check mit eigenem Resolver: exit 127

• Prüfen: Ist dig im Container installiert?
• Lösung: Installiere dig (Paket bind-tools unter Alpine) im Image oder nutze den System-Resolver, indem Du Custom resolver leer lässt.

HTTP-Check: URL wird beim Speichern abgelehnt

• Prüfen: Hat die URL einen Hostnamen mit Punkt (Top-Level-Domain)?
• Lösung: http://localhost und einzelne Hostnamen akzeptiert das Formular nicht. Nutze einen vollständigen Namen oder eine IP-Adresse.

Eigener Check erscheint nicht in der Auswahl

• Prüfen: Trägt die Klasse #[AutoconfigureTag('watchdog.check')] und implementiert sie CheckInterface? Ist das Image neu gebaut?
• Lösung: Siehe Eigene Checks schreiben.

Betrieb

429 Too many requests bei Agenten

• Prüfen: Melden mehrere Agenten über dieselbe IP-Adresse (NAT, Proxy)?
• Lösung: Das Limit liegt bei 60 Anfragen pro Minute und IP. Jeder Agent braucht etwa zwei bis vier Anfragen pro Minute. Stelle sicher, dass hinter einem Proxy TRUSTED_PROXIES korrekt gesetzt ist, damit die echte IP zählt.

Alte Ergebnisse verschwinden

• Prüfen: Hat der Check unter Keep results for (days) einen Wert?
• Lösung: Der Scheduler löscht täglich um 03:00 Uhr Ergebnisse, die älter sind. Leere das Feld, wenn Du alle Ergebnisse behalten willst.

Datenbankdatei nicht beschreibbar

• Prüfen: Gehört /app/var/data.db im Volume dem Benutzer www-data?
• Lösung: make stage-update setzt die Rechte beim Update. Alternativ im Container: docker compose -f compose.stage.yml exec --user root app chown www-data:www-data /app/var/data.db.