MediaMetz/customer-installer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

FAQ hinzugefügt

admin
2026-01-25 09:33:44 -08:00
parent 461167916d
commit fc9b82eae7
1 changed files with 515 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
FAQ.md
+515
@@ -0,0 +1,515 @@
# 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.