Lokale Ausführung Einrichtungsleitfaden

Dieser Leitfaden hilft Ihnen, Flowguard so einzurichten, dass Flows auf Ihrem eigenen Server ausgeführt werden, anstatt den Cloud-basierten Ausführungsdienst zu verwenden.

Warum lokale Ausführung?

Das lokale Ausführen von Flowguard auf Ihrem Server bietet mehrere Vorteile:

• Datenschutz: Alle Testdaten bleiben auf Ihrem Server
• Leistung: Geringere Latenz für Flow-Ausführungen
• Kontrolle: Volle Kontrolle über die Ausführungsumgebung
• Kosten: Keine Abhängigkeit von externen Diensten

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Ihr Server diese Anforderungen erfüllt:

• Node.js Version 18.0.0 oder höher
• npm Version 8.0.0 oder höher
• Ausreichend Speicherplatz für Playwright-Browser (~500MB)
• Serverzugriff zum Installieren von Paketen und Ausführen von Node.js-Prozessen

Schritt-für-Schritt-Einrichtung

1. Node.js installieren

Wenn Node.js noch nicht auf Ihrem Server installiert ist:

Ubuntu/Debian

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS/RHEL

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

macOS (mit Homebrew)

brew install node

Überprüfen Sie die Installation:

node --version
npm --version

2. API-Verzeichnis kopieren

Kopieren Sie das Flowguard-API-Verzeichnis an einen Ort auf Ihrem Server:

# Beispiel: Vom Plugin-Verzeichnis an einen benutzerdefinierten Ort kopieren
cp -r /pfad/zu/wordpress/wp-content/plugins/flowguard/api /var/www/flowguard-api

Hinweis: Sie können das API-Verzeichnis überall auf Ihrem Server platzieren. Stellen Sie sicher, dass das Verzeichnis für Ihren Webserver-Benutzer lesbar und ausführbar ist.

3. Abhängigkeiten installieren

Navigieren Sie zum API-Verzeichnis und installieren Sie die erforderlichen npm-Pakete:

cd /var/www/flowguard-api
npm install

Dies installiert:

• express - Web-Server-Framework
• playwright - Browser-Automatisierungsbibliothek
• axios - HTTP-Client
• dotenv - Umgebungsvariablen-Verwaltung

4. Playwright-Browser installieren

Playwright benötigt Browser-Binärdateien:

npx playwright install

Dies lädt Chromium, Firefox und WebKit-Browser herunter und installiert sie.

Für Headless-Server müssen Sie möglicherweise zusätzliche Systemabhängigkeiten installieren:

# Ubuntu/Debian
npx playwright install-deps

# Oder manuell
sudo apt-get install -y \
    libnss3 \
    libnspr4 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libdbus-1-3 \
    libxkbcommon0 \
    libatspi2.0-0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libpango-1.0-0 \
    libcairo2 \
    libasound2

5. Umgebung konfigurieren (Optional)

Erstellen Sie eine .env-Datei im API-Verzeichnis, um Einstellungen anzupassen:

cd /var/www/flowguard-api
nano .env

Fügen Sie folgende Konfiguration hinzu:

# Server-Konfiguration
PORT=3000
HOST=localhost
NODE_ENV=production

# Flow-Konfiguration
FLOW_TIMEOUT=300000

Konfigurationsoptionen:

Variable	Beschreibung	Standard
PORT	Portnummer für den API-Server	3000
HOST	Hostname zum Binden	localhost
NODE_ENV	Umgebungsmodus	development
FLOW_TIMEOUT	Maximale Zeit für Flow-Ausführung (ms)	300000 (5 Min)

6. Server starten

Sie haben mehrere Optionen zum Starten des Servers:

Lokale API vs. Vollständige API

Das Plugin enthält eine minimale lokale API, die nur Flow-Ausführungsfunktionen enthält. Sie verwendet server-local.js als Einstiegspunkt mit weniger Abhängigkeiten. Dies unterscheidet sich von der vollständigen API, die Monitoring, Datenbank und andere Funktionen enthält.

Option A: Manueller Start (zum Testen)

cd /var/www/flowguard-api
npm start

Drücken Sie Strg+C, um den Server zu stoppen.

Option B: Hintergrundprozess mit PM2 (Empfohlen)

PM2 ist ein Produktions-Prozessmanager für Node.js-Anwendungen.

PM2 global installieren:

sudo npm install -g pm2

Server mit PM2 starten:

cd /var/www/flowguard-api
pm2 start npm --name flowguard-api -- start

Nützliche PM2-Befehle:

pm2 status              # Serverstatus prüfen
pm2 logs flowguard-api  # Protokolle anzeigen
pm2 restart flowguard-api  # Server neu starten
pm2 stop flowguard-api  # Server stoppen
pm2 delete flowguard-api  # Aus PM2 entfernen

PM2 beim Systemstart automatisch starten:

pm2 startup
pm2 save

Option C: systemd-Dienst (Linux)

systemd-Dienstdatei erstellen:

sudo nano /etc/systemd/system/flowguard-api.service

Folgende Konfiguration hinzufügen:

[Unit]
Description=Flowguard API Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/flowguard-api
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
Environment=PORT=3000

[Install]
WantedBy=multi-user.target

Dienst aktivieren und starten:

sudo systemctl daemon-reload
sudo systemctl enable flowguard-api
sudo systemctl start flowguard-api

Status prüfen:

sudo systemctl status flowguard-api

Protokolle anzeigen:

sudo journalctl -u flowguard-api -f

7. Server-Betrieb überprüfen

Gesundheits-Endpunkt testen:

curl http://localhost:3000/health

Sie sollten eine Antwort wie diese sehen:

{"status":"ok","timestamp":"2024-12-09T10:30:45.123Z"}

8. WordPress-Plugin konfigurieren

1. Melden Sie sich in Ihrem WordPress-Admin-Panel an
2. Navigieren Sie zu Flowguard > Einstellungen
3. Klicken Sie auf den Ausführung-Tab
4. Wählen Sie Lokale API als Ausführungsmodus
5. Geben Sie den API-Verzeichnispfad ein: /var/www/flowguard-api
6. Geben Sie die Portnummer ein: 3000 (oder Ihren benutzerdefinierten Port)
7. Geben Sie den Host ein: localhost
8. Klicken Sie auf Anforderungen prüfen

Das System überprüft:

• Node.js ist installiert
• npm ist installiert
• API-Verzeichnis existiert
• package.json ist gültig
• Alle npm-Pakete sind installiert
• Playwright-Browser sind installiert
• Lokaler Server läuft

Wenn alle Anforderungen erfüllt sind, sehen Sie eine Erfolgsmeldung und können Flows lokal ausführen!

Fehlerbehebung

Server startet nicht

Fehler: Port 3000 is already in use

Lösung: Stoppen Sie entweder den anderen Prozess, der Port 3000 verwendet, oder ändern Sie den Port in Ihrer .env-Datei und den WordPress-Einstellungen.

# Prüfen, was Port 3000 verwendet
sudo lsof -i :3000

# Anderen Port verwenden
echo "PORT=3001" >> .env

Browser-Start schlägt fehl

Fehler: browserType.launch: Executable doesn't exist

Lösung: Playwright-Browser neu installieren:

cd /var/www/flowguard-api
npx playwright install --force
npx playwright install-deps

Berechtigungsfehler

Fehler: EACCES: permission denied

Lösung: Stellen Sie sicher, dass das API-Verzeichnis korrekte Berechtigungen hat:

sudo chown -R www-data:www-data /var/www/flowguard-api
sudo chmod -R 755 /var/www/flowguard-api

WordPress kann keine Verbindung zum Server herstellen

Fehler: Verbindung zum lokalen API-Server fehlgeschlagen

Lösungen:

1. Überprüfen Sie, ob der Server läuft:

   curl http://localhost:3000/health

2. Firewall-Einstellungen prüfen (Server sollte von localhost aus erreichbar sein)

3. Server-Protokolle überprüfen:

   # Bei Verwendung von PM2
   pm2 logs flowguard-api
   
   # Bei Verwendung von systemd
   sudo journalctl -u flowguard-api -n 50

Server stürzt während der Flow-Ausführung ab

Ursache: Unzureichender Speicher oder Ressourcen

Lösung: Speichergrenzen erhöhen und optimieren:

# Node.js-Speicherlimit erhöhen
node --max-old-space-size=4096 src/server.js

# Oder in PM2
pm2 start src/server.js --name flowguard-api --max-memory-restart 1G

Sicherheitsüberlegungen

Nur lokales Netzwerk

Standardmäßig bindet der API-Server nur an localhost, was bedeutet, dass er nur von derselben Maschine aus erreichbar ist. Dies ist die empfohlene Konfiguration.

DANGER

Setzen Sie den API-Server niemals ohne ordnungsgemäße Authentifizierung dem öffentlichen Internet aus!

Firewall-Konfiguration

Wenn Sie von einem anderen Server auf die API zugreifen müssen, verwenden Sie SSH-Tunneling anstatt Ports zu öffnen:

ssh -L 3000:localhost:3000 benutzer@ihr-server.de

Prozess-Isolation

Erwägen Sie, den API-Server unter einem dedizierten Benutzerkonto mit eingeschränkten Berechtigungen auszuführen:

sudo useradd -r -s /bin/false flowguard
sudo chown -R flowguard:flowguard /var/www/flowguard-api

Aktualisieren Sie Ihre systemd-Dienst- oder PM2-Konfiguration, um diesen Benutzer zu verwenden.

Performance-Optimierung

Browser-Wiederverwendung

Der API-Server verwendet Browser-Instanzen nach Möglichkeit wieder, um die Leistung zu verbessern. Browser-Kontexte werden für jede Flow-Ausführung neu erstellt.

Gleichzeitige Flows

Der Server kann mehrere Flow-Ausführungen gleichzeitig verarbeiten. Das Standardlimit basiert auf den verfügbaren Systemressourcen.

Ressourcen-Bereinigung

Fehlgeschlagene oder abgebrochene Flows bereinigen automatisch ihre Browser-Ressourcen. Der Server überwacht die Ressourcennutzung und startet Browser bei Bedarf neu.

Wartung

API aktualisieren

Beim Aktualisieren von Flowguard müssen Sie möglicherweise die API-Abhängigkeiten aktualisieren:

cd /var/www/flowguard-api
npm install
npx playwright install

Dann Server neu starten:

# Bei Verwendung von PM2
pm2 restart flowguard-api

# Bei Verwendung von systemd
sudo systemctl restart flowguard-api

Log-Rotation

Konfigurieren Sie Log-Rotation, um zu verhindern, dass Protokolle zu viel Speicherplatz verbrauchen:

# Für PM2
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7

Überwachung

Server-Gesundheit und Ressourcennutzung überwachen:

# Serverstatus prüfen
curl http://localhost:3000/health

# Mit PM2 überwachen
pm2 monit

# Systemressourcen prüfen
htop

Verwandte Dokumentation

• Einstellungen - Ausführungsmodus und andere Einstellungen konfigurieren
• Flows ausführen - Flow-Ausführung verstehen
• REST API - API-Referenz für Entwickler