Troubleshooting hinzugefügt

2026-01-25 09:34:46 -08:00
parent 297c520de2
commit 2dc9cddb81
1 changed files with 580 additions and 0 deletions
@@ -0,0 +1,580 @@
+# 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