perinco-CRM/docs/06-betrieb.md

06 Betrieb

Deployment

Gebaut wird lokal, auf den Server geht nur dist/ plus Backend-Quellen. Der Server hat wenig freien RAM und volles Swap - dort wird nicht gebaut.

flowchart LR
    L["Arbeitsplatz"] -->|"npm run build"| D["dist/"]
    D -->|pscp| S1["/var/www/perinco_CRM/dist"]
    L -->|pscp| S2["/var/www/perinco_CRM/server/src"]
    L -->|pscp| S3["server/package.json"]
    S3 -.->|"nur mit -Deps"| NI["npm install --omit=dev"]
    NI --> R["systemctl restart<br/>perinco-crm-backend"]
    S2 --> R
    R --> H["curl /api/health"]

npm run build
powershell -File deploy/deploy.ps1                 # dist + Backend
powershell -File deploy/deploy.ps1 -Deps           # zusaetzlich npm install
powershell -File deploy/deploy.ps1 -SkipBuild      # ohne neuen Build

Das Passwort kommt aus $env:PERINCO_CRM_SSH_PASSWORD oder per -Password.

deploy.ps1 lädt die systemd-Unit nicht mit hoch. Nach Änderungen an deploy/perinco-crm-backend.service von Hand kopieren und daemon-reload.

Dienste auf dem Server

Unit	Verzeichnis	Port	Anmerkung
perinco-crm-backend	/var/www/perinco_CRM/server	5006	MemoryMax=1536M
project-scanner-backend	/var/www/Projekt Scanner/backend	5005	alte App, läuft bis zur Ablosung

Der Verzeichnisname der alten App enthält ein Leerzeichen. In Skripten und in der .env immer in Anführungszeichen setzen - systemd liest .env als EnvironmentFile und trennt sonst am Leerzeichen.

MemoryMax=1536M statt der ursprünglichen 512M: ein Scan-Lauf startet Chromium als Kindprozess in derselben cgroup. Mit 512M würde der OOM-Killer das Backend mitten im Scrapen beenden.

Umgebungsvariablen

server/.env, Rechte 600. Vorlage: server/.env.example.

Variable	Bedeutung
PORT, HOST	5006, 127.0.0.1 - von außen nur über Apache
DB_*	Verbindung zu perinco_CRM
JWT_SECRET, JWT_EXPIRES_IN	Signatur der Sitzungen, Standard 12 h
ADMIN_*	wird beim ersten Start angelegt, nur wenn crm_users leer ist
SCANNER_DB_NAME	eigene Scanner-Datenbank, Standard perinco_scanner
SCANNER_ENCRYPTION_KEY	AES-Schlüssel für Portal-Passwörter
SCANNER_UPLOAD_DIR	CV-Verzeichnis, leer = <server>/uploads
SCANNER_SCHEDULER	Hintergrund-Scraper, Standard an, nur false schaltet ab
SCANNER_SCHEDULER_OFFSET	Minuten Versatz für den ersten Lauf, Standard 30
LEGACY_*	Quelle für npm run scanner:import
MS_TENANT_ID, MS_CLIENT_ID, MS_CLIENT_SECRET	App-only-Zugriff auf Microsoft Graph
MS_MAILBOX	abzugleichendes Postfach, Standard crm@perinco.de
MS_MAIL_FOLDER	Ordner, Standard inbox
MAIL_SYNC	Postfachabgleich, Standard an, nur false schaltet ab
MAIL_MAX_PAGES, MAIL_MAX_BODY_CHARS	Bremsen für Erstabgleich und Textgröße

Die Scanner-Datenbank wird beim Start automatisch angelegt (CREATE DATABASE IF NOT EXISTS), Tabellen kommen aus sequelize.sync(), Portale und Standardeinstellungen werden geseedet.

Fehlen die MS_*-Werte, startet das Backend normal und protokolliert [Mail] Zugangsdaten fehlen. Die Ansicht Mails und der Einstellungsreiter Postfach nennen die fehlende Variable beim Namen. Einrichtung in Entra und Exchange Online: 11 Postfachanbindung.

Die MS_*-Werte werden beim Start gelesen. Nach einer Änderung an der .env muss der Dienst neu starten, ein Speichern in der Oberfläche genügt nicht - dort liegen nur Intervall, Schalter und Zeitraum (crm_settings).

Playwright

playwright ist auf exakt 1.60.0 gepinnt - dieselbe Version wie die alte App. Deren Chromium-Build (chromium-1223) liegt in /root/.cache/ms-playwright, also fällt kein zweiter Browser-Download an. Ein ^ in der Version würde das aufgeben; die Begründung steht als comments-Feld in server/package.json.

Fehlt der Browser, funktioniert alles ausser Scan-Lauf und Verbindungstest:

cd /var/www/perinco_CRM/server && npx playwright install chromium

Erststart des Scanners

bash /var/www/perinco_CRM/deploy/scanner-setup.sh   # .env ergaenzen, Schluessel erzeugen
cd /var/www/perinco_CRM/server
npm run scanner:import -- --dry-run
npm run scanner:import -- --with-matches
systemctl restart perinco-crm-backend

Reihenfolge: Der Import schreibt search_interval aus der alten App in die Einstellungen. Der laufende Scheduler merkt die Änderung binnen einer Minute und plant sich neu - beim Rollout hat er direkt nach dem Import einen Scan gestartet, den der folgende Restart mitten im Scrapen beendet hat. Harmlos, aber vermeidbar: erst neu starten, dann importieren.

Störungssuche

Symptom	Blick darauf
Anmeldung schlägt fehl	journalctl -u perinco-crm-backend -n 50, JWT_SECRET gesetzt?
Scanner-Reiter leer, 500er	[Scanner] Datenbank nicht erreichbar im Journal
Kein Treffer trotz Scan	scanning_active, aktive Agenten mit CV, OpenAI-Key gesetzt
Portal expired	Cookies neu importieren (Cookie-Editor)
Target page ... has been closed	Dienst wurde mitten im Scrapen neu gestartet
Backend stirbt beim Scrapen	MemoryMax zu klein, systemctl show ... -p MemoryCurrent
Ton bleibt aus	Schwellenwert, Dashboard-Ansicht offen, einmal auf der Seite geklickt?
Keine Mails im Postfachreiter	journalctl -u perinco-crm-backend | grep '\[Mail\]', dann Verbindungstest in den Einstellungen
Mail-Abgleich meldet ErrorAccessDenied	Administratorzustimmung für Mail.Read fehlt, oder die ApplicationAccessPolicy erlaubt das Postfach nicht

Nützliche Abfragen:

systemctl status perinco-crm-backend
journalctl -u perinco-crm-backend -f
curl -s http://127.0.0.1:5006/api/health

set -a; . /var/www/perinco_CRM/server/.env; set +a
mysql -u"$DB_USER" -p"$DB_PASSWORD" "$SCANNER_DB_NAME" -e \
  "SELECT COUNT(*) FROM matches; SELECT key_name, value FROM settings"

# Zustand des Postfachabgleichs
mysql -u"$DB_USER" -p"$DB_PASSWORD" "$DB_NAME" -e \
  "SELECT mailbox, has_more, last_run_at, last_success_at, last_error FROM crm_mail_sync_state;
   SELECT COUNT(*) AS mails FROM crm_mail_messages;
   SELECT status, COUNT(*) FROM crm_mail_contact_candidates GROUP BY status"

Sicherung

Beide Datenbanken einzeln, dazu die CV-Dateien:

set -a; . /var/www/perinco_CRM/server/.env; set +a
mysqldump -u"$DB_USER" -p"$DB_PASSWORD" "$DB_NAME"         > crm_$(date +%F).sql
mysqldump -u"$DB_USER" -p"$DB_PASSWORD" "$SCANNER_DB_NAME" > scanner_$(date +%F).sql
tar czf uploads_$(date +%F).tar.gz -C /var/www/perinco_CRM/server uploads

Die .env gehört nicht ins Repository, aber in die Sicherung - ohne SCANNER_ENCRYPTION_KEY sind die Portal-Passwörter verloren. Genau das ist der alten App passiert.