> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehlersuche

> Störungen einer On-Premise-Installation eingrenzen: Standardprüfungen, Logs und Diagnosebefehle

Diese Seite richtet sich an Administratoren, vorzugsweise mit Shell-Zugang auf dem Server, auf dem VARIOS AI als Docker-Installation läuft. Sie beschreibt, wo welche Logs liegen und mit welchen Befehlen Sie eine Störung eingrenzen.

<Note>
  Alle Befehle auf dieser Seite laufen im **Installationsverzeichnis**, also dort, wo `docker-compose.yml` und `.env` liegen. Die [Installationsanleitung](/de/extended-support/installation/guide) empfiehlt dafür `/docker/variosai`, und die Beispiele auf dieser Seite verwenden diesen Pfad. Ihre Installation kann jedoch an einer anderen Stelle liegen. Setzen Sie in diesem Fall überall Ihren eigenen Pfad ein. Docker-Befehle erfordern in der Regel `sudo` oder eine Mitgliedschaft in der Gruppe `docker`.
</Note>

## Standardprüfungen zuerst

### Läuft die Installation auf der aktuellen Version und ist der Fehler bereits behoben?

Unter Administration → Einstellungen → [Systeminformationen](/de/extended-support/admin/settings/system-information) zeigt **System-Stand**, ob ein Update verfügbar ist. Dort steht auch Ihr ausgewählter **Release-Kanal**.

Prüfen Sie im [Changelog](/de/extended-support/changelog/changelog) die Abschnitte **Bugfixes** und **Verbesserungen** aller Versionen zwischen Ihrer installierten und der aktuellen Version. Achten Sie dabei auf Einträge, die zusätzlich zum Update eine manuelle Anpassung verlangen: Solche Hinweise stehen im Changelog-Eintrag selbst.

<Warning>
  Erstellen Sie vor jedem Update einen Snapshot der virtuellen Maschine, siehe [Backup und Wiederherstellung](/de/extended-support/operations/backup). Ein Update ist ohne Snapshot nicht zurückzunehmen.
</Warning>

### System-Log prüfen

Administration → [Logs](/de/extended-support/admin/logs) zeigt System-, Sicherheits- und SCIM-Logs, ohne dass Sie sich auf dem Server anmelden müssen. Das `System.log` ist die erste Anlaufstelle für die Fehleranalyse.

### Docker-Logs prüfen

Die Docker-Logs enthalten alles, was die Container melden.

```bash theme={null}
cd /docker/variosai   # oder Ihr Installationsverzeichnis
docker compose ps
docker compose logs --since 1h | grep -i -e error -e exception -e fatal
```

Welche Logs es darüber hinaus gibt und wo sie liegen, steht weiter unten unter [Wo welche Logs liegen](#wo-welche-logs-liegen).

### Störung eingrenzen

Diese Angaben entscheiden, wo Sie suchen, und der Support fragt sie ohnehin ab.

| Frage | Wozu |
| - | - |
| Seit wann tritt der Fehler auf? | Grenzt den Zeitraum in den Logs ein |
| Was wurde zuletzt geändert? | Update, Zertifikat, Firewallregel, Identitätsanbieter, Modellanbieter, Netzwerk |
| Betrifft es alle Benutzer oder einzelne? | Einzelne Benutzer deuten auf Rollen, Gruppen oder Berechtigungen, alle auf einen Dienst |
| Betrifft es alle Modelle oder eines? | Ein einzelnes Modell deutet auf den Anbieter, alle auf die Installation |
| Ist der Fehler reproduzierbar? | Ein reproduzierbarer Fehler lässt sich mit offenem Log nachstellen |
| Wie lautet die Meldung im Wortlaut, und wann genau erschien sie? | Nur damit lässt sich der passende Log-Eintrag finden |

<Tip>
  Stellen Sie den Fehler mit einem eigenen Testkonto nach und lesen Sie dabei `sudo tail -f Data/Logs/System.log` mit. So sehen Sie die Einträge, die zu genau diesem Vorgang gehören, statt in der Historie zu suchen.
</Tip>

### Grundregeln für Eingriffe auf dem Server

* **Snapshot vor Eingriffen**, die Konfiguration, Datenbank oder Dateien verändern.
* **Eine Änderung nach der anderen** und jeweils nachsehen, ob sie gewirkt hat. Mehrere Änderungen gleichzeitig machen das Ergebnis unbrauchbar.
* **Log-Dateien nie bearbeiten oder löschen.** Die Audit-, Auth-, SCIM-, DLP- und Konnektor-Logs sind mit Prüfsummen gesichert und verweigern nach einer Änderung weitere Schreibvorgänge.
* **Die `.env` nie weitergeben.** Sie enthält Datenbankpasswort, Client-Secret und API-Token.
* **Serverzeit prüfen** (`timedatectl status`). Eine abweichende Uhrzeit führt zu abgelehnten Anmeldetoken und fehlschlagenden Zertifikatsprüfungen.
* **Supportzugang nur bei Bedarf aktivieren** und danach wieder deaktivieren, siehe [Systeminformationen](/de/extended-support/admin/settings/system-information).

## Diagnose nach Auswertung des System-Logs

Arbeiten Sie diese Befehle der Reihe nach ab. In den meisten Fällen zeigt bereits einer davon die Ursache.

```bash theme={null}
cd /docker/variosai   # oder Ihr Installationsverzeichnis

# 1. Laufen alle Container, und startet einer ständig neu?
docker compose ps

# 2. Was meldet die Anwendung?
docker compose logs --tail=200 php

# 3. Ist der Reverse-Proxy sauber gestartet?
docker compose logs --tail=100 traefik

# 4. Sind Speicherplatz und Arbeitsspeicher frei?
df -h
free -h
docker system df

# 5. Hat der Kernel einen Prozess wegen Speichermangels beendet?
sudo dmesg -T | grep -i -e "out of memory" -e "killed process" | tail
```

### Die Spalte `STATUS` richtig lesen

| Anzeige in `docker compose ps` | Bedeutung | Nächster Schritt |
| - | - | - |
| `Up … (healthy)` | Dienst läuft, Healthcheck erfolgreich | Ursache liegt woanders |
| `Up …` ohne Healthcheck | Prozess läuft, sagt aber nichts über die Funktion aus | Log des Dienstes prüfen |
| `Restarting …` | Der Container stürzt ab und wird neu gestartet | `docker compose logs <dienst>`, meist Konfigurations- oder Rechtefehler |
| `Exited (137)` | Der Prozess wurde hart beendet, fast immer Speichermangel | `dmesg`, Arbeitsspeicher prüfen, siehe [Sizing](/de/extended-support/operations/sizing) |
| `Exited (1)` | Der Dienst hat sich selbst mit einer Fehlermeldung beendet | Letzte Zeilen im Container-Log lesen |
| `Created` | Der Container wurde nie gestartet | `docker compose up -d`, Image oder Registry-Anmeldung prüfen |

<Tip>
  Den Exit-Code eines bereits beendeten Containers liefert `docker inspect --format '{{.State.ExitCode}} {{.State.Error}}' $(docker compose ps -aq php)`.
</Tip>

## Wo welche Logs liegen

VARIOS AI schreibt an drei Stellen: in die Container-Logs von Docker, in Dateien unterhalb des Installationsverzeichnisses und, wenn konfiguriert, an ein Syslog-Ziel.

### Container-Logs

Alles, was die Dienste nach `stdout` und `stderr` schreiben, liegt im Docker-Log.

<Warning>
  Container-Logs überleben einen Neustart des Containers, nicht aber ein `docker compose down`, ein Neuanlegen des Containers oder ein `docker system prune`. Der Update-Helfer `varios.sh` führt nach jedem Update ein `docker system prune -f -a --volumes` aus. Sichern Sie Logs vor einem Update, wenn Sie einen Fehler noch untersuchen wollen.
</Warning>

### Anwendungs-Logs im Dateisystem

Diese Dateien liegen auf dem Host unter `./Data/Logs` und im Container unter `/data/Data/Logs`. Sie sind die wichtigste Quelle für alles, was innerhalb der Anwendung passiert, und überleben Container-Neustarts und Updates.

| Datei | Inhalt |
| - | - |
| `Audit.JJJJ_MM_TT.log` | Audit-Log aller nachvollziehbaren Aktionen, eine Datei pro Tag |
| `Auth.JJJJ_MM_TT.log` | Anmeldungen und Abmeldungen, auch fehlgeschlagene |
| `Scim.JJJJ_MM_TT.log` | Benutzer- und Gruppensynchronisation per SCIM |
| `Dlp.JJJJ_MM_TT.log` | Treffer und Entscheidungen der DLP-Prüfung |
| `Connector.JJJJ_MM_TT.log` | Aufrufe von Konnektoren und deren Antworten |
| `System*.log` | Systemmeldungen. `System.log` ist das Log, das die Oberfläche unter Administration → Logs anzeigt; das Framework legt daneben Dateien mit dem Flow-Kontext im Namen an |
| `Security*.log` | Sicherheitsrelevante Ereignisse des Frameworks |
| `Chats.log` | Chat-Verarbeitung, rotiert bei etwa 100 MB nach `Chats.log.1` |
| `Exceptions/*.txt` | Vollständige Stacktraces; eine Datei je aufgetretener Ausnahme |

Verschaffen Sie sich mit `ls` einen Überblick über die tatsächlich vorhandenen Dateien, statt einen Dateinamen zu raten:

```bash theme={null}
sudo ls -la Data/Logs
sudo ls -lat Data/Logs/Exceptions | head
```

Eine Meldung in `System.log` nennt in der Regel den Dateinamen des passenden Stacktraces. So kommen Sie von der Meldung zur vollständigen Ausnahme:

```bash theme={null}
sudo grep -i "exception" Data/Logs/System*.log | tail -5
sudo cat Data/Logs/Exceptions/<dateiname>.txt
```

<Note>
  Steht `LOG_OUTPUT` in der `.env` auf `syslog`, schreibt VARIOS AI **keine** Log-Dateien mehr, sondern ausschließlich an das unter `LOG_SYSLOG_HOST` und `LOG_SYSLOG_PORT` konfigurierte Ziel. Für eine lokale Fehlersuche setzen Sie `LOG_OUTPUT=both` und starten den `php`-Dienst neu.
</Note>

## Anwendung neu aufsetzen

Führen Sie im Installationsverzeichnis folgenden Befehl aus, um Caches zu leeren und neu aufzubauen, Migrationen auszuführen und alle Prozesse neu zu starten:

```bash theme={null}
docker compose exec php ./update.sh
```

<Warning>
  Der Befehl startet alle Prozesse im `php`-Container neu. VARIOS AI ist währenddessen kurz nicht erreichbar.
</Warning>