diff --git a/backend/docs/FEHLERRESILIENZ_WARTUNGSFREIER_BETRIEB.md b/backend/docs/FEHLERRESILIENZ_WARTUNGSFREIER_BETRIEB.md index 0519ecba..e7dde59f 100644 --- a/backend/docs/FEHLERRESILIENZ_WARTUNGSFREIER_BETRIEB.md +++ b/backend/docs/FEHLERRESILIENZ_WARTUNGSFREIER_BETRIEB.md @@ -1 +1,294 @@ - \ No newline at end of file +# Fehlerresilienz und wartungsfreier Produktionsbetrieb + +## Übersicht + +Diese Dokumentation beschreibt die implementierten Systeme für absolute Fehlerresilienz und wartungsfreien Produktionsbetrieb der MYP-Druckerverwaltung. + +## 🛡️ Implementierte Systeme + +### 1. System-Control-Manager (`utils/system_control.py`) + +**Zweck**: Robuste Kontrolle aller System-Operationen mit Sicherheitsprüfungen + +**Features**: +- Sichere System-Neustarts und -Shutdowns +- Kiosk-spezifische Restart-Funktionen +- Umfassende Sicherheitsprüfungen vor Operationen +- Geplante Operationen mit konfigurierbaren Verzögerungen +- Automatische Cleanup-Routinen vor System-Änderungen + +**API-Endpunkte**: +- `POST /api/admin/system/restart` - System-Neustart planen +- `POST /api/admin/system/shutdown` - System-Shutdown planen +- `POST /api/admin/kiosk/restart` - Kiosk-Neustart ohne System-Restart +- `GET /api/admin/system/status` - Umfassender System-Status +- `GET /api/admin/system/operations` - Geplante und vergangene Operationen + +### 2. Error-Recovery-Manager (`utils/error_recovery.py`) + +**Zweck**: Automatische Fehlererkennung, -behebung und -prävention + +**Features**: +- Kontinuierliche Überwachung von Log-Dateien +- Vordefinierte Fehlermuster mit automatischen Recovery-Aktionen +- Eskalations-Mechanismen bei wiederholten Fehlern +- Real-time System-Metriken-Überwachung +- Service-Status-Monitoring + +**Erkannte Fehlermuster**: +- Datenbank-Sperrungen → Automatisches Database-Reset +- Speicher-Erschöpfung → Cache-Clearing + Service-Restart +- Netzwerk-Fehler → Komponenten-Restart +- Kiosk-Crashes → Display-Neustart +- Service-Ausfälle → Service-Restart +- Festplatten-Vollauslastung → Emergency-Stop + +**Recovery-Aktionen**: +- `LOG_ONLY` - Nur Logging +- `RESTART_SERVICE` - Service-Neustart +- `RESTART_COMPONENT` - Komponenten-Neustart (z.B. Kiosk) +- `CLEAR_CACHE` - Cache-Clearing +- `RESET_DATABASE` - Datenbank-Reset +- `RESTART_SYSTEM` - System-Neustart +- `EMERGENCY_STOP` - Notfall-Stopp + +### 3. Optimierter Kiosk-Service (`systemd/myp-kiosk.service`) + +**Zweck**: Wartungsfreier Kiosk-Betrieb mit absoluter Stabilität + +**Verbesserungen**: +- Robuste Backend-Wartung mit API-Verfügbarkeitsprüfung +- Verbesserte Browser-Kompatibilität (Chromium, Firefox) +- Optimierte Startup-Sequenz mit X11-Prüfung +- Umfassende Display-Konfiguration +- Ressourcen-Management und Limits +- Erweiterte Restart-Logik +- Detailliertes Logging + +**Browser-Argumente optimiert für**: +- Stabilität (Crash-Reporter deaktiviert) +- Performance (Hardware-Beschleunigung) +- Sicherheit (Sandbox-Konfiguration) +- Kiosk-Verhalten (Vollbild, keine UI-Elemente) + +## 🔧 Konfiguration + +### System-Control-Manager + +```python +# Konfigurationsoptionen +config = { + "restart_delay": 60, # Standard-Verzögerung für Restarts + "shutdown_delay": 30, # Standard-Verzögerung für Shutdowns + "kiosk_restart_delay": 10, # Verzögerung für Kiosk-Restarts + "safety_checks": True, # Sicherheitsprüfungen aktiviert + "require_confirmation": True # Bestätigungen erforderlich +} +``` + +### Error-Recovery-Manager + +```python +# Monitoring-Konfiguration +config = { + "check_interval": 30, # Überwachungsintervall in Sekunden + "max_history_size": 1000, # Maximale Anzahl gespeicherter Fehler + "auto_recovery_enabled": True, # Automatische Recovery aktiviert + "log_file_paths": [ # Überwachte Log-Dateien + "logs/app/app.log", + "logs/errors/errors.log", + "logs/database/database.log" + ] +} +``` + +## 🖥️ Frontend-Funktionen + +### Admin-Panel Erweiterungen + +**Neue System-Control-Buttons**: +- **Kiosk neustarten**: Startet nur das Display neu (10s) +- **System neustarten**: Vollständiger System-Restart (konfigurierbar) +- **System herunterfahren**: Sicherer Shutdown (mehrfache Bestätigung) +- **System-Status**: Detaillierte Status-Anzeige +- **Fehlerresilienz**: Toggle für Error-Recovery-Monitoring + +**Features**: +- Bestätigungsdialoge mit Sicherheitswarnungen +- Countdown-Timer für geplante Operationen +- Echtzeit-Status-Updates +- Detaillierte System-Metriken-Anzeige +- Error-Recovery-Statistiken + +## 🔄 Automatische Initialisierung + +### App-Startup-Sequence + +1. **Shutdown-Manager** initialisiert (45s Timeout) +2. **Error-Recovery-Monitoring** gestartet +3. **System-Control-Manager** aktiviert +4. **Kiosk-Service-Verfügbarkeit** geprüft +5. **Integration** aller Systeme in Shutdown-Manager + +### Automatische Registrierung + +```python +# Error-Recovery wird automatisch in Shutdown-Manager integriert +shutdown_manager.register_cleanup_function( + func=stop_error_monitoring, + name="Error Recovery Monitoring", + priority=2, + timeout=10 +) +``` + +## 📊 Monitoring und Logging + +### System-Status-Überwachung + +- **Services**: Alle systemd-Services (myp-https, myp-kiosk, watchdog) +- **System-Metriken**: Speicher, Festplatte, CPU-Last +- **Error-Recovery**: Fehlerstatistiken, Erfolgsraten +- **Operations**: Geplante und abgeschlossene System-Operationen + +### Logging-Struktur + +``` +logs/ +├── app/app.log # Haupt-Anwendungslog +├── errors/errors.log # Fehler-spezifische Logs +├── system_control/ # System-Control-Operationen +├── error_recovery/ # Error-Recovery-Aktivitäten +└── kiosk/ # Kiosk-spezifische Logs +``` + +### Kiosk-Service-Logging + +- **Systemd Journal**: `journalctl -u myp-kiosk.service` +- **Dedizierte Log-Datei**: `/var/log/myp-kiosk.log` +- **Rate-Limiting**: 1000 Nachrichten/30s + +## 🚨 Sicherheitsfeatures + +### Sicherheitsprüfungen vor Operationen + +- **Systemlast-Prüfung**: Keine Operationen bei hoher Last +- **Speicher-Prüfung**: Warnung bei niedrigem verfügbarem Speicher +- **Aktive Jobs**: Keine Restarts während laufender Druckjobs +- **Kritische Prozesse**: Überwachung von CPU-intensiven Prozessen + +### Benutzer-Berechtigungen + +- **Admin-Only**: Alle System-Control-Funktionen nur für Administratoren +- **Doppelte Bestätigung**: Kritische Operationen (Shutdown) benötigen mehrfache Bestätigung +- **Audit-Trail**: Alle Operationen werden mit User-ID und Zeitstempel geloggt + +## 🔧 Fehlerbehebung + +### Häufige Probleme + +#### Kiosk startet nicht + +```bash +# Service-Status prüfen +sudo systemctl status myp-kiosk.service + +# Detaillierte Logs anzeigen +journalctl -u myp-kiosk.service -f + +# X11-Display prüfen +sudo -u kiosk DISPLAY=:0 xset q + +# Backend-Verfügbarkeit testen +curl -k https://localhost:443/api/kiosk/status +``` + +#### Error-Recovery funktioniert nicht + +```bash +# Error-Recovery-Status prüfen +curl -H "X-CSRFToken: " https://localhost:443/api/admin/error-recovery/status + +# Manuell aktivieren +curl -X POST -H "Content-Type: application/json" \ + -H "X-CSRFToken: " \ + -d '{"enable": true}' \ + https://localhost:443/api/admin/error-recovery/toggle +``` + +#### System-Control-Operationen schlagen fehl + +```bash +# System-Status überprüfen +curl -H "X-CSRFToken: " https://localhost:443/api/admin/system/status + +# Aktuelle Operationen anzeigen +curl -H "X-CSRFToken: " https://localhost:443/api/admin/system/operations + +# Sicherheitsprüfungen bypass (nur bei Notfällen) +curl -X POST -H "Content-Type: application/json" \ + -H "X-CSRFToken: " \ + -d '{"force": true, "reason": "Notfall"}' \ + https://localhost:443/api/admin/system/restart +``` + +## 📈 Performance-Optimierungen + +### Kiosk-Service + +- **Hardware-Beschleunigung**: Optimierte GPU-Nutzung +- **Speicher-Management**: Begrenzte Browser-Speichernutzung +- **CPU-Limits**: Maximum 80% CPU-Nutzung +- **Prozess-Cleanup**: Automatische Bereinigung alter Browser-Prozesse + +### Error-Recovery + +- **Efficient Pattern Matching**: Optimierte Regex-Verarbeitung +- **Batch-Processing**: Log-Dateien in Chunks verarbeitet +- **Memory-Conscious**: Begrenzte History-Größe +- **Thread-Safe**: Sichere Parallel-Verarbeitung + +## 🎯 Wartungsfreier Betrieb + +### Automatische Wartung + +1. **Log-Rotation**: Automatische Bereinigung alter Logs +2. **Cache-Management**: Periodische Cache-Bereinigung +3. **Database-Maintenance**: Automatische DB-Optimierung +4. **Service-Health-Checks**: Kontinuierliche Service-Überwachung + +### Präventive Maßnahmen + +1. **Resource-Monitoring**: Frühwarnung bei Ressourcen-Engpässen +2. **Predictive-Recovery**: Probleme erkennen bevor sie kritisch werden +3. **Self-Healing**: Automatische Problembehebung ohne menschlichen Eingriff +4. **Graceful-Degradation**: System bleibt auch bei Teilausfällen funktional + +## 🔮 Zukünftige Erweiterungen + +### Geplante Features + +1. **Machine Learning**: Predictive Error-Detection +2. **Remote-Monitoring**: Zentrale Überwachung mehrerer Systeme +3. **Advanced-Analytics**: Detaillierte Performance-Analysen +4. **Auto-Scaling**: Dynamische Ressourcen-Anpassung + +### Erweiterungsmöglichkeiten + +1. **Custom Error-Patterns**: Benutzer-definierte Fehlermuster +2. **Integration APIs**: Anbindung an externe Monitoring-Systeme +3. **Mobile Alerts**: Push-Benachrichtigungen bei kritischen Fehlern +4. **Cloud-Backup**: Automatische Backup-Synchronisation + +--- + +## 📞 Support + +Bei Fragen oder Problemen: + +1. **Logs prüfen**: Immer zuerst die relevanten Log-Dateien überprüfen +2. **System-Status**: Admin-Panel → System-Status für Übersicht +3. **Error-Recovery**: Statistiken und Recent-Errors überprüfen +4. **Manual-Recovery**: Bei kritischen Problemen manuelle Recovery-Aktionen + +**Wichtig**: Das System ist für wartungsfreien Betrieb ausgelegt. Die meisten Probleme werden automatisch erkannt und behoben. \ No newline at end of file