516 lines
11 KiB
Markdown
516 lines
11 KiB
Markdown
# FAQ - Häufig gestellte Fragen
|
|
|
|
Antworten auf häufig gestellte Fragen zum Customer Installer System.
|
|
|
|
## 🎯 Allgemein
|
|
|
|
### Was ist der Customer Installer?
|
|
|
|
Der Customer Installer ist ein automatisiertes Deployment-System für RAG (Retrieval-Augmented Generation) Stacks auf Proxmox VE. Es erstellt LXC-Container mit PostgreSQL, PostgREST, n8n und Ollama-Integration.
|
|
|
|
### Für wen ist das System gedacht?
|
|
|
|
- Entwickler, die schnell RAG-Systeme deployen möchten
|
|
- Unternehmen, die KI-Chatbots mit eigenem Wissen betreiben wollen
|
|
- Teams, die Workflow-Automation mit KI kombinieren möchten
|
|
|
|
### Welche Voraussetzungen gibt es?
|
|
|
|
- Proxmox VE Server (7.x oder 8.x)
|
|
- Root-Zugriff
|
|
- Netzwerk-Konfiguration (Bridge, optional VLAN)
|
|
- Optional: Ollama-Server für KI-Modelle
|
|
|
|
## 🚀 Installation
|
|
|
|
### Wie lange dauert die Installation?
|
|
|
|
Eine typische Installation dauert 5-10 Minuten, abhängig von:
|
|
- Netzwerk-Geschwindigkeit (Template-Download)
|
|
- Server-Performance
|
|
- APT-Proxy-Verfügbarkeit
|
|
|
|
### Kann ich mehrere Container installieren?
|
|
|
|
Ja! Jede Installation erstellt einen neuen Container mit eindeutiger CTID. Sie können beliebig viele Container parallel betreiben.
|
|
|
|
```bash
|
|
# Container 1
|
|
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
|
|
|
|
# Container 2
|
|
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
|
|
|
|
# Container 3
|
|
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
|
|
```
|
|
|
|
### Wie funktioniert die CTID-Generierung?
|
|
|
|
Die CTID wird automatisch generiert basierend auf dem aktuellen Unix-Timestamp. Dies garantiert Eindeutigkeit für die nächsten 10 Jahre.
|
|
|
|
```bash
|
|
# Format: 7XXXXXXXXX (10 Stellen)
|
|
# Beispiel: 769276659
|
|
```
|
|
|
|
### Kann ich eine eigene CTID angeben?
|
|
|
|
Ja, mit dem `--ctid` Parameter:
|
|
|
|
```bash
|
|
./install.sh --ctid 100 --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
|
|
```
|
|
|
|
**Achtung:** Stellen Sie sicher, dass die CTID nicht bereits verwendet wird!
|
|
|
|
## 🔧 Konfiguration
|
|
|
|
### Welche Ressourcen werden standardmäßig verwendet?
|
|
|
|
- **CPU:** Unlimited
|
|
- **RAM:** 4096 MB
|
|
- **Swap:** 512 MB
|
|
- **Disk:** 50 GB
|
|
- **Netzwerk:** DHCP, VLAN 90
|
|
|
|
### Kann ich die Ressourcen anpassen?
|
|
|
|
Ja, alle Ressourcen sind konfigurierbar:
|
|
|
|
```bash
|
|
./install.sh \
|
|
--cores 4 \
|
|
--memory 8192 \
|
|
--swap 1024 \
|
|
--disk 100 \
|
|
--storage local-zfs \
|
|
--bridge vmbr0 \
|
|
--ip dhcp \
|
|
--vlan 90
|
|
```
|
|
|
|
### Wie verwende ich eine statische IP?
|
|
|
|
```bash
|
|
./install.sh \
|
|
--storage local-zfs \
|
|
--bridge vmbr0 \
|
|
--ip 192.168.45.100/24 \
|
|
--vlan 90
|
|
```
|
|
|
|
### Kann ich VLAN deaktivieren?
|
|
|
|
Ja, setzen Sie `--vlan 0`:
|
|
|
|
```bash
|
|
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 0
|
|
```
|
|
|
|
## 🔐 Credentials
|
|
|
|
### Wo werden die Credentials gespeichert?
|
|
|
|
Automatisch in `credentials/sb-<timestamp>.json` nach erfolgreicher Installation.
|
|
|
|
### Wie kann ich Credentials später ändern?
|
|
|
|
Mit dem `update_credentials.sh` Script:
|
|
|
|
```bash
|
|
./update_credentials.sh \
|
|
--ctid 769276659 \
|
|
--ollama-url http://ollama.local:11434 \
|
|
--n8n-password "NewPassword123"
|
|
```
|
|
|
|
### Sind die Credentials sicher?
|
|
|
|
Ja:
|
|
- Gespeichert in `.gitignore`-geschütztem Verzeichnis
|
|
- Nicht im Git-Repository
|
|
- Nur auf dem Proxmox-Host zugänglich
|
|
- Passwörter werden automatisch generiert (14+ Zeichen)
|
|
|
|
### Wie kann ich das n8n-Passwort zurücksetzen?
|
|
|
|
```bash
|
|
pct exec <ctid> -- docker exec n8n \
|
|
n8n user-management:reset \
|
|
--email=admin@userman.de \
|
|
--password=NewPassword123
|
|
```
|
|
|
|
## 🐳 Docker & Container
|
|
|
|
### Welche Docker-Container werden erstellt?
|
|
|
|
1. **customer-postgres** - PostgreSQL 16 mit pgvector
|
|
2. **customer-postgrest** - PostgREST API
|
|
3. **n8n** - Workflow-Automation
|
|
|
|
### Wie kann ich in einen Container einloggen?
|
|
|
|
```bash
|
|
# In LXC-Container
|
|
pct enter <ctid>
|
|
|
|
# In Docker-Container
|
|
pct exec <ctid> -- docker exec -it n8n sh
|
|
pct exec <ctid> -- docker exec -it customer-postgres bash
|
|
```
|
|
|
|
### Wie starte ich Container neu?
|
|
|
|
```bash
|
|
# Einzelner Docker-Container
|
|
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart n8n
|
|
|
|
# Alle Docker-Container
|
|
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart
|
|
|
|
# LXC-Container
|
|
pct restart <ctid>
|
|
```
|
|
|
|
### Wie stoppe ich Container?
|
|
|
|
```bash
|
|
# Docker-Container stoppen
|
|
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml down
|
|
|
|
# LXC-Container stoppen
|
|
pct stop <ctid>
|
|
```
|
|
|
|
## 📊 Datenbank
|
|
|
|
### Welche PostgreSQL-Version wird verwendet?
|
|
|
|
PostgreSQL 16 (Alpine-basiert)
|
|
|
|
### Ist pgvector installiert?
|
|
|
|
Ja, pgvector v0.5.1 ist vorinstalliert und konfiguriert.
|
|
|
|
### Wie kann ich auf die Datenbank zugreifen?
|
|
|
|
```bash
|
|
# Via Docker
|
|
pct exec <ctid> -- docker exec -it customer-postgres \
|
|
psql -U customer -d customer
|
|
|
|
# Credentials aus Datei
|
|
cat credentials/sb-*.json | jq -r '.postgres'
|
|
```
|
|
|
|
### Wie groß ist die Embedding-Dimension?
|
|
|
|
384 Dimensionen (für nomic-embed-text Modell)
|
|
|
|
### Kann ich die Dimension ändern?
|
|
|
|
Ja, aber Sie müssen:
|
|
1. Tabelle neu erstellen
|
|
2. Anderes Embedding-Modell verwenden
|
|
3. Alle Dokumente neu embedden
|
|
|
|
```sql
|
|
-- Neue Dimension (z.B. 768 für andere Modelle)
|
|
CREATE TABLE documents (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
content TEXT NOT NULL,
|
|
metadata JSONB,
|
|
embedding vector(768), -- Geänderte Dimension
|
|
created_at TIMESTAMPTZ DEFAULT NOW()
|
|
);
|
|
```
|
|
|
|
## 🤖 n8n & Workflows
|
|
|
|
### Welcher Workflow wird installiert?
|
|
|
|
Der "RAG KI-Bot" Workflow mit:
|
|
- Chat-Webhook
|
|
- Document-Upload-Form
|
|
- Vektor-Embedding
|
|
- Similarity-Search
|
|
- Chat-Completion
|
|
|
|
### Wie kann ich den Workflow anpassen?
|
|
|
|
1. Via n8n Web-Interface: `http://<ip>:5678`
|
|
2. Login mit Credentials aus `credentials/sb-*.json`
|
|
3. Workflow bearbeiten und speichern
|
|
|
|
### Wird der Workflow bei Neustart geladen?
|
|
|
|
Ja, automatisch via `n8n-workflow-reload.service`
|
|
|
|
### Wie kann ich eigene Workflows importieren?
|
|
|
|
```bash
|
|
# Workflow-Datei angeben bei Installation
|
|
./install.sh \
|
|
--workflow-file /path/to/my-workflow.json \
|
|
--storage local-zfs \
|
|
--bridge vmbr0 \
|
|
--ip dhcp \
|
|
--vlan 90
|
|
```
|
|
|
|
### Wie viele Workflows kann ich haben?
|
|
|
|
Unbegrenzt! Sie können beliebig viele Workflows in n8n erstellen.
|
|
|
|
## 🔗 API & Integration
|
|
|
|
### Welche APIs sind verfügbar?
|
|
|
|
1. **n8n API** - `http://<ip>:5678/rest/*`
|
|
2. **PostgREST API** - `http://<ip>:3000/*`
|
|
3. **Chat-Webhook** - `http://<ip>:5678/webhook/rag-chat-webhook/chat`
|
|
4. **Upload-Form** - `http://<ip>:5678/form/rag-upload-form`
|
|
|
|
### Wie authentifiziere ich mich bei der API?
|
|
|
|
**n8n API:**
|
|
```bash
|
|
# Login
|
|
curl -X POST http://<ip>:5678/rest/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"emailOrLdapLoginId":"admin@userman.de","password":"..."}'
|
|
```
|
|
|
|
**PostgREST API:**
|
|
```bash
|
|
# Mit API-Key
|
|
curl http://<ip>:3000/documents \
|
|
-H "apikey: ${ANON_KEY}" \
|
|
-H "Authorization: Bearer ${ANON_KEY}"
|
|
```
|
|
|
|
### Ist die API öffentlich zugänglich?
|
|
|
|
Standardmäßig nur im lokalen Netzwerk. Für öffentlichen Zugriff:
|
|
1. NGINX Reverse Proxy einrichten
|
|
2. SSL-Zertifikat konfigurieren
|
|
3. Firewall-Regeln anpassen
|
|
|
|
### Wie teste ich die Chat-API?
|
|
|
|
```bash
|
|
curl -X POST http://<ip>:5678/webhook/rag-chat-webhook/chat \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"query":"Was ist RAG?"}'
|
|
```
|
|
|
|
## 🤖 Ollama-Integration
|
|
|
|
### Muss ich Ollama selbst installieren?
|
|
|
|
Ja, Ollama läuft auf einem separaten Server. Der Customer Installer verbindet sich nur damit.
|
|
|
|
### Welche Ollama-Modelle werden verwendet?
|
|
|
|
Standardmäßig:
|
|
- **Chat:** ministral-3:3b
|
|
- **Embeddings:** nomic-embed-text:latest
|
|
|
|
### Kann ich andere Modelle verwenden?
|
|
|
|
Ja:
|
|
|
|
```bash
|
|
# Bei Installation
|
|
./install.sh \
|
|
--ollama-model llama2:latest \
|
|
--embedding-model all-minilm:latest \
|
|
--storage local-zfs \
|
|
--bridge vmbr0 \
|
|
--ip dhcp \
|
|
--vlan 90
|
|
|
|
# Nach Installation
|
|
./update_credentials.sh \
|
|
--ctid <ctid> \
|
|
--ollama-model llama2:latest \
|
|
--embedding-model all-minilm:latest
|
|
```
|
|
|
|
### Wie ändere ich die Ollama-URL?
|
|
|
|
```bash
|
|
./update_credentials.sh \
|
|
--ctid <ctid> \
|
|
--ollama-url http://ollama.local:11434
|
|
```
|
|
|
|
### Funktioniert es ohne Ollama?
|
|
|
|
Nein, Ollama ist erforderlich für:
|
|
- Text-Embeddings
|
|
- Chat-Completions
|
|
|
|
Sie können aber alternative APIs verwenden, indem Sie den n8n-Workflow anpassen.
|
|
|
|
## 🧪 Testing
|
|
|
|
### Wie teste ich die Installation?
|
|
|
|
```bash
|
|
./test_complete_system.sh <ctid> <ip> <hostname>
|
|
```
|
|
|
|
### Was wird getestet?
|
|
|
|
- Container-Status
|
|
- Docker-Installation
|
|
- Datenbank-Konnektivität
|
|
- API-Endpoints
|
|
- Workflow-Status
|
|
- Credentials
|
|
- Netzwerk-Konfiguration
|
|
|
|
### Wie lange dauern die Tests?
|
|
|
|
Ca. 90 Sekunden für alle 40+ Tests.
|
|
|
|
### Was mache ich bei fehlgeschlagenen Tests?
|
|
|
|
1. Test-Output analysieren
|
|
2. [Troubleshooting](Troubleshooting.md) konsultieren
|
|
3. Logs prüfen
|
|
4. Bei Bedarf Issue erstellen
|
|
|
|
## 🔄 Updates & Wartung
|
|
|
|
### Wie aktualisiere ich das System?
|
|
|
|
```bash
|
|
# Docker-Images aktualisieren
|
|
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml pull
|
|
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml up -d
|
|
|
|
# System-Updates
|
|
pct exec <ctid> -- apt-get update
|
|
pct exec <ctid> -- apt-get upgrade -y
|
|
```
|
|
|
|
### Wie sichere ich Daten?
|
|
|
|
```bash
|
|
# Volumes sichern
|
|
pct exec <ctid> -- tar -czf /tmp/backup.tar.gz \
|
|
/opt/customer-stack/volumes/
|
|
|
|
# Backup herunterladen
|
|
pct pull <ctid> /tmp/backup.tar.gz ./backup-$(date +%Y%m%d).tar.gz
|
|
```
|
|
|
|
### Wie stelle ich Daten wieder her?
|
|
|
|
```bash
|
|
# Backup hochladen
|
|
pct push <ctid> ./backup-20260124.tar.gz /tmp/backup.tar.gz
|
|
|
|
# Volumes wiederherstellen
|
|
pct exec <ctid> -- tar -xzf /tmp/backup.tar.gz -C /
|
|
```
|
|
|
|
### Wie lösche ich einen Container?
|
|
|
|
```bash
|
|
# Container stoppen
|
|
pct stop <ctid>
|
|
|
|
# Container löschen
|
|
pct destroy <ctid>
|
|
|
|
# Credentials-Datei löschen (optional)
|
|
rm credentials/sb-<timestamp>.json
|
|
```
|
|
|
|
## 📈 Performance
|
|
|
|
### Wie viele Dokumente kann das System verarbeiten?
|
|
|
|
Abhängig von:
|
|
- RAM (mehr RAM = mehr Dokumente)
|
|
- Disk-Performance (SSD empfohlen)
|
|
- pgvector-Index-Konfiguration
|
|
|
|
Typisch: 10.000 - 100.000 Dokumente
|
|
|
|
### Wie optimiere ich die Performance?
|
|
|
|
1. **Mehr RAM:** `pct set <ctid> --memory 8192`
|
|
2. **SSD-Storage:** ZFS mit SSD
|
|
3. **Index-Tuning:** IVFFlat-Parameter anpassen
|
|
4. **Connection-Pooling:** PostgREST-Konfiguration
|
|
|
|
### Wie skaliere ich das System?
|
|
|
|
- **Vertikal:** Mehr CPU/RAM für Container
|
|
- **Horizontal:** Mehrere Container mit Load-Balancer
|
|
- **Datenbank:** PostgreSQL-Replikation
|
|
|
|
## 🔒 Sicherheit
|
|
|
|
### Ist das System sicher?
|
|
|
|
Ja, mit mehreren Sicherheitsebenen:
|
|
- Unprivileged LXC-Container
|
|
- Docker-Isolation
|
|
- JWT-basierte API-Authentifizierung
|
|
- Credentials nicht im Git
|
|
|
|
### Sollte ich HTTPS verwenden?
|
|
|
|
Ja, für Produktiv-Systeme:
|
|
1. NGINX Reverse Proxy einrichten
|
|
2. Let's Encrypt SSL-Zertifikat
|
|
3. HTTPS-Only-Modus
|
|
|
|
### Wie ändere ich Passwörter?
|
|
|
|
```bash
|
|
# n8n-Passwort
|
|
./update_credentials.sh --ctid <ctid> --n8n-password "NewPass123"
|
|
|
|
# PostgreSQL-Passwort (manuell in .env ändern)
|
|
pct exec <ctid> -- nano /opt/customer-stack/.env
|
|
pct exec <ctid> -- docker compose -f /opt/customer-stack/docker-compose.yml restart
|
|
```
|
|
|
|
## 📚 Weitere Hilfe
|
|
|
|
### Wo finde ich mehr Dokumentation?
|
|
|
|
- [Installation](Installation.md)
|
|
- [Credentials-Management](Credentials-Management.md)
|
|
- [Testing](Testing.md)
|
|
- [Architecture](Architecture.md)
|
|
- [Troubleshooting](Troubleshooting.md)
|
|
|
|
### Wie kann ich zum Projekt beitragen?
|
|
|
|
1. Fork das Repository
|
|
2. Erstellen Sie einen Feature-Branch
|
|
3. Implementieren Sie Ihre Änderungen
|
|
4. Erstellen Sie einen Pull Request
|
|
|
|
### Wo melde ich Bugs?
|
|
|
|
Erstellen Sie ein Issue im Repository mit:
|
|
- Fehlerbeschreibung
|
|
- Reproduktionsschritte
|
|
- Log-Dateien
|
|
- System-Informationen
|
|
|
|
---
|
|
|
|
**Haben Sie weitere Fragen?**
|
|
Erstellen Sie ein Issue oder konsultieren Sie die [Troubleshooting](Troubleshooting.md)-Seite.
|