customer-installer/wiki/Troubleshooting.md

Troubleshooting

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

🔍 Diagnose-Tools

Schnell-Diagnose

# 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

# 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:

# 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:

# 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:

# 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"

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

Lösung:

# 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:

# 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

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

Lösung:

# 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:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

# 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:

# 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

# 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:

# 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

# 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:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

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

Lösung:

# 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

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:

# 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:

# 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:

# 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

# 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

# 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

# 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 - Installations-Anleitung
• Testing - Test-Suites
• Monitoring - Überwachung
• Architecture - 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