KC@FlessingLabs – Kundencenter

Selbst gehostetes Kundencenter für Hosting-Anbieter, Agenturen und Software-Hersteller: Kunden, Produkte, Bestellungen, Verträge, Rechnungen, Support-Tickets und Lizenzen in einer Oberfläche – mit Anbindung an KeyHelp und an das FlessingLabs-Lizenzsystem. Modularer Monolith in TypeScript (Fastify, Next.js, MariaDB).

Prozess	Pfad	Port (nur 127.0.0.1)	Aufgabe
kc-api	apps/api	4100	Fastify-API (/v1/*), Module, Rechte, Audit
kc-worker	apps/worker	4102 (Health)	Persistente Aufträge, Discord-Bot, E-Mail-Posteingang
kc-web	apps/web	4101	Next.js-Oberfläche, leitet /api/* an die API weiter

Funktionen

• Konten und Sicherheit: Login mit Passwort + TOTP, Wiederherstellungscodes, Sitzungsverwaltung, Einladungen, Rollen für Personal und Kunden, Audit-Protokoll mit Hash-Kette.
• Kunden: Privat- und Geschäftskunden, Rechnungsanschrift, Übernahme aus KeyHelp, Kundenansicht („Als Kunde ansehen“).
• Produkte, Bestellungen, Verträge: versionierte Produkte, Bestellungen mit Freigabe und unveränderlichem Preis-Snapshot, Laufzeiten, Kündigung, automatische Verlängerung mit Erinnerung (docs/produkte-bestellungen-vertraege.md).
• Bereitstellung über Connectoren: KeyHelp (Hosting-Konten, Domains, Postfächer, Datenbanken) und Lizenzsystem (docs/connector-vertrag.md, docs/connector-keyhelp.md).
• Lizenzverwaltung: Übersicht, Vergabe mit Vertrag oder ohne Berechnung (Lizenz, Test, Add-on), Geräte freigeben, Sperren/Verlängern/Widerrufen, Limits und Funktionsumfang; Kunden sehen ihre Lizenzen und geben eigene Geräte frei.
• Rechnungen: Entwurf → Ausstellen (unveränderlich) → Bezahlt/Storno, PDF, DATEV-Export (docs/rechnungen.md).
• Support: Tickets je Kunde mit internen Notizen und Anhängen, E-Mail-Posteingang (IMAP), Discord-Bot mit eigenem Kanal je Ticket.
• Betrieb: verschlüsselte tägliche Backups mit automatischem Wiederherstellungstest (docs/betrieb-backup-restore.md).

Testmodus und Lizenz

Ohne Lizenzschlüssel läuft das Kundencenter im Testmodus:

	Testmodus	Mit Lizenz
Personal-Konten	1	laut Lizenz
Kunden	2	laut Lizenz
Discord-Bot, E-Mail-Posteingang (IMAP), DATEV-Export, Backups auf externe Ziele	–	✓

Alles andere ist im Testmodus voll nutzbar. Eine Lizenz gibt es bei FlessingLabs (https://flessinglabs.com); den Schlüssel unter Einstellungen → Lizenz eintragen, er wird regelmäßig bei licensing.flessinglabs.com geprüft (7 Tage offline möglich). Läuft eine Lizenz ab, gilt wieder der Testmodus – bestehende Daten bleiben vollständig erhalten und nutzbar, nur Neuanlagen über die Grenzen hinaus und die Zusatzfunktionen pausieren. Nutzungsbedingungen: LICENSE.md.

Installation (Debian/Ubuntu)

Voraussetzungen: Node.js ≥ 22, pnpm 10, MariaDB ≥ 10.6, ein Reverse-Proxy mit HTTPS (Apache, nginx, Caddy …), für Backups gpg und rclone.

# 1. Benutzer und Code
useradd --system --home-dir /var/lib/kundencenter --shell /usr/sbin/nologin kundencenter
git clone https://forge.flessinghome.de/flessinglabs/kundencenter.git /srv/kundencenter
chown -R kundencenter: /srv/kundencenter
cd /srv/kundencenter && sudo -u kundencenter pnpm install --frozen-lockfile && sudo -u kundencenter pnpm build

# 2. Datenbank (Zeichensatz utf8mb4 / utf8mb4_unicode_ci ist wichtig)
mysql -e "CREATE DATABASE kundencenter CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
          CREATE USER 'kundencenter'@'localhost' IDENTIFIED BY '<passwort>';
          GRANT ALL ON kundencenter.* TO 'kundencenter'@'localhost';
          GRANT ALL ON kundencenter_restoretest.* TO 'kundencenter'@'localhost';"

# 3. Konfiguration (Vorlage: .env.example; Kommentare nie hinter einen Wert schreiben)
install -d -m 700 /etc/kundencenter
install -d -o kundencenter -m 755 /var/lib/kundencenter/requests
install -d -o kundencenter -m 750 /var/lib/kundencenter/ticket-attachments
install -d -m 700 /var/backups/kundencenter
#    /etc/kundencenter/db.env und /etc/kundencenter/app.env anlegen, chmod 600

# 4. Schema und erster Superadmin (Passwort wird abgefragt)
cd /srv/kundencenter && pnpm migrate
pnpm cli create-superadmin --email=admin@example.de --name="Vorname Nachname"

# 5. Dienste
cp ops/systemd/kc-* /etc/systemd/system/ && systemctl daemon-reload
systemctl enable --now kc-api kc-web kc-worker kc-backup.timer kc-restore-test.timer kc-backup-request.path

Reverse-Proxy: alles auf http://127.0.0.1:4101 weiterleiten und X-Forwarded-Proto: https setzen. Beispiel Apache:

ProxyPass / http://127.0.0.1:4101/
ProxyPassReverse / http://127.0.0.1:4101/
RequestHeader set X-Forwarded-Proto "https"

Danach anmelden, 2FA einrichten, unter Einstellungen Firma, E-Mail (SMTP) und Backup-Passwort hinterlegen.

Update

cd /srv/kundencenter && systemctl start kc-backup            # vorher sichern
sudo -u kundencenter git pull && sudo -u kundencenter pnpm install --frozen-lockfile && sudo -u kundencenter pnpm build
pnpm migrate && systemctl restart kc-api kc-web kc-worker

Betrieb

systemctl status kc-api kc-worker kc-web        # Dienste (Autostart, Restart=always)
journalctl -u kc-api -f                          # Logs
pnpm cli reset-password --email=…                # Passwort zurücksetzen

Health: GET :4100/v1/health, GET :4100/v1/ready, GET :4102/health. Geheimnisse liegen nie im Repo, sondern in /etc/kundencenter/*.env (chmod 600). KC_BASE_URL muss exakt der Browser-Adresse entsprechen.

Discord-Bot

Unter Einstellungen → Discord Bot-Token, Server-ID und Kanäle eintragen (Anleitung auf der Seite). Mit einer Ticket-Kategorie bekommt jedes offene Ticket einen eigenen Kanal, sichtbar nur für die Support-Rollen und den Kunden. Kunden und Personal verknüpfen ihr Discord-Konto unter „Mein Konto“. Erfordert eine Lizenz.

Modularität

API-Module liegen in apps/api/src/modules/<name> und implementieren KcModule (core/module.ts). Sie werden in modules/index.ts eingetragen, registrieren Routen und Rechte und sprechen nur über core/* und Jobs miteinander. Neue Anbieter kommen als Connector unter packages/connector-* hinzu (docs/connector-vertrag.md).

Tests

cd apps/api && pnpm test – Integrationstests gegen eine separate Datenbank kundencenter_test (wird bei jedem Lauf neu erstellt). Abgedeckt: Login, Sperre, CSRF, 2FA-Pflicht, Sitzungen, Kundenanlage, Mandantentrennung, Rechte, Audit-Kette.