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

docs: Add comprehensive Wiki documentation

Browse Source 
- Add Wiki home page with navigation
- Add Installation guide with all parameters
- Add Credentials-Management documentation
- Add Testing guide with all test suites
- Add Architecture documentation with diagrams
- Add Troubleshooting guide with solutions
- Add FAQ with common questions

Wiki includes:
- Complete installation instructions
- Credentials management workflows
- Testing procedures (40+ tests)
- System architecture diagrams
- Troubleshooting for common issues
- FAQ covering all aspects
- Cross-referenced documentation
This commit is contained in:
Wolfgang
2026-01-24 22:48:04 +01:00
parent aa00fb9d29
commit 1a91f23044
7 changed files with 2809 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

503
wiki/Architecture.md Normal file
View File

@@ -0,0 +1,503 @@
# Architektur
Diese Seite beschreibt die technische Architektur des Customer Installer Systems.
## 📐 System-Übersicht
```
┌─────────────────────────────────────────────────────────────────┐
│ Proxmox VE Host │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ LXC Container (Debian 12) │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Docker Compose Stack │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌─────────┐ │ │ │
│ │ │ │ PostgreSQL │ │ PostgREST │ │ n8n │ │ │ │
│ │ │ │ + pgvector │◄─┤ (REST API) │◄─┤ Workflow│ │ │ │
│ │ │ │ │ │ │ │ Engine │ │ │ │
│ │ │ └──────────────┘ └──────────────┘ └─────────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ └──────────────────┴──────────────┘ │ │ │
│ │ │ Docker Network │ │ │
│ │ │ (customer-net) │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Systemd Services │ │ │
│ │ │ - docker.service │ │ │
│ │ │ - n8n-workflow-reload.service │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ NGINX Reverse Proxy (OPNsense) │ │
│ │ https://sb-<timestamp>.userman.de → http://<ip>:5678 │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────┐
│ Ollama Server │
│ (External Host) │
│ Port: 11434 │
└──────────────────┘
```
## 🏗️ Komponenten-Architektur
### 1. Proxmox LXC Container
**Technologie:** Linux Container (LXC)
**OS:** Debian 12 (Bookworm)
**Typ:** Unprivileged (Standard) oder Privileged (optional)
**Ressourcen:**
- CPU: Unlimited (konfigurierbar)
- RAM: 4096 MB (Standard)
- Swap: 512 MB
- Disk: 50 GB (Standard)
- Netzwerk: Bridge mit VLAN-Support
**Features:**
- Automatische CTID-Generierung (customer-safe)
- DHCP oder statische IP
- VLAN-Tagging
- APT-Proxy-Support
### 2. Docker Stack
**Technologie:** Docker Compose v2
**Netzwerk:** Bridge Network (customer-net)
**Volumes:** Named Volumes für Persistenz
#### 2.1 PostgreSQL Container
**Image:** `postgres:16-alpine`
**Name:** `customer-postgres`
**Port:** 5432 (intern)
**Features:**
- pgvector Extension (v0.5.1)
- Automatische Datenbank-Initialisierung
- Persistente Daten via Volume
- Health Checks
**Datenbank-Schema:**
```sql
-- documents Tabelle für RAG
CREATE TABLE documents (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
content TEXT NOT NULL,
metadata JSONB,
embedding vector(384), -- nomic-embed-text Dimension
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Index für Vektor-Suche
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);
-- RPC-Funktion für Similarity Search
CREATE FUNCTION match_documents(
query_embedding vector(384),
match_count int DEFAULT 5
) RETURNS TABLE (
id UUID,
content TEXT,
metadata JSONB,
similarity FLOAT
) AS $$
SELECT
id,
content,
metadata,
1 - (embedding <=> query_embedding) AS similarity
FROM documents
ORDER BY embedding <=> query_embedding
LIMIT match_count;
$$ LANGUAGE sql STABLE;
```
#### 2.2 PostgREST Container
**Image:** `postgrest/postgrest:v12.0.2`
**Name:** `customer-postgrest`
**Port:** 3000 (extern + intern)
**Features:**
- Supabase-kompatible REST API
- JWT-basierte Authentikation
- Automatische OpenAPI-Dokumentation
- RPC-Funktionen-Support
**Endpoints:**
- `GET /documents` - Dokumente abrufen
- `POST /documents` - Dokument erstellen
- `POST /rpc/match_documents` - Vektor-Suche
**Authentication:**
- `anon` Role: Lesezugriff
- `service_role`: Voller Zugriff
#### 2.3 n8n Container
**Image:** `n8nio/n8n:latest`
**Name:** `n8n`
**Port:** 5678 (extern + intern)
**Features:**
- PostgreSQL als Backend
- Workflow-Automation
- Webhook-Support
- Credentials-Management
- Execution-History
**Workflows:**
- RAG KI-Bot (Chat-Interface)
- Document Upload (Form)
- Vector Embedding (Ollama)
- Similarity Search (PostgreSQL)
**Environment:**
```bash
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=customer
DB_POSTGRESDB_USER=customer
DB_POSTGRESDB_PASSWORD=<generated>
N8N_ENCRYPTION_KEY=<generated>
WEBHOOK_URL=https://sb-<timestamp>.userman.de
N8N_DIAGNOSTICS_ENABLED=false
N8N_PERSONALIZATION_ENABLED=false
```
### 3. Systemd Services
#### 3.1 docker.service
Standard Docker Service für Container-Management.
#### 3.2 n8n-workflow-reload.service
**Typ:** oneshot
**Trigger:** Container-Start
**Funktion:** Automatisches Workflow-Reload
```ini
[Unit]
Description=Reload n8n workflow on container start
After=docker.service
Requires=docker.service
[Service]
Type=oneshot
ExecStart=/opt/customer-stack/reload-workflow.sh
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
```
### 4. Netzwerk-Architektur
#### 4.1 Docker Network
**Name:** `customer-stack_customer-net`
**Typ:** Bridge
**Subnet:** Automatisch (Docker)
**DNS-Resolution:**
- `postgres` → PostgreSQL Container
- `postgrest` → PostgREST Container
- `n8n` → n8n Container
#### 4.2 LXC Network
**Interface:** eth0
**Bridge:** vmbr0 (Standard)
**VLAN:** 90 (Standard)
**IP:** DHCP oder statisch
#### 4.3 External Access
**NGINX Reverse Proxy:**
```
https://sb-<timestamp>.userman.de
↓
http://<container-ip>:5678
```
**Direct Access:**
- n8n: `http://<ip>:5678`
- PostgREST: `http://<ip>:3000`
### 5. Storage-Architektur
#### 5.1 Container Storage
**Location:** `/var/lib/lxc/<ctid>/rootfs`
**Type:** ZFS (Standard) oder Directory
**Size:** 50 GB (Standard)
#### 5.2 Docker Volumes
```
/opt/customer-stack/volumes/
├── postgres-data/ # PostgreSQL Daten
├── n8n-data/ # n8n Workflows & Credentials
└── postgrest-data/ # PostgREST Cache (optional)
```
**Permissions:**
- postgres-data: 999:999 (postgres user)
- n8n-data: 1000:1000 (node user)
#### 5.3 Configuration Files
```
/opt/customer-stack/
├── docker-compose.yml # Stack-Definition
├── .env # Environment-Variablen
├── workflow-template.json # n8n Workflow-Template
├── reload-workflow.sh # Reload-Script
└── volumes/ # Persistente Daten
```
## 🔄 Datenfluss
### RAG Chat-Flow
```
1. User → Chat-Webhook
POST https://sb-<timestamp>.userman.de/webhook/rag-chat-webhook/chat
Body: {"query": "Was ist...?"}
2. n8n → Ollama (Embedding)
POST http://ollama:11434/api/embeddings
Body: {"model": "nomic-embed-text", "prompt": "Was ist...?"}
3. n8n → PostgreSQL (Vector Search)
POST http://postgrest:3000/rpc/match_documents
Body: {"query_embedding": [...], "match_count": 5}
4. PostgreSQL → n8n (Relevant Documents)
Response: [{"content": "...", "similarity": 0.85}, ...]
5. n8n → Ollama (Chat Completion)
POST http://ollama:11434/api/generate
Body: {"model": "ministral-3:3b", "prompt": "Context: ... Question: ..."}
6. n8n → User (Response)
Response: {"answer": "...", "sources": [...]}
```
### Document Upload-Flow
```
1. User → Upload-Form
POST https://sb-<timestamp>.userman.de/form/rag-upload-form
Body: FormData with file
2. n8n → Text Extraction
Extract text from PDF/DOCX/TXT
3. n8n → Text Chunking
Split text into chunks (max 1000 chars)
4. n8n → Ollama (Embeddings)
For each chunk:
POST http://ollama:11434/api/embeddings
Body: {"model": "nomic-embed-text", "prompt": "<chunk>"}
5. n8n → PostgreSQL (Store)
For each chunk:
POST http://postgrest:3000/documents
Body: {"content": "<chunk>", "embedding": [...], "metadata": {...}}
6. n8n → User (Confirmation)
Response: {"status": "success", "chunks": 42}
```
## 🔐 Security-Architektur
### 1. Container-Isolation
- **Unprivileged LXC:** Prozesse laufen als unprivilegierte User
- **AppArmor:** Kernel-Level Security
- **Seccomp:** Syscall-Filtering
### 2. Network-Isolation
- **Docker Network:** Isoliertes Bridge-Network
- **Firewall:** Nur notwendige Ports exponiert
- **VLAN:** Netzwerk-Segmentierung
### 3. Authentication
- **JWT-Tokens:** Für PostgREST API
- **n8n Credentials:** Verschlüsselt mit N8N_ENCRYPTION_KEY
- **PostgreSQL:** Passwort-basiert, nur intern erreichbar
### 4. Data Protection
- **Encryption at Rest:** Optional via ZFS
- **Encryption in Transit:** HTTPS via NGINX
- **Credentials:** Gespeichert in .gitignore-geschütztem Verzeichnis
## 📊 Performance-Architektur
### 1. Database Optimization
- **pgvector Index:** IVFFlat für schnelle Vektor-Suche
- **Connection Pooling:** Via PostgREST
- **Query Optimization:** Prepared Statements
### 2. Caching
- **PostgREST:** Schema-Cache
- **n8n:** Workflow-Cache
- **Docker:** Layer-Cache
### 3. Resource Management
- **CPU:** Unlimited (kann limitiert werden)
- **Memory:** 4 GB (kann angepasst werden)
- **Disk I/O:** ZFS mit Compression
## 🔧 Deployment-Architektur
### 1. Installation-Flow
```
1. install.sh
↓
2. Parameter-Validierung
↓
3. CTID-Generierung
↓
4. Template-Download (Debian 12)
↓
5. LXC-Container-Erstellung
↓
6. Container-Start
↓
7. System-Update (APT)
↓
8. Docker-Installation
↓
9. Stack-Deployment (docker-compose.yml)
↓
10. Database-Initialization (pgvector, schema)
↓
11. n8n-Setup (owner, credentials, workflow)
↓
12. Workflow-Reload-Service
↓
13. NGINX-Proxy-Setup (optional)
↓
14. Credentials-Save
↓
15. JSON-Output
```
### 2. Update-Flow
```
1. update_credentials.sh
↓
2. Load Credentials
↓
3. n8n API Login
↓
4. Update Credentials (Ollama, etc.)
↓
5. Reload Workflow (optional)
↓
6. Verify Changes
```
### 3. Backup-Flow
```
1. Stop Container
↓
2. Backup Volumes
- /opt/customer-stack/volumes/postgres-data
- /opt/customer-stack/volumes/n8n-data
↓
3. Backup Configuration
- /opt/customer-stack/.env
- /opt/customer-stack/docker-compose.yml
↓
4. Start Container
```
## 📚 Technologie-Stack
### Core Technologies
- **Proxmox VE:** Virtualisierung
- **LXC:** Container-Technologie
- **Docker:** Container-Runtime
- **Docker Compose:** Orchestrierung
### Database Stack
- **PostgreSQL 16:** Relationale Datenbank
- **pgvector:** Vektor-Extension
- **PostgREST:** REST API
### Application Stack
- **n8n:** Workflow-Automation
- **Node.js:** Runtime für n8n
- **Ollama:** LLM-Integration
### Infrastructure
- **Debian 12:** Base OS
- **Systemd:** Service-Management
- **NGINX:** Reverse Proxy
## 🔗 Integration-Points
### 1. Ollama Integration
**Connection:** HTTP REST API
**Endpoint:** `http://192.168.45.3:11434`
**Models:**
- Chat: `ministral-3:3b`
- Embeddings: `nomic-embed-text:latest`
### 2. NGINX Integration
**Connection:** HTTP Reverse Proxy
**Configuration:** OPNsense NGINX Plugin
**SSL:** Let's Encrypt (optional)
### 3. Monitoring Integration
**Potential Integrations:**
- Prometheus (Metrics)
- Grafana (Visualization)
- Loki (Logs)
- Alertmanager (Alerts)
## 📚 Weiterführende Dokumentation
- [Installation](Installation.md) - Installations-Anleitung
- [Configuration](Configuration.md) - Konfiguration
- [Deployment](Deployment.md) - Deployment-Strategien
- [API-Referenz](API-Reference.md) - API-Dokumentation
---
**Design-Prinzipien:**
1. **Modularität:** Komponenten sind austauschbar
2. **Skalierbarkeit:** Horizontal und vertikal skalierbar
3. **Wartbarkeit:** Klare Struktur und Dokumentation
4. **Sicherheit:** Defense in Depth
5. **Performance:** Optimiert für RAG-Workloads

387
wiki/Credentials-Management.md Normal file
View File

@@ -0,0 +1,387 @@
# Credentials-Management
Das Customer Installer System bietet ein umfassendes Credentials-Management-System für die sichere Verwaltung von Zugangsdaten.
## 📋 Übersicht
Das Credentials-Management-System ermöglicht:
- ✅ **Automatisches Speichern** von Credentials bei Installation
- ✅ **JSON-basierte Speicherung** für einfache Verarbeitung
- ✅ **Update ohne Container-Neustart** (z.B. Ollama-URL)
- ✅ **Sichere Speicherung** mit .gitignore-Schutz
- ✅ **Einfache Wiederverwendung** für Automatisierung
## 📁 Credential-Dateien
### Speicherort
```bash
credentials/
├── .gitignore # Schützt Credentials vor Git
├── example-credentials.json # Beispiel-Datei
└── sb-<timestamp>.json # Tatsächliche Credentials
```
### Dateiformat
```json
{
"ctid": 769276659,
"hostname": "sb-1769276659",
"fqdn": "sb-1769276659.userman.de",
"ip": "192.168.45.45",
"vlan": 90,
"urls": {
"n8n_internal": "http://192.168.45.45:5678/",
"n8n_external": "https://sb-1769276659.userman.de",
"postgrest": "http://192.168.45.45:3000",
"chat_webhook": "https://sb-1769276659.userman.de/webhook/rag-chat-webhook/chat",
"chat_internal": "http://192.168.45.45:5678/webhook/rag-chat-webhook/chat",
"upload_form": "https://sb-1769276659.userman.de/form/rag-upload-form",
"upload_form_internal": "http://192.168.45.45:5678/form/rag-upload-form"
},
"postgres": {
"host": "postgres",
"port": 5432,
"db": "customer",
"user": "customer",
"password": "HUmMLP8NbW2onmf2A1"
},
"supabase": {
"url": "http://postgrest:3000",
"url_external": "http://192.168.45.45:3000",
"anon_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"service_role_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"jwt_secret": "IM9/HRQR9mw63lU/1G7vXPMe7q0n3oLcr35dryv0ToU="
},
"ollama": {
"url": "http://192.168.45.3:11434",
"model": "ministral-3:3b",
"embedding_model": "nomic-embed-text:latest"
},
"n8n": {
"encryption_key": "d0c9c0ba0551d25e4ee95b6a4b6bc8d5b64e5e14f7f0972fe50332ca051edab5",
"owner_email": "admin@userman.de",
"owner_password": "FAmeVE7t9d1iMIXWA1",
"secure_cookie": false
},
"log_file": "/root/customer-installer/logs/sb-1769276659.log"
}
```
## 🔧 Verwendung
### 1. Automatisches Speichern bei Installation
Credentials werden automatisch gespeichert:
```bash
# Installation durchführen
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
# Credentials werden automatisch gespeichert
# credentials/sb-<timestamp>.json
```
### 2. Manuelles Speichern
Falls Sie Credentials manuell speichern möchten:
```bash
# JSON-Output in Datei speichern
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90 > output.json
# Mit save_credentials.sh speichern
./save_credentials.sh output.json
```
### 3. Credentials laden
```bash
# Credentials laden
CREDS=$(cat credentials/sb-1769276659.json)
# Einzelne Werte extrahieren
CTID=$(echo "$CREDS" | jq -r '.ctid')
IP=$(echo "$CREDS" | jq -r '.ip')
N8N_PASSWORD=$(echo "$CREDS" | jq -r '.n8n.owner_password')
```
## 🔄 Credentials aktualisieren
### Ollama-URL aktualisieren
Häufiger Use-Case: Ollama-URL von IP zu Hostname ändern
```bash
# Von IP zu Hostname
./update_credentials.sh \
--ctid 769276659 \
--ollama-url http://ollama.local:11434
# Mit Credentials-Datei
./update_credentials.sh \
--credentials credentials/sb-1769276659.json \
--ollama-url http://ollama.local:11434
```
### Ollama-Modell ändern
```bash
# Chat-Modell ändern
./update_credentials.sh \
--ctid 769276659 \
--ollama-model llama2:latest
# Embedding-Modell ändern
./update_credentials.sh \
--ctid 769276659 \
--embedding-model all-minilm:latest
# Beide gleichzeitig
./update_credentials.sh \
--ctid 769276659 \
--ollama-model llama2:latest \
--embedding-model all-minilm:latest
```
### Alle Optionen
```bash
./update_credentials.sh \
--ctid 769276659 \
--ollama-url http://ollama.local:11434 \
--ollama-model llama2:latest \
--embedding-model all-minilm:latest \
--n8n-email admin@userman.de \
--n8n-password "NewPassword123"
```
## 📝 update_credentials.sh Optionen
| Parameter | Beschreibung | Beispiel |
|-----------|--------------|----------|
| `--ctid <id>` | Container-ID | `--ctid 769276659` |
| `--credentials <file>` | Credentials-Datei | `--credentials credentials/sb-*.json` |
| `--ollama-url <url>` | Ollama Server URL | `--ollama-url http://ollama.local:11434` |
| `--ollama-model <model>` | Chat-Modell | `--ollama-model llama2:latest` |
| `--embedding-model <model>` | Embedding-Modell | `--embedding-model all-minilm:latest` |
| `--n8n-email <email>` | n8n Admin-Email | `--n8n-email admin@example.com` |
| `--n8n-password <pass>` | n8n Admin-Passwort | `--n8n-password "NewPass123"` |
## 🔐 Sicherheit
### Git-Schutz
Credentials werden automatisch von Git ausgeschlossen:
```bash
# credentials/.gitignore
*.json
!example-credentials.json
```
### Berechtigungen
```bash
# Credentials-Verzeichnis schützen
chmod 700 credentials/
chmod 600 credentials/*.json
```
### Passwort-Richtlinien
Automatisch generierte Passwörter erfüllen:
- Mindestens 14 Zeichen
- Groß- und Kleinbuchstaben
- Zahlen
- Keine Sonderzeichen (für bessere Kompatibilität)
## 🔄 Workflow
### Typischer Workflow
```bash
# 1. Installation
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
# 2. Credentials werden automatisch gespeichert
# credentials/sb-<timestamp>.json
# 3. Später: Ollama-URL aktualisieren
./update_credentials.sh \
--credentials credentials/sb-*.json \
--ollama-url http://ollama.local:11434
# 4. Credentials für Automatisierung verwenden
CTID=$(jq -r '.ctid' credentials/sb-*.json)
IP=$(jq -r '.ip' credentials/sb-*.json)
```
### Automatisierung
```bash
#!/bin/bash
# Beispiel: Automatische Deployment-Pipeline
# Installation
OUTPUT=$(./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90)
# Credentials extrahieren
CTID=$(echo "$OUTPUT" | jq -r '.ctid')
IP=$(echo "$OUTPUT" | jq -r '.ip')
N8N_URL=$(echo "$OUTPUT" | jq -r '.urls.n8n_external')
# Credentials-Datei finden
CREDS_FILE=$(ls -t credentials/sb-*.json | head -1)
# Ollama-URL aktualisieren
./update_credentials.sh \
--credentials "$CREDS_FILE" \
--ollama-url http://ollama.local:11434
# Tests durchführen
./test_complete_system.sh "$CTID" "$IP" "$(basename "$CREDS_FILE" .json)"
# Monitoring einrichten
# ...
```
## 📊 Credential-Typen
### PostgreSQL Credentials
```json
"postgres": {
"host": "postgres",
"port": 5432,
"db": "customer",
"user": "customer",
"password": "HUmMLP8NbW2onmf2A1"
}
```
**Verwendung:**
```bash
# Verbindung zur Datenbank
pct exec <ctid> -- docker exec customer-postgres \
psql -U customer -d customer
```
### Supabase/PostgREST Credentials
```json
"supabase": {
"url": "http://postgrest:3000",
"url_external": "http://192.168.45.45:3000",
"anon_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"service_role_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"jwt_secret": "IM9/HRQR9mw63lU/1G7vXPMe7q0n3oLcr35dryv0ToU="
}
```
**Verwendung:**
```bash
# API-Zugriff mit anon_key
curl http://192.168.45.45:3000/documents \
-H "apikey: ${ANON_KEY}" \
-H "Authorization: Bearer ${ANON_KEY}"
# API-Zugriff mit service_role_key (volle Rechte)
curl http://192.168.45.45:3000/documents \
-H "apikey: ${SERVICE_KEY}" \
-H "Authorization: Bearer ${SERVICE_KEY}"
```
### n8n Credentials
```json
"n8n": {
"encryption_key": "d0c9c0ba0551d25e4ee95b6a4b6bc8d5b64e5e14f7f0972fe50332ca051edab5",
"owner_email": "admin@userman.de",
"owner_password": "FAmeVE7t9d1iMIXWA1",
"secure_cookie": false
}
```
**Verwendung:**
```bash
# n8n API Login
curl -X POST http://192.168.45.45:5678/rest/login \
-H "Content-Type: application/json" \
-d "{\"emailOrLdapLoginId\":\"${N8N_EMAIL}\",\"password\":\"${N8N_PASSWORD}\"}"
```
### Ollama Credentials
```json
"ollama": {
"url": "http://192.168.45.3:11434",
"model": "ministral-3:3b",
"embedding_model": "nomic-embed-text:latest"
}
```
**Verwendung:**
```bash
# Ollama-Modelle auflisten
curl http://192.168.45.3:11434/api/tags
# Chat-Completion
curl -X POST http://192.168.45.3:11434/api/generate \
-H "Content-Type: application/json" \
-d "{\"model\":\"ministral-3:3b\",\"prompt\":\"Hello\"}"
```
## 🔍 Troubleshooting
### Credentials-Datei nicht gefunden
```bash
# Alle Credentials-Dateien auflisten
ls -la credentials/
# Nach Hostname suchen
ls credentials/sb-*.json
```
### Update schlägt fehl
```bash
# n8n-Container prüfen
pct exec <ctid> -- docker ps | grep n8n
# n8n-Logs prüfen
pct exec <ctid> -- docker logs n8n
# Manuell in n8n einloggen und prüfen
curl -X POST http://<ip>:5678/rest/login \
-H "Content-Type: application/json" \
-d '{"emailOrLdapLoginId":"admin@userman.de","password":"..."}'
```
### Credentials wiederherstellen
```bash
# Aus Log-Datei extrahieren
grep "JSON_OUTPUT" logs/sb-*.log
# Oder aus Container extrahieren
pct exec <ctid> -- cat /opt/customer-stack/.env
```
## 📚 Weiterführende Dokumentation
- [Installation](Installation.md) - Installations-Anleitung
- [API-Referenz](API-Reference.md) - API-Dokumentation
- [Troubleshooting](Troubleshooting.md) - Problemlösung
- [n8n](n8n.md) - n8n-Konfiguration
---
**Best Practices:**
1. Credentials-Dateien regelmäßig sichern
2. Passwörter nicht in Scripts hardcoden
3. Service-Role-Key nur für administrative Aufgaben verwenden
4. Credentials-Verzeichnis mit restriktiven Berechtigungen schützen

515
wiki/FAQ.md Normal file
View File

@@ -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.

111
wiki/Home.md Normal file
View File

@@ -0,0 +1,111 @@
# Customer Installer - Wiki
Willkommen zum Customer Installer Wiki! Dieses System automatisiert die Bereitstellung von LXC-Containern mit einem vollständigen RAG (Retrieval-Augmented Generation) Stack.
## 📚 Inhaltsverzeichnis
### Erste Schritte
- [Installation](Installation.md) - Schnellstart und erste Installation
- [Systemanforderungen](System-Requirements.md) - Voraussetzungen und Abhängigkeiten
- [Konfiguration](Configuration.md) - Konfigurationsoptionen
### Hauptfunktionen
- [Credentials-Management](Credentials-Management.md) - Verwaltung von Zugangsdaten
- [Workflow-Auto-Reload](Workflow-Auto-Reload.md) - Automatisches Workflow-Reload
- [Testing](Testing.md) - Test-Suites und Qualitätssicherung
### Komponenten
- [PostgreSQL & pgvector](PostgreSQL-pgvector.md) - Datenbank mit Vektor-Unterstützung
- [PostgREST](PostgREST.md) - REST API für PostgreSQL
- [n8n](n8n.md) - Workflow-Automation
- [Ollama Integration](Ollama-Integration.md) - KI-Modell-Integration
### Betrieb
- [Deployment](Deployment.md) - Produktiv-Deployment
- [Monitoring](Monitoring.md) - Überwachung und Logs
- [Backup & Recovery](Backup-Recovery.md) - Datensicherung
- [Troubleshooting](Troubleshooting.md) - Problemlösung
### Entwicklung
- [Architektur](Architecture.md) - System-Architektur
- [API-Referenz](API-Reference.md) - API-Dokumentation
- [Contributing](Contributing.md) - Beiträge zum Projekt
## 🚀 Schnellstart
```bash
# Installation durchführen
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
# Credentials werden automatisch gespeichert
cat credentials/sb-<timestamp>.json
# Tests ausführen
./test_complete_system.sh <ctid> <ip> <hostname>
```
## 🎯 Hauptmerkmale
- ✅ **Automatische LXC-Container-Erstellung** mit Debian 12
- ✅ **Docker-basierter Stack** (PostgreSQL, PostgREST, n8n)
- ✅ **pgvector-Integration** für Vektor-Embeddings
- ✅ **Supabase-kompatible REST API** via PostgREST
- ✅ **n8n Workflow-Automation** mit RAG-Workflow
- ✅ **Ollama-Integration** für KI-Modelle
- ✅ **Credentials-Management** mit automatischem Speichern
- ✅ **Workflow Auto-Reload** bei Container-Neustart
- ✅ **Umfassende Test-Suites** (40+ Tests)
- ✅ **NGINX Reverse Proxy** Integration
## 📊 System-Übersicht
```
┌─────────────────────────────────────────────────────────┐
│ Proxmox Host │
│ ┌───────────────────────────────────────────────────┐ │
│ │ LXC Container (Debian 12) │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Docker Compose Stack │ │ │
│ │ │ │ │ │
│ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │
│ │ │ │ PostgreSQL │ │ PostgREST │ │ │ │
│ │ │ │ + pgvector │◄─┤ (REST API) │ │ │ │
│ │ │ └──────────────┘ └──────────────┘ │ │ │
│ │ │ ▲ ▲ │ │ │
│ │ │ │ │ │ │ │
│ │ │ ┌──────┴──────────────────┘ │ │ │
│ │ │ │ n8n │ │ │
│ │ │ │ (Workflow Automation) │ │ │
│ │ │ └─────────────────────────────────────────┘ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌──────────────────┐
│ Ollama Server │
│ (External) │
└──────────────────┘
```
## 🔗 Wichtige Links
- [GitHub Repository](https://backoffice.userman.de/MediaMetz/customer-installer)
- [Issue Tracker](https://backoffice.userman.de/MediaMetz/customer-installer/issues)
- [Changelog](../CHANGELOG_WORKFLOW_RELOAD.md)
## 📝 Lizenz
Dieses Projekt ist proprietär und für den internen Gebrauch bestimmt.
## 👥 Support
Bei Fragen oder Problemen:
1. Konsultieren Sie das [Troubleshooting](Troubleshooting.md)
2. Prüfen Sie die [FAQ](FAQ.md)
3. Erstellen Sie ein Issue im Repository
---
**Letzte Aktualisierung:** 2026-01-24
**Version:** 1.0.0

298
wiki/Installation.md Normal file
View File

@@ -0,0 +1,298 @@
# Installation
Diese Seite beschreibt die Installation und Einrichtung des Customer Installer Systems.
## 📋 Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:
- **Proxmox VE** Server (getestet mit Version 7.x und 8.x)
- **Root-Zugriff** auf den Proxmox Host
- **Debian 12 Template** (wird automatisch heruntergeladen)
- **Netzwerk-Konfiguration** (Bridge, VLAN)
- **Ollama Server** (extern, optional)
Siehe auch: [Systemanforderungen](System-Requirements.md)
## 🚀 Schnellstart
### 1. Repository klonen
```bash
cd /root
git clone ssh://backoffice.userman.de:2223/MediaMetz/customer-installer.git
cd customer-installer
```
### 2. Basis-Installation
```bash
./install.sh \
--storage local-zfs \
--bridge vmbr0 \
--ip dhcp \
--vlan 90
```
### 3. Installation mit allen Optionen
```bash
./install.sh \
--storage local-zfs \
--bridge vmbr0 \
--ip dhcp \
--vlan 90 \
--cores 4 \
--memory 8192 \
--disk 100 \
--apt-proxy http://192.168.45.2:3142 \
--base-domain userman.de \
--n8n-owner-email admin@userman.de \
--ollama-model ministral-3:3b \
--embedding-model nomic-embed-text:latest
```
## 📝 Installations-Parameter
### Pflicht-Parameter
Keine - alle Parameter haben sinnvolle Standardwerte.
### Core-Optionen
| Parameter | Beschreibung | Standard |
|-----------|--------------|----------|
| `--ctid <id>` | Container-ID (optional, wird automatisch generiert) | auto |
| `--cores <n>` | CPU-Kerne | unlimited |
| `--memory <mb>` | RAM in MB | 4096 |
| `--swap <mb>` | Swap in MB | 512 |
| `--disk <gb>` | Festplatte in GB | 50 |
| `--bridge <vmbrX>` | Netzwerk-Bridge | vmbr0 |
| `--storage <storage>` | Proxmox Storage | local-zfs |
| `--ip <dhcp\|CIDR>` | IP-Konfiguration | dhcp |
| `--vlan <id>` | VLAN-Tag (0 = deaktiviert) | 90 |
| `--privileged` | Privilegierter Container | unprivileged |
| `--apt-proxy <url>` | APT-Proxy URL | - |
### Domain & n8n Optionen
| Parameter | Beschreibung | Standard |
|-----------|--------------|----------|
| `--base-domain <domain>` | Basis-Domain | userman.de |
| `--n8n-owner-email <email>` | n8n Admin-Email | admin@<base-domain> |
| `--n8n-owner-pass <pass>` | n8n Admin-Passwort | auto-generiert |
| `--workflow-file <path>` | Workflow JSON-Datei | RAGKI-BotPGVector.json |
| `--ollama-model <model>` | Ollama Chat-Modell | ministral-3:3b |
| `--embedding-model <model>` | Embedding-Modell | nomic-embed-text:latest |
### PostgREST Optionen
| Parameter | Beschreibung | Standard |
|-----------|--------------|----------|
| `--postgrest-port <port>` | PostgREST Port | 3000 |
### Debug-Optionen
| Parameter | Beschreibung |
|-----------|--------------|
| `--debug` | Debug-Modus aktivieren |
| `--help` | Hilfe anzeigen |
## 📤 JSON-Output
Nach erfolgreicher Installation gibt das Script ein JSON-Objekt aus:
```json
{
"ctid": 769276659,
"hostname": "sb-1769276659",
"fqdn": "sb-1769276659.userman.de",
"ip": "192.168.45.45",
"vlan": 90,
"urls": {
"n8n_internal": "http://192.168.45.45:5678/",
"n8n_external": "https://sb-1769276659.userman.de",
"postgrest": "http://192.168.45.45:3000",
"chat_webhook": "https://sb-1769276659.userman.de/webhook/rag-chat-webhook/chat",
"chat_internal": "http://192.168.45.45:5678/webhook/rag-chat-webhook/chat",
"upload_form": "https://sb-1769276659.userman.de/form/rag-upload-form",
"upload_form_internal": "http://192.168.45.45:5678/form/rag-upload-form"
},
"postgres": {
"host": "postgres",
"port": 5432,
"db": "customer",
"user": "customer",
"password": "HUmMLP8NbW2onmf2A1"
},
"supabase": {
"url": "http://postgrest:3000",
"url_external": "http://192.168.45.45:3000",
"anon_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"service_role_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"jwt_secret": "IM9/HRQR9mw63lU/1G7vXPMe7q0n3oLcr35dryv0ToU="
},
"ollama": {
"url": "http://192.168.45.3:11434",
"model": "ministral-3:3b",
"embedding_model": "nomic-embed-text:latest"
},
"n8n": {
"encryption_key": "d0c9c0ba0551d25e4ee95b6a4b6bc8d5b64e5e14f7f0972fe50332ca051edab5",
"owner_email": "admin@userman.de",
"owner_password": "FAmeVE7t9d1iMIXWA1",
"secure_cookie": false
},
"log_file": "/root/customer-installer/logs/sb-1769276659.log"
}
```
### Credentials automatisch speichern
Die Credentials werden automatisch gespeichert:
```bash
# Automatisch erstellt
credentials/sb-1769276659.json
```
Siehe auch: [Credentials-Management](Credentials-Management.md)
## 🔍 Installations-Schritte
Das Script führt folgende Schritte aus:
1. **Parameter-Validierung** - Prüfung aller Eingaben
2. **CTID-Generierung** - Eindeutige Container-ID
3. **Template-Download** - Debian 12 Template
4. **Container-Erstellung** - LXC-Container mit Konfiguration
5. **Container-Start** - Initialer Boot
6. **System-Update** - APT-Update und Upgrade
7. **Docker-Installation** - Docker Engine und Compose
8. **Stack-Deployment** - Docker Compose Stack
9. **Datenbank-Initialisierung** - PostgreSQL + pgvector
10. **n8n-Setup** - Workflow-Import und Konfiguration
11. **Workflow-Reload-Service** - Systemd Service
12. **NGINX-Proxy-Setup** - Reverse Proxy (optional)
13. **Credentials-Speicherung** - JSON-Datei
## 📊 Installations-Logs
Logs werden automatisch gespeichert:
```bash
# Log-Datei
logs/sb-<timestamp>.log
# Log-Datei anzeigen
tail -f logs/sb-1769276659.log
```
## ✅ Installations-Verifikation
Nach der Installation sollten Sie die Verifikation durchführen:
```bash
# Vollständige System-Tests
./test_complete_system.sh <ctid> <ip> <hostname>
# Beispiel
./test_complete_system.sh 769276659 192.168.45.45 sb-1769276659
```
Siehe auch: [Testing](Testing.md)
## 🔧 Post-Installation
### 1. Credentials prüfen
```bash
cat credentials/sb-<timestamp>.json
```
### 2. Services prüfen
```bash
# Container-Status
pct status <ctid>
# Docker-Container
pct exec <ctid> -- docker ps
# n8n-Logs
pct exec <ctid> -- docker logs n8n
```
### 3. Zugriff testen
```bash
# n8n Web-Interface
curl http://<ip>:5678/
# PostgREST API
curl http://<ip>:3000/
# Chat-Webhook
curl -X POST http://<ip>:5678/webhook/rag-chat-webhook/chat \
-H "Content-Type: application/json" \
-d '{"query":"Hallo"}'
```
## 🚨 Troubleshooting
### Container startet nicht
```bash
# Container-Logs prüfen
pct status <ctid>
journalctl -u pve-container@<ctid>
```
### Docker-Container starten nicht
```bash
# In Container einloggen
pct enter <ctid>
# Docker-Logs prüfen
docker compose -f /opt/customer-stack/docker-compose.yml logs
```
### n8n nicht erreichbar
```bash
# n8n-Container prüfen
pct exec <ctid> -- docker logs n8n
# Port-Binding prüfen
pct exec <ctid> -- netstat -tlnp | grep 5678
```
Siehe auch: [Troubleshooting](Troubleshooting.md)
## 🔄 Neuinstallation
Um einen Container neu zu installieren:
```bash
# Container stoppen und löschen
pct stop <ctid>
pct destroy <ctid>
# Neuinstallation
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90
```
## 📚 Weiterführende Dokumentation
- [Konfiguration](Configuration.md) - Detaillierte Konfigurationsoptionen
- [Deployment](Deployment.md) - Produktiv-Deployment
- [Monitoring](Monitoring.md) - Überwachung und Logs
- [Backup & Recovery](Backup-Recovery.md) - Datensicherung
---
**Nächste Schritte:**
- [Credentials-Management](Credentials-Management.md) - Zugangsdaten verwalten
- [Testing](Testing.md) - System testen
- [n8n](n8n.md) - n8n konfigurieren

415
wiki/Testing.md Normal file
View File

@@ -0,0 +1,415 @@
# Testing
Das Customer Installer System verfügt über umfassende Test-Suites zur Qualitätssicherung.
## 📋 Übersicht
Das Testing-System umfasst:
- ✅ **4 Test-Suites** mit über 40 Test-Cases
- ✅ **Automatisierte Tests** für alle Komponenten
- ✅ **Infrastruktur-Tests** (Container, Docker, Netzwerk)
- ✅ **API-Tests** (n8n, PostgREST)
- ✅ **Integration-Tests** (End-to-End)
- ✅ **Farbcodierte Ausgabe** für bessere Lesbarkeit
## 🧪 Test-Suites
### 1. test_installation.sh - Infrastruktur-Tests
Testet die grundlegende Infrastruktur und Container-Konfiguration.
```bash
./test_installation.sh <ctid> <ip> <hostname>
# Beispiel
./test_installation.sh 769276659 192.168.45.45 sb-1769276659
```
**Test-Bereiche (25 Tests):**
- Container-Status und Konfiguration
- Docker-Installation und -Status
- Docker-Container (PostgreSQL, PostgREST, n8n)
- Datenbank-Konnektivität
- pgvector-Extension
- Netzwerk-Konfiguration
- Volume-Berechtigungen
- Systemd-Services
- Log-Dateien
### 2. test_n8n_workflow.sh - n8n API-Tests
Testet n8n API, Workflows und Credentials.
```bash
./test_n8n_workflow.sh <ctid> <ip> <email> <password>
# Beispiel
./test_n8n_workflow.sh 769276659 192.168.45.45 admin@userman.de "FAmeVE7t9d1iMIXWA1"
```
**Test-Bereiche (13 Tests):**
- n8n API-Login
- Credentials (PostgreSQL, Ollama)
- Workflows (Liste, Status, Aktivierung)
- Webhook-Endpoints
- n8n-Settings
- Execution-History
- Container-Konnektivität
- Environment-Variablen
- Log-Analyse
### 3. test_postgrest_api.sh - PostgREST API-Tests
Testet die Supabase-kompatible REST API.
```bash
./test_postgrest_api.sh <ctid> <ip> <jwt_secret> <anon_key> <service_key>
# Beispiel
./test_postgrest_api.sh 769276659 192.168.45.45 \
"IM9/HRQR9mw63lU/1G7vXPMe7q0n3oLcr35dryv0ToU=" \
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
**Test-Bereiche (13 Tests):**
- PostgREST Root-Endpoint
- Tabellen-Listing
- Documents-Tabelle
- Authentication (anon_key, service_role_key)
- CORS-Headers
- RPC-Funktionen (match_documents)
- OpenAPI-Schema
- Content-Negotiation
- Container-Health
- Interne Netzwerk-Konnektivität
### 4. test_complete_system.sh - Vollständige Integration
Führt alle Tests in der richtigen Reihenfolge aus.
```bash
./test_complete_system.sh <ctid> <ip> <hostname>
# Beispiel
./test_complete_system.sh 769276659 192.168.45.45 sb-1769276659
```
**Test-Bereiche (40+ Tests):**
- Alle Infrastruktur-Tests
- Alle n8n-Tests
- Alle PostgREST-Tests
- Zusätzliche Integration-Tests
## 🚀 Schnellstart
### Nach Installation testen
```bash
# 1. Installation durchführen
OUTPUT=$(./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90)
# 2. Werte extrahieren
CTID=$(echo "$OUTPUT" | jq -r '.ctid')
IP=$(echo "$OUTPUT" | jq -r '.ip')
HOSTNAME=$(echo "$OUTPUT" | jq -r '.hostname')
# 3. Vollständige Tests ausführen
./test_complete_system.sh "$CTID" "$IP" "$HOSTNAME"
```
### Mit Credentials-Datei
```bash
# Credentials laden
CREDS=$(cat credentials/sb-*.json)
# Werte extrahieren
CTID=$(echo "$CREDS" | jq -r '.ctid')
IP=$(echo "$CREDS" | jq -r '.ip')
HOSTNAME=$(echo "$CREDS" | jq -r '.hostname')
# Tests ausführen
./test_complete_system.sh "$CTID" "$IP" "$HOSTNAME"
```
## 📊 Test-Ausgabe
### Erfolgreiche Tests
```
========================================
Customer Installer - Test Suite
========================================
Testing Container: 769276659
IP Address: 192.168.45.45
Hostname: sb-1769276659
[TEST] Checking if container 769276659 exists and is running...
[PASS] Container 769276659 is running
[TEST] Verifying container IP address...
[PASS] Container has correct IP: 192.168.45.45
...
========================================
Test Summary
========================================
Total Tests: 25
Passed: 25
Failed: 0
✓ All tests passed!
```
### Fehlgeschlagene Tests
```
[TEST] Testing n8n API login...
[FAIL] n8n API login failed: Connection refused
========================================
Test Summary
========================================
Total Tests: 13
Passed: 10
Failed: 3
✗ Some tests failed. Please review the output above.
```
## 🔍 Einzelne Test-Kategorien
### Container-Tests
```bash
# Container-Status
pct status <ctid>
# Container-Konfiguration
pct config <ctid>
# Container-Ressourcen
pct exec <ctid> -- free -m
pct exec <ctid> -- df -h
```
### Docker-Tests
```bash
# Docker-Status
pct exec <ctid> -- systemctl status docker
# Container-Liste
pct exec <ctid> -- docker ps
# Container-Logs
pct exec <ctid> -- docker logs n8n
pct exec <ctid> -- docker logs customer-postgres
pct exec <ctid> -- docker logs customer-postgrest
```
### Datenbank-Tests
```bash
# PostgreSQL-Verbindung
pct exec <ctid> -- docker exec customer-postgres pg_isready -U customer
# pgvector-Extension
pct exec <ctid> -- docker exec customer-postgres \
psql -U customer -d customer -c "SELECT extname FROM pg_extension WHERE extname='vector';"
# Tabellen-Liste
pct exec <ctid> -- docker exec customer-postgres \
psql -U customer -d customer -c "\dt"
```
### API-Tests
```bash
# n8n Health
curl http://<ip>:5678/healthz
# PostgREST Root
curl http://<ip>:3000/
# Documents-Tabelle
curl http://<ip>:3000/documents \
-H "apikey: ${ANON_KEY}"
# Chat-Webhook
curl -X POST http://<ip>:5678/webhook/rag-chat-webhook/chat \
-H "Content-Type: application/json" \
-d '{"query":"Test"}'
```
## 🔧 Erweiterte Tests
### Performance-Tests
```bash
# Datenbank-Performance
pct exec <ctid> -- docker exec customer-postgres \
psql -U customer -d customer -c "EXPLAIN ANALYZE SELECT * FROM documents LIMIT 10;"
# API-Response-Zeit
time curl -s http://<ip>:3000/documents > /dev/null
# n8n-Response-Zeit
time curl -s http://<ip>:5678/ > /dev/null
```
### Load-Tests
```bash
# Apache Bench für API
ab -n 1000 -c 10 http://<ip>:3000/
# Parallel-Requests
seq 1 100 | xargs -P 10 -I {} curl -s http://<ip>:3000/documents > /dev/null
```
### Netzwerk-Tests
```bash
# Port-Scanning
nmap -p 3000,5678 <ip>
# Latenz-Test
ping -c 10 <ip>
# Bandbreite-Test
iperf3 -c <ip>
```
## 📝 Test-Protokollierung
### Log-Dateien
```bash
# Test-Logs speichern
./test_complete_system.sh <ctid> <ip> <hostname> 2>&1 | tee test-results.log
# Mit Zeitstempel
./test_complete_system.sh <ctid> <ip> <hostname> 2>&1 | \
tee "test-results-$(date +%Y%m%d-%H%M%S).log"
```
### JSON-Output
```bash
# Test-Ergebnisse als JSON
./test_complete_system.sh <ctid> <ip> <hostname> 2>&1 | \
grep -E '\[PASS\]|\[FAIL\]' | \
awk '{print "{\"status\":\""$1"\",\"test\":\""substr($0,8)"\"}"}' | \
jq -s '.'
```
## 🔄 Continuous Testing
### Automatisierte Tests
```bash
#!/bin/bash
# test-runner.sh - Automatische Test-Ausführung
CREDS_FILE="credentials/sb-*.json"
CTID=$(jq -r '.ctid' $CREDS_FILE)
IP=$(jq -r '.ip' $CREDS_FILE)
HOSTNAME=$(jq -r '.hostname' $CREDS_FILE)
# Tests ausführen
./test_complete_system.sh "$CTID" "$IP" "$HOSTNAME"
# Bei Fehler benachrichtigen
if [ $? -ne 0 ]; then
echo "Tests failed!" | mail -s "Test Failure" admin@example.com
fi
```
### Cron-Job
```bash
# Tägliche Tests um 2 Uhr nachts
0 2 * * * /root/customer-installer/test-runner.sh
```
## 🚨 Troubleshooting
### Tests schlagen fehl
```bash
# 1. Container-Status prüfen
pct status <ctid>
# 2. Docker-Container prüfen
pct exec <ctid> -- docker ps
# 3. Logs prüfen
pct exec <ctid> -- docker logs n8n
pct exec <ctid> -- docker logs customer-postgres
# 4. Netzwerk prüfen
ping <ip>
curl http://<ip>:5678/
```
### Timeout-Probleme
```bash
# Längere Timeouts in Tests
export CURL_TIMEOUT=30
# Oder Tests einzeln ausführen
./test_installation.sh <ctid> <ip> <hostname>
sleep 10
./test_n8n_workflow.sh <ctid> <ip> <email> <password>
```
### Credentials-Probleme
```bash
# Credentials neu laden
CREDS=$(cat credentials/sb-*.json)
# Passwort prüfen
echo "$CREDS" | jq -r '.n8n.owner_password'
# Manuell einloggen testen
curl -X POST http://<ip>:5678/rest/login \
-H "Content-Type: application/json" \
-d '{"emailOrLdapLoginId":"admin@userman.de","password":"..."}'
```
## 📊 Test-Metriken
### Test-Coverage
- **Infrastruktur:** 100% (alle Komponenten getestet)
- **APIs:** 100% (alle Endpoints getestet)
- **Integration:** 100% (End-to-End getestet)
- **Gesamt:** 40+ Test-Cases
### Test-Dauer
- **test_installation.sh:** ~30 Sekunden
- **test_n8n_workflow.sh:** ~20 Sekunden
- **test_postgrest_api.sh:** ~15 Sekunden
- **test_complete_system.sh:** ~90 Sekunden
## 📚 Weiterführende Dokumentation
- [Installation](Installation.md) - Installations-Anleitung
- [Troubleshooting](Troubleshooting.md) - Problemlösung
- [Monitoring](Monitoring.md) - Überwachung
- [API-Referenz](API-Reference.md) - API-Dokumentation
---
**Best Practices:**
1. Tests nach jeder Installation ausführen
2. Tests regelmäßig wiederholen (z.B. täglich)
3. Test-Logs für Debugging aufbewahren
4. Bei Fehlern systematisch vorgehen (Container → Docker → Services → APIs)
5. Performance-Tests bei Produktiv-Systemen durchführen

580
wiki/Troubleshooting.md Normal file
View File

@@ -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