docs: Registrierungs-Setup und Troubleshooting Guides
Neue Dateien: - BotKonzept-Customer-Registration-Workflow.json: n8n Workflow für Kundenregistrierung - BotKonzept-Trial-Management-Workflow.json: n8n Workflow für Trial-Management - REGISTRATION_SETUP_GUIDE.md: Kompletter Setup-Guide (Datenbank, Credentials, Workflows) - REGISTRATION_TROUBLESHOOTING.md: Troubleshooting-Guide mit 10 häufigen Problemen Gelöscht: - 20250119_Logo_Botkozept.svg: Verschoben nach customer-frontend Die Workflows enthalten: - Webhook-Trigger für Registrierung - Datenbank-Integration (PostgreSQL/Supabase) - SSH-Integration zu PVE20 für LXC-Erstellung - E-Mail-Versand (Willkommens-E-Mail) - Trial-Management mit automatischen E-Mails (Tag 3, 5, 7) Setup-Guide erklärt: - Datenbank-Schema einrichten - n8n Credentials konfigurieren (Supabase, SSH, SMTP) - Workflows importieren und aktivieren - Testing und Monitoring Troubleshooting-Guide behandelt: - Workflow-Probleme - Credential-Fehler - SSH-Verbindungsprobleme - Datenbank-Fehler - E-Mail-Versand-Probleme - JSON-Parsing-Fehler - Performance-Probleme - Debugging-Checkliste
This commit is contained in:
581
REGISTRATION_TROUBLESHOOTING.md
Normal file
581
REGISTRATION_TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,581 @@
|
||||
# 🔧 BotKonzept - Registrierung Troubleshooting
|
||||
|
||||
## Häufige Probleme und Lösungen
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 1: Workflow wird nicht ausgeführt
|
||||
|
||||
### Symptome
|
||||
- Frontend zeigt "Verbindungsfehler"
|
||||
- Keine Execution in n8n History
|
||||
- Timeout-Fehler
|
||||
|
||||
### Diagnose
|
||||
```bash
|
||||
# 1. Prüfen ob n8n läuft
|
||||
curl -I https://n8n.userman.de
|
||||
|
||||
# 2. Webhook-URL testen
|
||||
curl -X POST https://n8n.userman.de/webhook/botkonzept-registration \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"firstName":"Test","lastName":"User","email":"test@test.de"}'
|
||||
```
|
||||
|
||||
### Lösungen
|
||||
|
||||
#### A) Workflow nicht aktiviert
|
||||
1. Öffnen Sie n8n
|
||||
2. Öffnen Sie den Workflow
|
||||
3. Klicken Sie auf den **Toggle oben rechts** (muss grün sein)
|
||||
4. Speichern Sie den Workflow
|
||||
|
||||
#### B) Webhook-Pfad falsch
|
||||
1. Öffnen Sie den Workflow
|
||||
2. Klicken Sie auf "Registration Webhook" Node
|
||||
3. Prüfen Sie den Pfad: Sollte `botkonzept-registration` sein
|
||||
4. Kopieren Sie die "Production URL"
|
||||
5. Aktualisieren Sie `customer-frontend/js/main.js`:
|
||||
```javascript
|
||||
const CONFIG = {
|
||||
WEBHOOK_URL: 'https://n8n.userman.de/webhook/botkonzept-registration',
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
#### C) n8n nicht erreichbar
|
||||
```bash
|
||||
# Auf dem n8n Server
|
||||
docker ps | grep n8n
|
||||
docker logs n8n
|
||||
|
||||
# Falls Container nicht läuft
|
||||
docker start n8n
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 2: "Credential not found" Fehler
|
||||
|
||||
### Symptome
|
||||
- Workflow stoppt bei einem Node
|
||||
- Fehler: "Credential 'Supabase Local' not found"
|
||||
- Execution zeigt roten Fehler
|
||||
|
||||
### Lösung
|
||||
|
||||
#### Schritt 1: Credentials prüfen
|
||||
1. n8n → Sidebar → **Credentials**
|
||||
2. Prüfen Sie ob folgende existieren:
|
||||
- `Supabase Local` (Postgres)
|
||||
- `PVE20` (SSH)
|
||||
- `Postfix SES` (SMTP)
|
||||
|
||||
#### Schritt 2: Credential erstellen (falls fehlend)
|
||||
|
||||
**Supabase Local:**
|
||||
```
|
||||
Name: Supabase Local
|
||||
Type: Postgres
|
||||
Host: localhost (oder Ihr Supabase Host)
|
||||
Port: 5432
|
||||
Database: botkonzept
|
||||
User: postgres
|
||||
Password: [Ihr Passwort]
|
||||
SSL: Enabled
|
||||
```
|
||||
|
||||
**PVE20:**
|
||||
```
|
||||
Name: PVE20
|
||||
Type: SSH (Private Key)
|
||||
Host: 192.168.45.20
|
||||
Port: 22
|
||||
Username: root
|
||||
Private Key: [Fügen Sie Ihren Private Key ein]
|
||||
```
|
||||
|
||||
**Postfix SES:**
|
||||
```
|
||||
Name: Postfix SES
|
||||
Type: SMTP
|
||||
Host: email-smtp.eu-central-1.amazonaws.com
|
||||
Port: 587
|
||||
User: [SMTP Username]
|
||||
Password: [SMTP Password]
|
||||
From: noreply@botkonzept.de
|
||||
```
|
||||
|
||||
#### Schritt 3: Credential im Workflow zuweisen
|
||||
1. Öffnen Sie den betroffenen Node
|
||||
2. Klicken Sie auf "Credential to connect with"
|
||||
3. Wählen Sie das richtige Credential
|
||||
4. Speichern Sie den Workflow
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 3: SSH-Verbindung zu PVE20 schlägt fehl
|
||||
|
||||
### Symptome
|
||||
- Node "Create Customer Instance" schlägt fehl
|
||||
- Fehler: "Connection refused" oder "Permission denied"
|
||||
|
||||
### Diagnose
|
||||
```bash
|
||||
# Auf dem n8n Server (im Container)
|
||||
docker exec -it n8n sh
|
||||
|
||||
# SSH-Verbindung testen
|
||||
ssh root@192.168.45.20 "echo 'Connection OK'"
|
||||
```
|
||||
|
||||
### Lösungen
|
||||
|
||||
#### A) SSH Key nicht konfiguriert
|
||||
```bash
|
||||
# Auf dem n8n Server (Host, nicht Container)
|
||||
ssh-keygen -t ed25519 -C "n8n@botkonzept" -f ~/.ssh/n8n_key
|
||||
|
||||
# Public Key auf PVE20 kopieren
|
||||
ssh-copy-id -i ~/.ssh/n8n_key.pub root@192.168.45.20
|
||||
|
||||
# Private Key anzeigen (für n8n Credential)
|
||||
cat ~/.ssh/n8n_key
|
||||
```
|
||||
|
||||
#### B) SSH Key im Container nicht verfügbar
|
||||
```bash
|
||||
# SSH Key als Volume mounten
|
||||
docker run -d \
|
||||
--name n8n \
|
||||
-v ~/.ssh:/home/node/.ssh:ro \
|
||||
-v n8n_data:/home/node/.n8n \
|
||||
-p 5678:5678 \
|
||||
n8nio/n8n
|
||||
```
|
||||
|
||||
#### C) Firewall blockiert
|
||||
```bash
|
||||
# Auf PVE20
|
||||
iptables -L -n | grep 22
|
||||
|
||||
# Falls blockiert, Regel hinzufügen
|
||||
iptables -A INPUT -p tcp --dport 22 -j ACCEPT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 4: install.sh schlägt fehl
|
||||
|
||||
### Symptome
|
||||
- SSH-Verbindung OK, aber install.sh gibt Fehler
|
||||
- Fehler: "No such file or directory"
|
||||
- Fehler: "Permission denied"
|
||||
|
||||
### Diagnose
|
||||
```bash
|
||||
# Auf PVE20
|
||||
ls -lh /root/customer-installer/install.sh
|
||||
|
||||
# Ausführbar?
|
||||
chmod +x /root/customer-installer/install.sh
|
||||
|
||||
# Manuell testen
|
||||
cd /root/customer-installer
|
||||
./install.sh --help
|
||||
```
|
||||
|
||||
### Lösungen
|
||||
|
||||
#### A) Repository nicht geklont
|
||||
```bash
|
||||
# Auf PVE20
|
||||
cd /root
|
||||
git clone https://backoffice.userman.de/MediaMetz/customer-installer.git
|
||||
cd customer-installer
|
||||
chmod +x install.sh
|
||||
```
|
||||
|
||||
#### B) Pfad im Workflow falsch
|
||||
1. Öffnen Sie den Node "Create Customer Instance"
|
||||
2. Prüfen Sie den Command:
|
||||
```bash
|
||||
/root/customer-installer/install.sh --storage local-zfs ...
|
||||
```
|
||||
3. Passen Sie den Pfad an falls nötig
|
||||
|
||||
#### C) Abhängigkeiten fehlen
|
||||
```bash
|
||||
# Auf PVE20
|
||||
apt-get update
|
||||
apt-get install -y jq curl python3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 5: Datenbank-Fehler
|
||||
|
||||
### Symptome
|
||||
- Fehler: "relation 'customers' does not exist"
|
||||
- Fehler: "permission denied for table customers"
|
||||
- Fehler: "connection refused"
|
||||
|
||||
### Diagnose
|
||||
```bash
|
||||
# Verbindung testen
|
||||
psql -h localhost -U postgres -d botkonzept -c "SELECT 1;"
|
||||
|
||||
# Tabellen prüfen
|
||||
psql -h localhost -U postgres -d botkonzept -c "\dt"
|
||||
```
|
||||
|
||||
### Lösungen
|
||||
|
||||
#### A) Schema nicht erstellt
|
||||
```bash
|
||||
# Schema erstellen
|
||||
psql -U postgres -d botkonzept < /root/customer-installer/sql/botkonzept_schema.sql
|
||||
|
||||
# Prüfen
|
||||
psql -U postgres -d botkonzept -c "\dt"
|
||||
```
|
||||
|
||||
#### B) Datenbank existiert nicht
|
||||
```bash
|
||||
# Datenbank erstellen
|
||||
createdb -U postgres botkonzept
|
||||
|
||||
# Schema importieren
|
||||
psql -U postgres -d botkonzept < /root/customer-installer/sql/botkonzept_schema.sql
|
||||
```
|
||||
|
||||
#### C) Berechtigungen fehlen
|
||||
```sql
|
||||
-- Als postgres User
|
||||
GRANT ALL ON ALL TABLES IN SCHEMA public TO service_role;
|
||||
GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO service_role;
|
||||
```
|
||||
|
||||
#### D) Supabase: Falsche Credentials
|
||||
1. Gehen Sie zu Supabase Dashboard
|
||||
2. Settings → Database
|
||||
3. Kopieren Sie die Connection String
|
||||
4. Aktualisieren Sie das n8n Credential
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 6: E-Mail wird nicht versendet
|
||||
|
||||
### Symptome
|
||||
- Workflow läuft durch, aber keine E-Mail
|
||||
- Fehler: "SMTP connection failed"
|
||||
- E-Mail landet im Spam
|
||||
|
||||
### Diagnose
|
||||
```bash
|
||||
# SMTP-Verbindung testen
|
||||
telnet email-smtp.eu-central-1.amazonaws.com 587
|
||||
|
||||
# Postfix Status (falls lokal)
|
||||
systemctl status postfix
|
||||
journalctl -u postfix -n 50
|
||||
```
|
||||
|
||||
### Lösungen
|
||||
|
||||
#### A) Amazon SES: E-Mail nicht verifiziert
|
||||
1. Gehen Sie zu AWS SES Console
|
||||
2. Verified Identities → Verify new email
|
||||
3. Bestätigen Sie die E-Mail
|
||||
4. Warten Sie auf Verifizierung
|
||||
|
||||
#### B) Amazon SES: Sandbox-Modus
|
||||
1. AWS SES Console → Account Dashboard
|
||||
2. Request production access
|
||||
3. Füllen Sie das Formular aus
|
||||
4. Warten Sie auf Genehmigung (24-48h)
|
||||
|
||||
**Workaround für Tests:**
|
||||
- Verifizieren Sie auch die Empfänger-E-Mail
|
||||
- Oder verwenden Sie Gmail für Tests
|
||||
|
||||
#### C) SMTP-Credentials falsch
|
||||
1. AWS IAM → Users → Ihr SMTP User
|
||||
2. Security Credentials → Create SMTP credentials
|
||||
3. Kopieren Sie Username und Password
|
||||
4. Aktualisieren Sie n8n SMTP Credential
|
||||
|
||||
#### D) SPF/DKIM nicht konfiguriert
|
||||
```bash
|
||||
# DNS-Records prüfen
|
||||
dig TXT botkonzept.de
|
||||
dig TXT _dmarc.botkonzept.de
|
||||
|
||||
# Fehlende Records hinzufügen (bei Ihrem DNS-Provider)
|
||||
```
|
||||
|
||||
**Benötigte DNS-Records:**
|
||||
```
|
||||
# SPF
|
||||
botkonzept.de. IN TXT "v=spf1 include:amazonses.com ~all"
|
||||
|
||||
# DKIM (von AWS SES bereitgestellt)
|
||||
[selector]._domainkey.botkonzept.de. IN CNAME [value-from-ses]
|
||||
|
||||
# DMARC
|
||||
_dmarc.botkonzept.de. IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@botkonzept.de"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 7: JSON-Parsing-Fehler
|
||||
|
||||
### Symptome
|
||||
- Fehler: "Unexpected token in JSON"
|
||||
- Node "Parse Install Output" schlägt fehl
|
||||
|
||||
### Diagnose
|
||||
```bash
|
||||
# install.sh manuell ausführen und Output prüfen
|
||||
cd /root/customer-installer
|
||||
./install.sh --storage local-zfs --bridge vmbr0 --ip dhcp --vlan 90 2>&1 | tee test-output.log
|
||||
|
||||
# Ist der Output valides JSON?
|
||||
cat test-output.log | jq .
|
||||
```
|
||||
|
||||
### Lösungen
|
||||
|
||||
#### A) install.sh gibt Fehler aus
|
||||
- Prüfen Sie die Logs in `/root/customer-installer/logs/`
|
||||
- Beheben Sie die Fehler in install.sh
|
||||
- Testen Sie erneut
|
||||
|
||||
#### B) Output enthält zusätzliche Zeilen
|
||||
1. Öffnen Sie `install.sh`
|
||||
2. Stellen Sie sicher, dass nur JSON auf stdout ausgegeben wird
|
||||
3. Alle anderen Ausgaben sollten nach stderr gehen
|
||||
|
||||
#### C) DEBUG-Modus aktiviert
|
||||
1. Prüfen Sie ob `DEBUG=1` gesetzt ist
|
||||
2. Für Produktion: `DEBUG=0` verwenden
|
||||
3. Im Workflow: Command ohne `--debug` ausführen
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 8: Workflow zu langsam / Timeout
|
||||
|
||||
### Symptome
|
||||
- Frontend zeigt Timeout nach 30 Sekunden
|
||||
- Workflow läuft noch, aber Frontend gibt auf
|
||||
|
||||
### Lösung
|
||||
|
||||
#### A) Timeout im Frontend erhöhen
|
||||
```javascript
|
||||
// In customer-frontend/js/main.js
|
||||
const response = await fetch(CONFIG.WEBHOOK_URL, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
},
|
||||
body: JSON.stringify(formData),
|
||||
signal: AbortSignal.timeout(300000), // 5 Minuten
|
||||
});
|
||||
```
|
||||
|
||||
#### B) Asynchrone Verarbeitung
|
||||
Ändern Sie den Workflow:
|
||||
1. Webhook gibt sofort Response zurück
|
||||
2. Instanz-Erstellung läuft im Hintergrund
|
||||
3. E-Mail wird gesendet wenn fertig
|
||||
|
||||
**Workflow-Änderung:**
|
||||
- Nach "Create Customer in DB" → Sofort Response
|
||||
- Rest des Workflows läuft asynchron weiter
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 9: Doppelte Registrierungen
|
||||
|
||||
### Symptome
|
||||
- Kunde registriert sich mehrmals
|
||||
- Mehrere Einträge in `customers` Tabelle
|
||||
- Mehrere LXC-Container
|
||||
|
||||
### Lösung
|
||||
|
||||
#### A) E-Mail-Unique-Constraint prüfen
|
||||
```sql
|
||||
-- Prüfen ob Constraint existiert
|
||||
SELECT conname, contype
|
||||
FROM pg_constraint
|
||||
WHERE conrelid = 'customers'::regclass;
|
||||
|
||||
-- Falls nicht, hinzufügen
|
||||
ALTER TABLE customers ADD CONSTRAINT customers_email_unique UNIQUE (email);
|
||||
```
|
||||
|
||||
#### B) Workflow anpassen
|
||||
Fügen Sie einen Check-Node hinzu:
|
||||
```javascript
|
||||
// Vor "Create Customer in DB"
|
||||
const email = $json.body.email;
|
||||
const existing = await $('Postgres').execute({
|
||||
query: 'SELECT id FROM customers WHERE email = $1',
|
||||
values: [email]
|
||||
});
|
||||
|
||||
if (existing.length > 0) {
|
||||
throw new Error('E-Mail bereits registriert');
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Problem 10: Trial-Management läuft nicht
|
||||
|
||||
### Symptome
|
||||
- Keine E-Mails an Tag 3, 5, 7
|
||||
- Cron-Workflow wird nicht ausgeführt
|
||||
|
||||
### Diagnose
|
||||
```bash
|
||||
# In n8n: Executions filtern nach "Trial Management"
|
||||
# Prüfen ob täglich um 9:00 Uhr ausgeführt wird
|
||||
```
|
||||
|
||||
### Lösungen
|
||||
|
||||
#### A) Workflow nicht aktiviert
|
||||
1. Öffnen Sie "BotKonzept - Trial Management"
|
||||
2. Aktivieren Sie den Workflow (Toggle oben rechts)
|
||||
|
||||
#### B) Cron-Expression falsch
|
||||
1. Öffnen Sie den Node "Daily at 9 AM"
|
||||
2. Prüfen Sie die Expression: `0 9 * * *`
|
||||
3. Testen Sie mit: https://crontab.guru/#0_9_*_*_*
|
||||
|
||||
#### C) Keine Trial-Kunden vorhanden
|
||||
```sql
|
||||
-- Prüfen
|
||||
SELECT * FROM customers WHERE status = 'trial';
|
||||
|
||||
-- Test-Kunde erstellen
|
||||
INSERT INTO customers (email, first_name, last_name, status, created_at)
|
||||
VALUES ('test@example.com', 'Test', 'User', 'trial', NOW() - INTERVAL '3 days');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Debugging-Checkliste
|
||||
|
||||
Wenn ein Problem auftritt, gehen Sie diese Checkliste durch:
|
||||
|
||||
### 1. Frontend
|
||||
- [ ] Browser-Konsole prüfen (F12)
|
||||
- [ ] Network-Tab prüfen (Request/Response)
|
||||
- [ ] Webhook-URL korrekt?
|
||||
|
||||
### 2. n8n
|
||||
- [ ] Workflow aktiviert?
|
||||
- [ ] Execution History prüfen
|
||||
- [ ] Jeden Node einzeln testen
|
||||
- [ ] Credentials korrekt?
|
||||
|
||||
### 3. Datenbank
|
||||
- [ ] Verbindung OK?
|
||||
- [ ] Tabellen existieren?
|
||||
- [ ] Berechtigungen OK?
|
||||
- [ ] Daten werden gespeichert?
|
||||
|
||||
### 4. PVE20
|
||||
- [ ] SSH-Verbindung OK?
|
||||
- [ ] install.sh existiert?
|
||||
- [ ] install.sh ausführbar?
|
||||
- [ ] Manueller Test OK?
|
||||
|
||||
### 5. E-Mail
|
||||
- [ ] SMTP-Verbindung OK?
|
||||
- [ ] Absender verifiziert?
|
||||
- [ ] Spam-Ordner prüfen?
|
||||
- [ ] DNS-Records korrekt?
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Logs & Debugging
|
||||
|
||||
### n8n Logs
|
||||
```bash
|
||||
# Container Logs
|
||||
docker logs -f n8n
|
||||
|
||||
# Execution Logs
|
||||
# In n8n UI: Sidebar → Executions → Click on execution
|
||||
```
|
||||
|
||||
### install.sh Logs
|
||||
```bash
|
||||
# Auf PVE20
|
||||
ls -lh /root/customer-installer/logs/
|
||||
tail -f /root/customer-installer/logs/install_*.log
|
||||
```
|
||||
|
||||
### PostgreSQL Logs
|
||||
```bash
|
||||
# Auf DB Server
|
||||
tail -f /var/log/postgresql/postgresql-*.log
|
||||
|
||||
# Oder in Supabase Dashboard: Logs
|
||||
```
|
||||
|
||||
### E-Mail Logs
|
||||
```bash
|
||||
# Postfix
|
||||
journalctl -u postfix -f
|
||||
|
||||
# Amazon SES
|
||||
# AWS Console → SES → Sending Statistics
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Wenn nichts hilft
|
||||
|
||||
### Schritt-für-Schritt-Debugging
|
||||
|
||||
1. **Workflow deaktivieren**
|
||||
2. **Jeden Node einzeln testen:**
|
||||
```
|
||||
- Webhook → Test mit curl
|
||||
- Validate Input → Manuell ausführen
|
||||
- Generate Password → Output prüfen
|
||||
- Create Customer → DB prüfen
|
||||
- SSH → Manuell auf PVE20 testen
|
||||
- Parse Output → JSON validieren
|
||||
- Save Instance → DB prüfen
|
||||
- Send Email → Test-E-Mail
|
||||
```
|
||||
3. **Logs sammeln:**
|
||||
- n8n Execution
|
||||
- install.sh Log
|
||||
- PostgreSQL Log
|
||||
- E-Mail Log
|
||||
4. **Support kontaktieren** mit allen Logs
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support-Kontakt
|
||||
|
||||
**E-Mail:** support@botkonzept.de
|
||||
|
||||
**Bitte inkludieren:**
|
||||
- Fehlermeldung (vollständig)
|
||||
- n8n Execution ID
|
||||
- Logs (n8n, install.sh, DB)
|
||||
- Was Sie bereits versucht haben
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Letzte Aktualisierung:** 26.01.2025
|
||||
Reference in New Issue
Block a user