customer-installer/wiki/Troubleshooting.md

# Troubleshooting

Häufige Probleme und deren Lösungen beim Customer Installer System.

## 🔍 Diagnose-Tools

### Schnell-Diagnose

```bash
# Container-Status
pct status <ctid>

# Docker-Status
pct exec <ctid> -- systemctl status docker

# Container-Liste
pct exec <ctid> -- docker ps -a

# Logs anzeigen
tail -f logs/sb-<timestamp>.log
```

### Vollständige Diagnose

```bash
# Test-Suite ausführen
./test_complete_system.sh <ctid> <ip> <hostname>
```

## 🚨 Häufige Probleme

### 1. Installation schlägt fehl

#### Problem: Template-Download fehlgeschlagen

```
ERROR: Failed to download template
```

**Lösung:**
```bash
# Manuell Template herunterladen
pveam update
pveam download local debian-12-standard_12.12-1_amd64.tar.zst

# Installation erneut versuchen
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
```

#### Problem: Storage nicht gefunden

```
ERROR: Storage 'local-zfs' not found
```

**Lösung:**
```bash
# Verfügbare Storages auflisten
pvesm status

# Korrekten Storage verwenden
./install.sh --storage local-lvm --bridge vmbr0 --ip dhcp --vlan 90
```

#### Problem: Bridge nicht gefunden

```
ERROR: Bridge 'vmbr0' not found
```

**Lösung:**
```bash
# Verfügbare Bridges auflisten
ip link show | grep vmbr

# Korrekte Bridge verwenden
./install.sh --storage local-zfs --bridge vmbr1 --ip dhcp --vlan 90
```

### 2. Container startet nicht

#### Problem: Container bleibt im Status "stopped"

```bash
# Status prüfen
pct status <ctid>
# Output: stopped
```

**Lösung:**
```bash
# Container-Logs prüfen
journalctl -u pve-container@<ctid> -n 50

# Container manuell starten
pct start <ctid>

# Bei Fehlern: Container-Konfiguration prüfen
pct config <ctid>
```

#### Problem: "Failed to start container"

**Lösung:**
```bash
# AppArmor-Profil prüfen
aa-status | grep lxc

# Container im privilegierten Modus starten (nur für Debugging)
pct set <ctid> --unprivileged 0
pct start <ctid>

# Nach Debugging wieder unprivileged setzen
pct stop <ctid>
pct set <ctid> --unprivileged 1
pct start <ctid>
```

### 3. Docker-Probleme

#### Problem: Docker startet nicht

```bash
# Docker-Status prüfen
pct exec <ctid> -- systemctl status docker
# Output: failed
```

**Lösung:**
```bash
# Docker-Logs prüfen
pct exec <ctid> -- journalctl -u docker -n 50

# Docker neu starten
pct exec <ctid> -- systemctl restart docker

# Docker neu installieren (falls nötig)
pct exec <ctid> -- bash -c "curl -fsSL https://get.docker.com | sh"
```

#### Problem: Docker Compose nicht gefunden

```
docker: 'compose' is not a docker command
```

**Lösung:**
```bash
# Docker Compose Plugin installieren
pct exec <ctid> -- apt-get update
pct exec <ctid> -- apt-get install -y docker-compose-plugin

# Version prüfen
pct exec <ctid> -- docker compose version
```

### 4. Container-Probleme

#### Problem: PostgreSQL startet nicht

```bash
# Container-Status prüfen
pct exec <ctid> -- docker ps -a | grep postgres
# Output: Exited (1)
```

**Lösung:**
```bash
# Logs prüfen
pct exec <ctid> -- docker logs customer-postgres

# Häufige Ursachen:
# 1. Volume-Permissions
pct exec <ctid> -- chown -R 999:999 /opt/customer-stack/volumes/postgres-data

# 2. Korrupte Daten
pct exec <ctid> -- rm -rf /opt/customer-stack/volumes/postgres-data/*
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml up -d postgres

# 3. Port bereits belegt
pct exec <ctid> -- netstat -tlnp | grep 5432
```

#### Problem: n8n startet nicht

```bash
# Container-Status prüfen
pct exec <ctid> -- docker ps -a | grep n8n
# Output: Exited (1)
```

**Lösung:**
```bash
# Logs prüfen
pct exec <ctid> -- docker logs n8n

# Häufige Ursachen:
# 1. Datenbank nicht erreichbar
pct exec <ctid> -- docker exec n8n nc -zv postgres 5432

# 2. Volume-Permissions
pct exec <ctid> -- chown -R 1000:1000 /opt/customer-stack/volumes/n8n-data

# 3. Environment-Variablen fehlen
pct exec <ctid> -- cat /opt/customer-stack/.env | grep N8N_ENCRYPTION_KEY

# Container neu starten
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart n8n
```

#### Problem: PostgREST startet nicht

```bash
# Container-Status prüfen
pct exec <ctid> -- docker ps -a | grep postgrest
# Output: Exited (1)
```

**Lösung:**
```bash
# Logs prüfen
pct exec <ctid> -- docker logs customer-postgrest

# Häufige Ursachen:
# 1. PostgreSQL nicht erreichbar
pct exec <ctid> -- docker exec customer-postgrest nc -zv postgres 5432

# 2. JWT-Secret fehlt
pct exec <ctid> -- cat /opt/customer-stack/.env | grep PGRST_JWT_SECRET

# 3. Schema nicht gefunden
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "\dt"

# Container neu starten
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart postgrest
```

### 5. Netzwerk-Probleme

#### Problem: Container nicht erreichbar

```bash
# Ping-Test
ping <container-ip>
# Output: Destination Host Unreachable
```

**Lösung:**
```bash
# 1. IP-Adresse prüfen
pct exec <ctid> -- ip addr show

# 2. Routing prüfen
ip route | grep <container-ip>

# 3. Firewall prüfen
iptables -L -n | grep <container-ip>

# 4. VLAN-Konfiguration prüfen
pct config <ctid> | grep net0
```

#### Problem: Ports nicht erreichbar

```bash
# Port-Test
curl http://<ip>:5678/
# Output: Connection refused
```

**Lösung:**
```bash
# 1. Container läuft?
pct exec <ctid> -- docker ps | grep n8n

# 2. Port-Binding prüfen
pct exec <ctid> -- netstat -tlnp | grep 5678

# 3. Docker-Netzwerk prüfen
pct exec <ctid> -- docker network inspect customer-stack_customer-net

# 4. Firewall im Container prüfen
pct exec <ctid> -- iptables -L -n
```

### 6. Datenbank-Probleme

#### Problem: pgvector Extension fehlt

```bash
# Extension prüfen
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "SELECT * FROM pg_extension WHERE extname='vector';"
# Output: (0 rows)
```

**Lösung:**
```bash
# Extension manuell installieren
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Version prüfen
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "SELECT extversion FROM pg_extension WHERE extname='vector';"
```

#### Problem: Tabellen fehlen

```bash
# Tabellen prüfen
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "\dt"
# Output: Did not find any relations
```

**Lösung:**
```bash
# Schema manuell initialisieren
pct exec <ctid> -- docker exec -i customer-postgres \
  psql -U customer -d customer < /opt/customer-stack/init_pgvector.sql

# Oder SQL direkt ausführen
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "
CREATE TABLE IF NOT EXISTS documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  content TEXT NOT NULL,
  metadata JSONB,
  embedding vector(384),
  created_at TIMESTAMPTZ DEFAULT NOW()
);
"
```

### 7. n8n-Probleme

#### Problem: n8n Login funktioniert nicht

```bash
# Login testen
curl -X POST http://<ip>:5678/rest/login \
  -H "Content-Type: application/json" \
  -d '{"emailOrLdapLoginId":"admin@userman.de","password":"..."}'
# Output: {"code":"invalid_credentials"}
```

**Lösung:**
```bash
# 1. Credentials aus Datei laden
cat credentials/sb-<timestamp>.json | jq -r '.n8n'

# 2. Owner neu erstellen
pct exec <ctid> -- docker exec n8n \
  n8n user-management:reset --email=admin@userman.de --password=NewPassword123

# 3. n8n neu starten
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart n8n
```

#### Problem: Workflow nicht gefunden

```bash
# Workflows auflisten
curl -s http://<ip>:5678/rest/workflows \
  -H "Cookie: ..." | jq '.data | length'
# Output: 0
```

**Lösung:**
```bash
# Workflow manuell importieren
pct exec <ctid> -- bash /opt/customer-stack/reload-workflow.sh

# Oder Workflow-Reload-Service ausführen
pct exec <ctid> -- systemctl start n8n-workflow-reload.service

# Status prüfen
pct exec <ctid> -- systemctl status n8n-workflow-reload.service
```

#### Problem: Credentials fehlen

```bash
# Credentials auflisten
curl -s http://<ip>:5678/rest/credentials \
  -H "Cookie: ..." | jq '.data | length'
# Output: 0
```

**Lösung:**
```bash
# Credentials manuell erstellen via n8n UI
# Oder update_credentials.sh verwenden
./update_credentials.sh \
  --ctid <ctid> \
  --ollama-url http://192.168.45.3:11434
```

### 8. API-Probleme

#### Problem: PostgREST API gibt 401 zurück

```bash
curl http://<ip>:3000/documents
# Output: {"code":"PGRST301","message":"JWT invalid"}
```

**Lösung:**
```bash
# 1. API-Key verwenden
ANON_KEY=$(cat credentials/sb-*.json | jq -r '.supabase.anon_key')
curl http://<ip>:3000/documents \
  -H "apikey: ${ANON_KEY}" \
  -H "Authorization: Bearer ${ANON_KEY}"

# 2. JWT-Secret prüfen
pct exec <ctid> -- cat /opt/customer-stack/.env | grep PGRST_JWT_SECRET

# 3. PostgREST neu starten
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart postgrest
```

#### Problem: Webhook gibt 404 zurück

```bash
curl -X POST http://<ip>:5678/webhook/rag-chat-webhook/chat
# Output: 404 Not Found
```

**Lösung:**
```bash
# 1. Workflow aktiv?
curl -s http://<ip>:5678/rest/workflows \
  -H "Cookie: ..." | jq '.data[] | select(.name=="RAG KI-Bot") | .active'

# 2. Workflow aktivieren
# Via n8n UI oder API

# 3. Webhook-URL prüfen
curl -s http://<ip>:5678/rest/workflows \
  -H "Cookie: ..." | jq '.data[] | select(.name=="RAG KI-Bot") | .nodes[] | select(.type=="n8n-nodes-base.webhook")'
```

### 9. Ollama-Integration

#### Problem: Ollama nicht erreichbar

```bash
curl http://192.168.45.3:11434/api/tags
# Output: Connection refused
```

**Lösung:**
```bash
# 1. Ollama-Server prüfen
ssh user@192.168.45.3 "systemctl status ollama"

# 2. Firewall prüfen
ssh user@192.168.45.3 "iptables -L -n | grep 11434"

# 3. Alternative URL verwenden
./update_credentials.sh \
  --ctid <ctid> \
  --ollama-url http://ollama.local:11434
```

#### Problem: Modell nicht gefunden

```bash
curl -X POST http://192.168.45.3:11434/api/generate \
  -d '{"model":"ministral-3:3b","prompt":"test"}'
# Output: {"error":"model not found"}
```

**Lösung:**
```bash
# Modell herunterladen
ssh user@192.168.45.3 "ollama pull ministral-3:3b"

# Verfügbare Modelle auflisten
curl http://192.168.45.3:11434/api/tags
```

### 10. Performance-Probleme

#### Problem: Langsame Vektor-Suche

**Lösung:**
```bash
# Index prüfen
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "\d documents"

# Index neu erstellen
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "
DROP INDEX IF EXISTS documents_embedding_idx;
CREATE INDEX documents_embedding_idx ON documents 
USING ivfflat (embedding vector_cosine_ops) 
WITH (lists = 100);
"

# Statistiken aktualisieren
pct exec <ctid> -- docker exec customer-postgres \
  psql -U customer -d customer -c "ANALYZE documents;"
```

#### Problem: Hohe Memory-Nutzung

**Lösung:**
```bash
# Memory-Nutzung prüfen
pct exec <ctid> -- free -m

# Container-Limits setzen
pct set <ctid> --memory 8192

# Docker-Container-Limits
pct exec <ctid> -- docker update --memory 2g customer-postgres
pct exec <ctid> -- docker update --memory 2g n8n
```

## 🔧 Erweiterte Diagnose

### Log-Analyse

```bash
# Alle Logs sammeln
mkdir -p debug-logs
pct exec <ctid> -- docker logs customer-postgres > debug-logs/postgres.log 2>&1
pct exec <ctid> -- docker logs customer-postgrest > debug-logs/postgrest.log 2>&1
pct exec <ctid> -- docker logs n8n > debug-logs/n8n.log 2>&1
pct exec <ctid> -- journalctl -u docker > debug-logs/docker.log 2>&1

# Logs analysieren
grep -i error debug-logs/*.log
grep -i warning debug-logs/*.log
```

### Netzwerk-Diagnose

```bash
# Vollständige Netzwerk-Analyse
pct exec <ctid> -- ip addr show
pct exec <ctid> -- ip route show
pct exec <ctid> -- netstat -tlnp
pct exec <ctid> -- docker network ls
pct exec <ctid> -- docker network inspect customer-stack_customer-net
```

### Performance-Analyse

```bash
# CPU-Nutzung
pct exec <ctid> -- top -b -n 1

# Disk I/O
pct exec <ctid> -- iostat -x 1 5

# Netzwerk-Traffic
pct exec <ctid> -- iftop -t -s 5
```

## 📚 Weiterführende Hilfe

- [Installation](Installation.md) - Installations-Anleitung
- [Testing](Testing.md) - Test-Suites
- [Monitoring](Monitoring.md) - Überwachung
- [Architecture](Architecture.md) - System-Architektur

---

**Support-Kontakt:**
Bei persistierenden Problemen erstellen Sie bitte ein Issue im Repository mit:
1. Fehlerbeschreibung
2. Log-Dateien
3. System-Informationen
4. Reproduktionsschritte