11. Fehlersuche¶
Bei Störungen lohnt es sich, zuerst den betroffenen Bereich einzugrenzen: Anwendung, Datenbank, Mail, Queue, Browser-Laufzeit oder Webserver.
11.1. Häufige Fehlerbilder¶
11.1.1. Login funktioniert nicht¶
Prüfen Sie:
- stimmt
APP_URL? - stimmen Session- und Cookie-Einstellungen?
- funktioniert die Datenbank?
- ist das Benutzerkonto aktiv?
11.1.2. Seiten laden, aber Speichern schlägt fehl¶
Prüfen Sie:
- Anwendungslog
- Datenbankverbindung
- PHP-Fehler
- fehlende Schreibrechte
11.1.3. Debug- oder Entwicklerseiten sind erreichbar¶
Prüfen Sie:
APP_DEBUGsteht nicht versehentlich auftrueBOOST_ENABLEDundBOOST_BROWSER_LOGS_WATCHERsind nicht unbeabsichtigt aktiviertIGNITION_ENABLE_RUNNABLE_SOLUTIONSist nicht aktiviertTELESCOPE_ENABLEDist nur für bewusst abgesicherte lokale Sitzungen aktivDUSK_ENABLEDist nur für gezielte Browser-Tests aktiv- Entwicklungswerkzeuge wie Dusk oder Telescope laufen nicht auf einem öffentlich erreichbaren System
11.1.4. Mails kommen nicht an¶
Prüfen Sie:
- Mail-Konfiguration in
.env - Status und Logs des optionalen Produktionsdienstes
postfix ./planer exec app php artisan queue:failedund Horizon- SMTP-Verbindung beziehungsweise Relay-Zugang
- SPF, DKIM, DMARC
- öffentliche DNS- und PTR/rDNS-Einträge bei direkter MX-Zustellung
Eine ausführliche Prüfreihenfolge und der anwendungsseitige Rollback stehen im Mail-Betriebskapitel.
11.1.5. PDF- oder Browser-Ausgaben schlagen fehl¶
Prüfen Sie:
- Chromium/Chrome installiert?
- Zeigt
BROWSERSHOT_CHROME_PATHauf die tatsächlich vorhandene Browser-Datei? Im Docker-Image ist der Standardpfad/usr/bin/chromium. - Systembibliotheken vollständig?
- Startet der Browser für den Webserver-Benutzer?
- gibt es genug temporären Speicher?
11.1.6. Updates brechen ab¶
Prüfen Sie:
- lokaler Git-Status
- Upstream-Branch
- Composer- oder npm-Abhängigkeiten
- Migrationen
- Dateirechte
11.2. Wichtige Protokollquellen¶
- Container-Logs mit
./planer logsbeziehungsweise./planer logs app horizon - optionale Laravel-Logs in
src/storage/logs/, wennDAILY_LOGS=truegesetzt ist - Webserver-Logs
- PHP-FPM- oder Prozess-Logs
- Queue- und Scheduler-Logs
- Container-Logs bei Docker
11.3. Gute Reihenfolge bei der Fehlersuche¶
- Symptom kurz beschreiben.
- Reproduzierbarkeit prüfen.
- Logs derselben Zeitspanne ansehen.
- zuletzt geänderte Systemteile notieren; bei Docker zusätzlich
./planer statusund die relevanten./planer logsprüfen. - erst dann korrigieren oder zurückrollen.
11.4. Fehlerberichte aus der Anwendung¶
11.4.1. Fehlerreferenz und Nutzerhinweise¶
Bei einem internen Serverfehler zeigt Pfarrplaner eine eigene Fehlerseite mit der großen Pfarrplaner-Marke und einer Fehlerreferenz an. Diese Referenz sollte bei einer Supportmeldung mitgeteilt werden. Wenn Sentry konfiguriert ist, ist sie die Event-ID des Sentry-Eintrags und kann dort direkt zum betroffenen Issue aufgelöst werden. Die Fehlerreferenz wird außerdem zusammen mit der ursprünglichen Ausnahme und ihrem Stacktrace im Anwendungslog protokolliert.
Die Fehlerseite bietet außerdem ein freiwilliges Formular für eine kurze Beschreibung des Problems. Die Eingabe wird serverseitig an Sentrys User-Feedback-Schnittstelle übermittelt und der Fehlerreferenz zugeordnet. Der Sentry-API-Token wird nicht an den Browser übertragen.
Für die Zuordnung werden zusätzlich zur DSN diese Produktionsvariablen benötigt:
SENTRY_FEEDBACK_TOKEN=
SENTRY_ORGANIZATION=
SENTRY_PROJECT=
Der Token benötigt nur die Berechtigung zum Schreiben von Projekt-Feedback. Wenn SENTRY_FEEDBACK_ENDPOINT leer bleibt, verwendet Pfarrplaner automatisch den Sentry-Host aus SENTRY_LARAVEL_DSN; ein abweichender Wert kann hier mit dem vollständigen API-Basispfad wie https://sentry.io/api/0 angegeben werden. Wenn diese Variablen fehlen oder Sentry nicht erreichbar ist, bleibt die Fehlerreferenz sichtbar; die Anwendung zeigt dann an, dass der Hinweis nicht automatisch übermittelt werden konnte.
Die Testseite /__test/500 ist ausschließlich in den Umgebungen local und
testing verfügbar. Sie kann verwendet werden, um Fehlerseite und Feedback-
Formular nach einem Update zu prüfen.