Installations- und Benutzerhandbuch für Stella AI Chatbot

Dieser Leitfaden deckt sowohl die Free- als auch die Pro-Edition an einem Ort ab. Wenn eine Funktion nur in Pro verfügbar ist, ist sie mit (Pro) markiert.1. Installation1.1 VoraussetzungenNode.js 18+ - Erforderliche Laufzeit zum Ausführen des Chatbot-Backend-Servers.npm - Erforderlich zur Installation der Projektabhängigkeiten.Moderner Browser - Erforderlich für Zugriff auf das Admin-Panel und Tests des Widget-Verhaltens.PostgreSQL 13+ (optional in Pro) - Nur erforderlich, wenn PostgreSQL-Speichermodus gewählt wird.pgvector (optional in Pro) - Erforderlich für PostgreSQL-Vektorähnlichkeitssuche im RAG-Modus.Ollama (optional in Pro) - Nur erforderlich, wenn lokale Embedding-Erzeugung ohne API-Kosten genutzt wird.1.2 Herunterladen und vorbereitenPaket entpacken - Entpacke entweder stella-ai-chatbot-free oder stella-ai-chatbot-pro.Ordner im Terminal öffnen - Führe alle Installations-/Startbefehle aus diesem Verzeichnis aus.Abhängigkeiten installieren - Lädt alle erforderlichen Backend-Bibliotheken herunter.npm install1.3 Umgebung konfigurieren.env erstellen - Kopiere .env.example nach .env.Erforderliche Variablen setzen:NODE_ENV - Definiert den Laufzeitmodus (development oder production).APP_SECRET - Wird zum Signieren/Verifizieren sicherer Tokens und Sessions verwendet.ADMIN_USER - Admin-Benutzername.ADMIN_PASS - Admin-Passwort.INSTALL_TOKEN - Schützt den Installer vor unbefugtem Zugriff.CORS_ORIGINS / ALLOWED_ORIGINS - Steuert, welche Origins APIs aufrufen dürfen.DATA_ENCRYPTION_KEY - Zur Verschlüsselung sensibler Daten (falls unterstützt).Optionale Variablen:PORT - Server-Port (kann von der Plattform dynamisch überschrieben werden).TRUST_PROXY=true - Aktiviert korrekte IP-Erkennung hinter Reverse Proxy/CDN.1.4 Anwendung startennpm start/install - Ersteinrichtungsassistent./admin - Admin-Login und Dashboard.1.5 InstallationsschritteInstaller öffnen - /install initialisiert das Chatbot-System.Installations-Token eingeben - Bestätigt autorisierte Installation.Speichermodus wählen:Free: JSON-Speicher.Pro: JSON oder PostgreSQL.Installation abschließen - Erstellt erforderliche Standardwerte/Einstellungen.install.lock erzeugt - Verhindert versehentliche Neuinstallation und liegt im data-Ordner.1.6 Widget auf beliebiger Website einbindenEmbed-Code-Bereich öffnen - Generiert Script für Frontend-Integration.Script kopieren - Enthält Widget-Loader und API-Basis-URL.Vor </body> einfügen - Stellt sicher, dass das Widget nach dem Seiteninhalt lädt.Seite aktualisieren - Prüft, ob Chatbot angezeigt wird und funktioniert.1.7 Produktions-ChecklisteHTTPS aktivieren - Schützt Datenverkehr und Zugangsdaten.Starke Secrets verwenden - Verhindert Kompromittierung von Token/Sessions.Domains einschränken - Verhindert Widget/API-Missbrauch auf nicht autorisierten Websites.Installer schützen - Blockiert öffentliche Neuinstallationsangriffe.CSRF-/Sicherheitskontrollen aktivieren - Schützt Admin-Schreibvorgänge.Aufbewahrungsrichtlinie setzen - Hält Logs verwaltbar und regelkonform.2. Benutzerhandbuch (Schritt für Schritt)2.1 Admin-Login/admin öffnen - Zugriff auf die Admin-Einstiegsseite.Anmelden - Verwendet Zugangsdaten aus .env.Menü nutzen - Overview, Settings, FAQs, Logs.2.2 Overview-SeiteNutzungsstatistiken - Zeigt eine Zusammenfassung der Chatbot-Aktivität.Matched vs unmatched - Zeigt den Trend der Antwortqualität.Top matched keywords - Erkennt, welche Fragen erfolgreich beantwortet werden.Top unmatched questions - Zeigt FAQ/AI-Inhaltslücken zur Optimierung.2.3 Settings-SeiteA. Core IdentityChatbot Name - Titel im Chat-Header.Avatar Upload - Markenbild in Launcher und Chat.Avatar Shape - Steuert, ob Avatar rund oder quadratisch erscheint.Show Live Preview - Aktiviert/deaktiviert Live-Vorschau im Admin.B. Messaging & EngagementWelcome Message - Nachricht beim Öffnen der Chatbox.No Match Message - Fallback-Antwort, wenn keine passende Antwort gefunden wird.Fuzzy Match - Findet ähnliche Schlüsselwörter/Fragen auch ohne exakte Übereinstimmung.Fuzzy Threshold - Legt die Strenge des Fuzzy Matching fest.Lead Capture - Erfasst Name/E-Mail vor oder während des Chats.Lead Capture Prompt - Nachricht zur Abfrage von Besucherdaten.C. Widget AppearanceWidget Position - Platziert den Launcher links oder rechts.Widget Size - Steuert die visuelle Größe des Launchers.Brand/Theme Colors - Passt das Widget an das Branding der Website an.Avatar Size - Steuert die Avatargröße in der Chat-UI.Animation - Fügt Effekte wie pulse/shake/float hinzu.Chatbox Width/Height - Steuert die Größe des Gesprächspanels.D. System & PerformanceItems Per Page - Seitengröße der Admin-Tabellen.Log Retention Days - Anzahl Tage bis zur Log-Bereinigung.Auto Cleanup - Löscht alte Daten automatisch nach Aufbewahrungsregel.Enforce HTTPS - Blockiert unsichere Nicht-HTTPS-Anfragen (außer localhost).Enforce Admin CSRF - Erfordert CSRF-Token für Admin-Schreibvorgänge.E. CategoriesAdd Category - Erstellt neue Gruppen für FAQ/Chat-Flows.Recommended Categories - Bis zu 3 Kategorien werden zuerst im Widget angezeigt.Delete Category - Entfernt ungenutzte Kategorie (oder Merge/Neuzuweisungslogik greift).F. Embed CodeAPI Base URL - Definiert die Backend-URL des Widget-Scripts.Allowed Widget Domains - Beschränkt, wo das Widget ausgeführt werden darf.Widget Domain Policy - restricted erzwingt Liste erlaubter Domains.Regenerate / Copy Code - Erneuert und kopiert den Embed-Code.2.4 Pro-Funktionen in Settings (Pro)A. Human Handoff (Pro)Enable Handoff - Aktiviert Eskalation an menschlichen Support.Escalate After Unmatched - Anzahl fehlgeschlagener Matches bis zur Eskalation.Handoff Message - Nachricht bei ausgelöster Eskalation.Support URL - Link zur Kontaktaufnahme mit menschlichem Support.Business Hours - Optionales Zeitfenster für Handoff-Verhalten.B. AI Powered Responses (Pro)AI Provider - Wählt den LLM-Backend-Anbieter.API Key - Authentifizierungsschlüssel des Anbieters.Load Models - Lädt verfügbare Modelle für Anbieter/Key.AI Model - Modell zur Antwortgenerierung.Test Connection - Prüft Anbieter-/Modell-/Key-Konfiguration.Max Tokens - Maximale Ausgabelänge der AI-Antwort.System Instructions - Definiert Verhalten, Ton und Regeln des Bots.AI Disclaimer - Optionaler Hinweistext unter AI-Antworten.C. Vector Retrieval (RAG) (Pro)Enable RAG - Aktiviert Retrieval aus indexierten Website-Inhalten.Use PostgreSQL pgvector - Aktiviert skalierbare Vektorspeicherung/-suche.Embedding Provider - Dienst zur Umwandlung von Text in Vektoren.Embedding API Key - Authentifizierung für Embedding-Anbieter.Fetch Models - Lädt verfügbare Embedding-Modelle.Embedding Model - Modell für Indexierung und Query-Embeddings.Test Embedding Connection - Prüft Embedding-Endpunkt.Crawl Root URL / Sitemap - Definiert Startpunkte des Crawlings.Max Pages / Max Depth - Steuert Umfang und Tiefe des Crawlings.Chunk Size / Overlap - Steuert Textsegmentierung für bessere Retrieval-Qualität.Include / Exclude Patterns - Feinkontrolle über zu crawlende URLs.Resume Mode - Überspringt bereits indexierte URLs beim Recrawl.Crawl Website Content - Startet den Indexierungsjob.RAG Ranking Mode - Steuert Ranking-Strategie (Balanced / Exact Product First).2.5 FAQs-SeiteAdd FAQ - Manuelle Q&A-Erstellung mit eindeutigem Keyword.Edit/Delete FAQ - Pflege und Korrektur bestehender Antworten.Import File - Massenimport aus TXT/CSV/CSB/DOCX.Delimiter Option - Parst benutzerdefinierte Dateiformate (:, ,, | usw.).Duplicate Keyword Handling - Überspringen oder Suffix bei Duplikaten.Category Handling - Fehlende Kategorien erstellen oder Fallback-Kategorie verwenden.Import Summary - Zeigt Anzahl hinzugefügt/abgelehnt/dupliziert.2.6 Logs-SeiteSession Filters - Suche nach Session-Key, Name oder E-Mail.Show Chat - Öffnet Chatverlauf nur der ausgewählten Session.Leads Table - Zeigt erfasste Besucherkontaktdaten.Pagination - Effiziente Navigation großer Datenmengen mit oberen/unteren Kontrollen.2.7 Frontend-VerhaltenWidget Open - Nutzer öffnet Launcher und startet Chat.Welcome/Categories - Einleitung und Empfehlungen erscheinen (wenn aktiviert).User Query Handling:Free: FAQ + Fuzzy-Match-Flow.Pro: FAQ + AI + RAG + Handoff-Regeln.Lead Collection - Name/E-Mail-Formular erscheint, wenn aktiviert.Logging - Sessions/Nachrichten/Leads werden für Analytics gespeichert.2.8 FehlerbehebungWidget nicht sichtbar - Embed-Code, Domain-Policy und Browserkonsole prüfen.Kurze AI-Antworten - Anderes Modell/Anbieter testen, max tokens erhöhen, Provider-Metadaten prüfen.RAG antwortet nicht - Crawl-Erfolg, Embedding-Konfiguration und Ranking-Modus prüfen.Installation blockiert - Install-Token und Lock/Maintenance-Verhalten prüfen.2.9 Empfohlener Rollout-PfadMit FAQ + Kategorien starten - Zuverlässige Basisantworten aufbauen.Fuzzy Match aktivieren - Toleranz für variierende Fragen erhöhen.Lead Capture aktivieren - Qualifizierte Kontakte erfassen.(Pro) AI aktivieren - Breitere natürlichsprachliche Anfragen abdecken.(Pro) RAG aktivieren - Antworten auf eigene Website-Inhalte stützen.(Pro) Handoff aktivieren - Komplexe Anliegen an Menschen eskalieren.Sicherheit finalisieren + deployen - Richtlinien fixieren und produktiv gehen.