fotospiel-app/docs/ops/dr-storage-issues.md

title, sidebar_label

title	sidebar_label
DR-Playbook – Storage-Probleme (Hot/Archive)	DR – Storage

Dieses Playbook beschreibt, wie du vorgehst, wenn es Probleme mit dem Medien‑Storage gibt – z.B. Hot‑Storage voll, Archivierung bleibt hängen oder viele Assets im Status failed.

1. Symptome & erste Checks

Typische Symptome:

• Gäste können keine Fotos mehr hochladen (Fehlermeldungen im Upload‑Flow).
• Tenant Admins sehen „fehlende Medien“ oder sehr langsame Galerien.
• event_media_assets enthält viele Einträge mit Status pending oder failed.
• Logs enthalten Hinweise auf fehlgeschlagene Archivierungen oder fehlende Dateien.

Erste Checks:

• Storage‑Usage der Hot‑Volumes/Buckets prüfen (Docker‑Volume, S3‑Dashboard o.ä.).
• EventMediaAsset‑Status stichprobenartig prüfen (hot, archived, pending, failed).
• Queue‑Längen und Fehler in media-storage und media-security via Horizon und Logs.

2. Hot-Storage voll oder kurz vor Limit

1. Warnungen bestätigen
   • System‑/Provider‑Warnungen (z.B. 90 % voll) bestätigen.
   • Prüfen, ob storage:monitor oder ähnliche Kommandos bereits Alerts ausgelöst haben.
2. Sofortmaßnahmen
   • Archivierung priorisieren: sicherstellen, dass storage:archive-pending regelmäßig läuft und die media-storage‑Queue abgearbeitet wird.
   • Temporäre Limits erhöhen, falls Provider dies erlaubt (z.B. S3‑Bucket praktisch „unbegrenzt“ vs. lokaler Disk).
3. Aufräumen
   • Alte Caches/Thumbnails, die problemlos neu generiert werden können, ggf. gezielt löschen.
   • Keine unüberlegten rm -rf Aktionen auf dem Storage – immer mit klarer Strategie arbeiten.

3. Archivierung hängt oder schlägt häufig fehl

1. Queue-Status prüfen
   • media-storage Queue‑Länge, Failed Jobs in Horizon prüfen.
   • Log‑Channel storage-jobs nach Fehlermeldungen durchsuchen.
2. Fehlerbilder auswerten
   • Typische Ursachen:
     • Netzwerk‑/Credential‑Probleme beim Zugriff auf den Archiv‑Bucket.
     • Zeitüberschreitungen bei sehr großen Medien.
     • Inkonsistente EventMediaAsset‑Einträge (Pfad nicht mehr vorhanden, falscher Disk‑Key).
3. Abhilfe
   • Netzwerk/Credentials fixen (z.B. S3‑Keys, Endpoints, Rechte).
   • Problematische Assets gezielt in den Logs identifizieren und manuell nachziehen (Kopie auf Archive‑Disk, Status auf archived setzen, Fehler‑Feld leeren).
   • Wenn viele Assets betroffen sind, lieber ein dediziertes Skript/Job bauen als ad‑hoc SQL.

4. Fehlende oder beschädigte Medien-Dateien

Wenn EventMediaAsset‑Einträge existieren, die zu nicht mehr vorhandenen Dateien zeigen:

1. Umfang ermitteln
   • Stichproben auf Basis der Fehlerlogs oder per Batch‑Check (z.B. ein Artisan‑Command, das exists() prüft).
2. Backup-Sicht
   • Prüfen, ob die Dateien noch im Backup vorhanden sind (Hot‑/Archive‑Backups).
3. Wiederherstellung
   • Fehlende Dateien an den erwarteten Pfad im Storage kopieren (Hot oder Archive).
   • EventMediaAsset‑Status und Timestamps ggf. aktualisieren (hot vs. archived).

Wenn keine Backups existieren, bleibt nur, die betroffenen Assets sauber als „nicht mehr verfügbar“ zu kennzeichnen und die Nutzer entsprechend zu informieren.

5. Nach einem Storage-Incident

• Monitoring schärfen
  • Schwellwerte in storage-monitor anpassen (Warnung/Kritisch), Alerts für Queues/Storage erweitern.
• Kapazitätsplanung
  • Erkenntnisse über Medienwachstum nutzen, um frühzeitig auf größere Volumes/Buckets oder häufigere Archivierung umzusteigen.
• Dokumentation
  • Incident und Maßnahmen in docs/process/changes/* dokumentieren.
  • Dieses Playbook aktualisieren, wenn neue Muster entdeckt wurden.

Dieses Playbook ist eng mit docs/ops/media-storage-spec.md und docs/ops/monitoring-observability.md verknüpft. Nutze diese Dokumente für Detailinformationen zu Queues, Thresholds und Storage‑Targets.