customer-installer/REGISTRATION_TROUBLESHOOTING.md

🔧 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

# 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:

const CONFIG = {
    WEBHOOK_URL: 'https://n8n.userman.de/webhook/botkonzept-registration',
    // ...
};

C) n8n nicht erreichbar

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

/root/customer-installer/install.sh --storage local-zfs ...

3. Passen Sie den Pfad an falls nötig

C) Abhängigkeiten fehlen

# 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

# 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

# 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

# Datenbank erstellen
createdb -U postgres botkonzept

# Schema importieren
psql -U postgres -d botkonzept < /root/customer-installer/sql/botkonzept_schema.sql

C) Berechtigungen fehlen

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

# 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

# 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

# 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

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

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

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

# 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

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

# Container Logs
docker logs -f n8n

# Execution Logs
# In n8n UI: Sidebar → Executions → Click on execution

install.sh Logs

# Auf PVE20
ls -lh /root/customer-installer/logs/
tail -f /root/customer-installer/logs/install_*.log

PostgreSQL Logs

# Auf DB Server
tail -f /var/log/postgresql/postgresql-*.log

# Oder in Supabase Dashboard: Logs

E-Mail Logs

# 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