docs: Add comprehensive Wiki documentation
- 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:
503
wiki/Architecture.md
Normal file
503
wiki/Architecture.md
Normal 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
387
wiki/Credentials-Management.md
Normal 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
515
wiki/FAQ.md
Normal 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
111
wiki/Home.md
Normal 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
298
wiki/Installation.md
Normal 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
415
wiki/Testing.md
Normal 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
580
wiki/Troubleshooting.md
Normal 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
|
||||||
Reference in New Issue
Block a user