Files

T

jhartworks 2c055fcb63 Merge branch 'main' of https://git.portal.se-cloud.de/Hannes/SE-LTD

2026-07-01 13:58:53 +02:00

19 KiB

Raw Blame History

# SE Local Trenddata

SE Local Trenddata ist eine webbasierte Trend-, Dashboard- und Quellenverwaltung fuer lokale Anlagen- und WAGO-Daten. Das Projekt besteht aus einem React-Frontend, einer Node.js/Express-API, MariaDB, Redis und einem Collector-Service fuer Protokollquellen wie Modbus TCP, OPC UA, BACnet IP und KNX IP.

Das Ziel ist, bestehende breite Trendtabellen wie isp01, isp02 usw. weiter nutzen zu koennen und zusaetzlich neue Quellen sauber ueber eine Weboberflaeche anzulegen, zu scannen, zu loggen und im Dashboard oder in der Trendansicht auszuwerten.

Inhaltsverzeichnis

Projektaufbau
Architektur
Services und Ports
Schnellstart mit Docker Compose
Lokale Entwicklung
Konfiguration
Login, Benutzer und Rollen
Frontend-Funktionen
API-Funktionen
Collector-Funktionen
Datenbank und Speicher
WAGO- oder SD-Karten-Betrieb
Backup und Restore
Deployment-Hinweise
Troubleshooting
Sicherheits-Checkliste

Projektaufbau

SeLTD/
├── .env.example
├── docker-compose.yml
├── docker-compose.wago.yml
├── docker/
│   └── redis/
│       └── redis.conf
├── api/
│   ├── Dockerfile
│   ├── package.json
│   └── src/
│       ├── index.js
│       ├── auth.js
│       ├── config.js
│       ├── db.js
│       ├── redis.js
│       └── lib/
│           ├── isp.js
│           └── store.js
├── collector/
│   ├── Dockerfile
│   ├── package.json
│   └── src/
│       └── index.js
└── web/
    ├── Dockerfile
    ├── package.json
    ├── vite.config.js
    ├── public/
    │   └── logo.png
    └── src/
        ├── App.jsx
        ├── api.js
        ├── main.jsx
        ├── styles.css
        └── components/
            ├── Gauge.jsx
            └── TrendChart.jsx

Hauptbereiche

Bereich	Aufgabe
`web/`	React/Vite-Frontend fuer Login, Dashboard, Trends, Admin-Bereich, Quellen, Rollen und Benutzer
`api/`	Express-API fuer Auth, Rollen, Aliase, Trendabfragen, Dashboard, SQL-Import und Benutzerverwaltung
`collector/`	HTTP-Service fuer Protokollquellen, Datenpunkte, Scans, Imports und zyklisches Logging
`mariadb`	Persistente Trenddaten und Benutzer-Tabelle
`redis`	Metadaten, Aliase, Rollen, Einheiten, Dashboards, Auswahlen und User-Praeferenzen
`dockhand`	Docker-Verwaltung ueber Weboberflaeche
`cadvisor`	Container-Metriken fuer Monitoring

Architektur

Browser
  │
  │ http://localhost:5173
  ▼
React/Vite Frontend (web)
  │
  ├── API-Aufrufe:       http://localhost:18080/api/...
  │       ▼
  │     Express API (api, intern Port 8080)
  │       ├── MariaDB: Benutzer, Trendtabellen, SQL-Daten
  │       └── Redis: Rollen, Einheiten, Aliase, Dashboard, Auswahlen
  │
  └── Collector-Aufrufe: http://localhost:18110/...
          ▼
        Collector-Service
          ├── sources.json unter /app/data
          ├── Modbus TCP / OPC UA / BACnet / KNX
          └── schreibt aktive Datenpunkte in MariaDB-Trendtabellen

Wichtig: Die API laeuft im Container intern auf Port 8080, wird aber nach aussen auf 18080 gemappt. Das Frontend muss deshalb im Browser auf http://localhost:18080/api zugreifen.

Services und Ports

Service	Container	Interner Port	Host-Port	Zweck
Web	`seltd-web`	5173	5173	React/Vite-Oberflaeche
API	`seltd-api`	8080	18080	REST-API
Collector	`seltd-collector`	18110	18110	Quellen, Datenpunkte, Scans, Polling
MariaDB	`seltd-mariadb`	3306	3306	Trend- und Benutzerdaten
Redis	`seltd-redis`	6379	6379	Metadaten und App-State
Dockhand	`dockhand`	3000	3000	Docker-Webverwaltung
cAdvisor	`cadvisor_ltd`	8080	9090	Container-Metriken

Schnellstart mit Docker Compose

Du solltest WSL installiert haben. Falls du das nicht hast:

 wsl --install Ubuntu

Dann kannst du Docker Desktop installieren: https://docs.docker.com/desktop/setup/install/windows-install/ Die Installation einfach durchklicken und wenn du gefragt wirst ob du Hyper-V oder WSL verwenden möchtest, wähle WSL.

1. Repository vorbereiten

Wenn du git auf deinem rechner installiert hast, dann öffne eine Powershell in dem Ordner, in dem du das LTD-System haben willst. (rechtsklick im Windowsexplorer ins leere --> "In Terminal öffnen")

git clone https://git.portal.se-cloud.de/Hannes/SE-LTD
cd ./SeLTD

Powershell nicht schließen, brauchst du gleich noch.

2. Stack bauen und starten

Falls du Powershell geschlossen hast: (rechtsklick im Windowsexplorer ins leere --> "In Terminal öffnen")

docker compose build --no-cache web api collector
docker compose up -d --force-recreate

Die lokalen Images werden jetzt gebaut und die Onlineimages werden heruntrergeladen. Wenn das fertig ist müssen alle 7 Container gestartet sein.

Im Nachgang kannst du dies in der Powershell mit...

docker ps -a

...überprüfen

3. Aufrufen

Nun stehen dir mehrere Tools zur Verfügung: <<<<<<< HEAD

Frontend | http://localhost:5173 --> Das ist die normale Weboberfläche zum anschauen, editieren und anpassen von Trends.

API Healthcheck | http://localhost:18080/api/health --> hier kannst du schauen ob die API läuft

Collector Healthcheck | http://localhost:18110/health --> hier kannst du schauen ob der Collector läuft, was nur wichtig ist, wenn du Datenpunkte per OPC,KNX, Modbus oder Bacnet angebunden hast.

Dockhand | http://localhost:3000 --> Dockhand ist Container verwaltungstool, dass es dir ermöglicht, auch grafisch den Zustand deiner Container und deines Stacks zu sehen. Der Vorteil hier, im Gegensatz zur normalen Docker Desktopoberfläche: Du kannst es auf jedem beliebigen anderen Rechner, der auf dein Netzwerk zugriff hat, öffnen.

cAdvisor | `http://localhost:9090` --> Cadvisor stellt alle Containerdaten für Monitoring und Analyticprogramme bereit. So kann bei einer größeren Anlage, das Dockersystem mitr Prometheus oder ähnlichem überwacht werden. Cadvisor stellt di Daten per html bereit, kannst du dir gern anschauen, ist aber ziemlich unübersichtlich.

| Frontend | http://localhost:5173 | --> Das ist die normale Weboberfläche zum anschauen, editieren und anpassen von Trends.

c06fe1fd4d

| API Healthcheck | http://localhost:18080/api/health | --> hier kannst du schauen ob die API läuft

| Collector Healthcheck | http://localhost:18110/health | --> hier kannst du schauen ob der Collector läuft, was nur wichtig ist, wenn du Datenpunkte per OPC,KNX, Modbus oder Bacnet angebunden hast.

| Dockhand | http://localhost:3000 | --> Dockhand ist Container verwaltungstool, dass es dir ermöglicht, auch grafisch den Zustand deiner Container und deines Stacks zu sehen. Der Vorteil hier, im Gegensatz zur normalen Docker Desktopoberfläche: Du kannst es auf jedem beliebigen anderen Rechner, der auf dein Netzwerk zugriff hat, öffnen.

| cAdvisor | http://localhost:9090 | --> Cadvisor stellt alle Containerdaten für Monitoring und Analyticprogramme bereit. So kann bei einer größeren Anlage, das Dockersystem mitr Prometheus oder ähnlichem überwacht werden. Cadvisor stellt di Daten per html bereit, kannst du dir gern anschauen, ist aber ziemlich unübersichtlich.

Username: admin
Passwort: SE3112

Konfiguration

Die wichtigsten Variablen liegen in .env.

Variable	Beispiel	Beschreibung
`JWT_SECRET`	`change-me`	Signatur fuer Login-Tokens. In Produktion unbedingt aendern.
`ADMIN_USERNAME`	`admin`	Initialer Admin-Username
`ADMIN_EMAIL`	`admin@example.com`	Initiale Admin-E-Mail
`ADMIN_PASSWORD`	`ChangeMe123!`	Initiales Admin-Passwort
`ADMIN_NAME`	`System Admin`	Anzeigename des Admins
`MARIADB_ROOT_PASSWORD`	`SE3112`	MariaDB-Root-Passwort
`DB_PASSWORD_FALLBACK`	`root`	Fallback fuer alte Entwicklungsvolumes
`CORS_ORIGIN`	`*`	Erlaubter Browser-Ursprung fuer API-Aufrufe
`VITE_API_PORT`	`18080`	API-Port, den das Frontend im Browser nutzt
`POLL_TICK_MS`	`1000`	Collector-Tick fuer Polling-Pruefung

Die API legt beim Start automatisch einen Admin-Benutzer an oder aktualisiert den vorhandenen Admin.

Systemrollen

Rolle	Rechte
`viewer`	Dashboard anzeigen, Trendansicht anzeigen
`technician`	Dashboard, Trends, Aliase, Quellen, Debug
`admin`	Alle Rechte inkl. Benutzer- und Rollenverwaltung

Rechtekatalog

Recht	Bedeutung
`view_dashboard`	Dashboard anzeigen und speichern
`view_trends`	Trends anzeigen, Auswahlen nutzen
`edit_aliases`	Aliase und Einheiten bearbeiten
`manage_sources`	Quellen und Datenpunkte verwalten
`manage_users`	Benutzer anlegen und bearbeiten
`manage_roles`	Rollen und Rechte verwalten
`view_debug`	Collector-Debug sehen

Benutzer, Rollen und Passwoerter werden ueber den Admin-Bereich verwaltet.

Frontend-Funktionen

Username-basierter Login
JWT-Token wird im Browser gespeichert
Passwortwechsel ueber Einstellungen
Rollenbasierte Navigation

Dashboard

Widgets aus aktueller Auswahl oder gespeicherter Auswahl
Widget-Typen:
- Graph
- Zahl
- Zeigermanometer
Dashboard wird pro Benutzer gespeichert

Trendansicht

Datenpunkte aus mehreren Trendtabellen kombinierbar
Auswahl speicherbar und optional fuer andere Benutzer freigebbar
Zeitraeume als Presets von 5 Minuten bis 30 Tage
Eigener Start-/Endzeitraum moeglich
Aktuelle Werte werden separat angezeigt
Fokusmodus fuer den Graphen

Trend-Export

Der Trendgraph kann exportiert werden als:

CSV
XLSX
PNG
JPG
SVG
PDF

Admin: Aliase

Anzeigename und Beschreibung pro Trendtabelle
Alias, Einheit, Faktor, Typ, Min/Max und Farbe pro Wert
CSV-Import und CSV-Export
Encoding-/Grad-Celsius-Bereinigung

Admin: Einheiten

Systemeinheiten wie °C, %, K, V, A, Pa
Eigene Einheiten wie bar, m³/h, Hz usw.
Einheitenauswahl bei Aliasen und Datenpunkten

Admin: Quellen

Protokollquellen anlegen und bearbeiten
Unterstuetzte Protokolle in der UI:
- Modbus TCP
- OPC UA
- BACnet IP
- KNX IP
Poll-Intervall und Schreibmodus konfigurierbar
Scan-Ergebnisse und importierte Punkte koennen ins Logging uebernommen werden
Manuelle Datenpunkte koennen erstellt und bearbeitet werden

API-Funktionen

Die API laeuft unter:

http://localhost:18080/api

Authentifizierung

Methode	Pfad	Beschreibung
`POST`	`/api/auth/login`	Login mit Username/Passwort
`GET`	`/api/auth/me`	Aktuellen Benutzer lesen
`POST`	`/api/auth/change-password`	Passwort aendern

Trends und ISPs

Methode	Pfad	Beschreibung
`GET`	`/api/isps`	Verfuegbare Trendtabellen lesen
`GET`	`/api/isps/:isp/aliases`	Alias-Metadaten lesen
`PUT`	`/api/isps/:isp/aliases`	Alias-Metadaten speichern
`POST`	`/api/trend-tables`	Neue Trendtabelle anlegen
`POST`	`/api/trends/query`	Trenddaten abfragen
`POST`	`/api/points/latest`	Letzte Werte lesen

Einheiten

Methode	Pfad	Beschreibung
`GET`	`/api/units`	Einheiten lesen
`POST`	`/api/units`	Einheit anlegen
`PATCH`	`/api/units/:symbol`	Einheit bearbeiten

Benutzer und Rollen

Methode	Pfad	Beschreibung
`GET`	`/api/users`	Benutzerliste
`POST`	`/api/users`	Benutzer anlegen
`PATCH`	`/api/users/:id`	Benutzer bearbeiten
`GET`	`/api/roles`	Rollenliste inkl. Rechtekatalog
`POST`	`/api/roles`	Rolle anlegen
`PATCH`	`/api/roles/:name`	Rolle bearbeiten

Auswahlen und Dashboard

Methode	Pfad	Beschreibung
`GET`	`/api/selections`	Gespeicherte Auswahlen lesen
`POST`	`/api/selections`	Auswahl speichern
`PUT`	`/api/selections/:selectionId`	Auswahl aktualisieren
`DELETE`	`/api/selections/:selectionId`	Auswahl loeschen
`GET`	`/api/dashboard`	Dashboard laden
`PUT`	`/api/dashboard`	Dashboard speichern
`POST`	`/api/dashboard/data`	Widget-Daten laden
`GET`	`/api/preferences`	Benutzerpraeferenzen laden
`PUT`	`/api/preferences`	Benutzerpraeferenzen speichern

Collector-Funktionen

Der Collector laeuft unter:

http://localhost:18110

Er verwaltet Quellen und Datenpunkte in einer JSON-Datei (/app/data/sources.json) und schreibt aktive Punkte zyklisch in MariaDB.

Collector-Endpunkte

Methode	Pfad	Beschreibung
`GET`	`/health`	Healthcheck
`GET`	`/capabilities`	Unterstuetzte Protokolle/Funktionen
`GET`	`/sources`	Quellen lesen
`POST`	`/sources`	Quelle anlegen
`PUT`	`/sources/:id`	Quelle bearbeiten
`DELETE`	`/sources/:id`	Quelle loeschen
`GET`	`/datapoints`	Datenpunkte lesen
`POST`	`/datapoints/manual`	Datenpunkt manuell anlegen
`PATCH`	`/datapoints/:id`	Datenpunkt bearbeiten, aktivieren, deaktivieren
`POST`	`/datapoints/:id/read`	Live-Wert lesen
`POST`	`/imports/modbus-csv`	Modbus-CSV importieren
`POST`	`/imports/knx-xml`	KNX-XML importieren
`POST`	`/scan/opcua`	OPC-UA-Scan starten
`POST`	`/scan/bacnet`	BACnet-Scan starten
`GET`	`/debug`	Debugdaten lesen

Schreibmodus

Modus	Bedeutung
`interval`	Jeder Poll wird geschrieben
`cov`	Nur bei Wertaenderung wird geschrieben

Aktive vs. inaktive Datenpunkte

Inaktive Datenpunkte sind gefunden/importiert, werden aber nicht geloggt.
Aktive Datenpunkte werden vom Collector gepollt und in die zugehoerige Trendtabelle geschrieben.
In der Weboberflaeche entspricht das der Trennung zwischen „Gefunden / importiert“ und „Wird geloggt“.

Datenbank und Speicher

MariaDB

MariaDB speichert:

app_users
bestehende isp... Tabellen
neue trend_... Tabellen
Registry-Tabellen fuer Quellen und Datenpunkte, falls vom Collector/API genutzt

Die API kann bestehende breite Tabellen mit Wert1, Wert2, ... lesen. Neue lokale Trendtabellen koennen bis zu 2000 Werte unterstuetzen.

Redis

Redis speichert:

Rollen
Einheiten
Aliase und Tabellen-Metadaten
Auswahlen
Dashboard-Konfiguration
Benutzerpraeferenzen

Redis sollte deshalb ebenfalls gebackupt werden, nicht nur MariaDB.

MariaDB Backup

docker exec seltd-mariadb mariadb-dump -uroot -pSE3112 --all-databases > seltd-mariadb-backup.sql

Restore:

type .\seltd-mariadb-backup.sql | docker exec -i seltd-mariadb mariadb -uroot -pSE3112

Redis Backup

Redis nutzt ein Docker-Volume. Fuer ein einfaches Dateibackup:

docker run --rm -v seltd_redis_data:/data -v ${PWD}:/backup alpine tar czf /backup/seltd-redis-backup.tar.gz -C /data .

Collector Backup

docker run --rm -v seltd_collector_data:/data -v ${PWD}:/backup alpine tar czf /backup/seltd-collector-backup.tar.gz -C /data .

Browsercache

Bei alten JavaScript-Fehlern nach einem Fix:

Strg + F5

Nginx Proxy Manager

Wenn das Frontend hinter Nginx laeuft, muessen die API- und Collector-URLs sauber erreichbar sein. Entweder:

Frontend, API und Collector unter eigenen Subdomains veroeffentlichen, oder
Nginx so konfigurieren, dass /api zur API und /collector zum Collector weitergeleitet wird.

In diesem Fall kann VITE_API_URL statt VITE_API_PORT gesetzt werden:

VITE_API_URL=https://trend-api.example.local/api
VITE_COLLECTOR_URL=https://trend-collector.example.local

Troubleshooting

Fehler: `NetworkError when attempting to fetch resource`

Ursachen:

API-Container laeuft nicht
falscher Port im Frontend
CORS nicht korrekt
Browser ruft alte Version auf

Pruefen:

docker ps
curl http://localhost:18080/api/health

Wenn Frontend lokal auf localhost:5173 laeuft:

CORS_ORIGIN=*

Danach API neu starten:

docker compose restart api

Fehler: Browser zeigt alte React-Fehler nach Fix

Sehr wahrscheinlich wurde das Docker-Image nicht neu gebaut.

docker compose down
docker compose build --no-cache web api collector
docker compose up -d

Danach im Browser Strg + F5.

Logs ansehen:

docker logs seltd-api --tail 100
docker logs seltd-mariadb --tail 100

Pruefen, ob MariaDB healthy ist:

docker ps

Redis-Probleme

docker exec seltd-redis redis-cli ping

Erwartet:

PONG

Nuetzliche Befehle

Alle Container anzeigen

docker compose ps

Logs live verfolgen

docker compose logs -f

Nur API:

docker logs seltd-api -f

Nur Frontend:

docker logs seltd-web -f

Nur Collector:

docker logs seltd-collector -f

Komplett neu starten

docker compose restart

Komplett neu bauen

docker compose down
docker compose build --no-cache
docker compose up -d

Volumes loeschen

Achtung: Dadurch gehen Daten verloren.

docker compose down -v

Sicherheits-Checkliste

Vor produktiver Nutzung:

JWT_SECRET auf langen zufaelligen Wert setzen
Admin-Passwort aendern
MariaDB-Root-Passwort aendern
MariaDB-Port 3306 nicht ungeschuetzt ins Internet veroeffentlichen
Redis-Port 6379 nicht ungeschuetzt ins Internet veroeffentlichen
Dockhand absichern oder nur intern bereitstellen
Backups fuer MariaDB, Redis und Collector-Daten einrichten
Reverse Proxy mit HTTPS verwenden

Bekannte Hinweise

Leere Trendtabellen erscheinen nicht in der Trendauswahl, aber im Admin-Bereich.
Bestehende breite isp... Tabellen bleiben kompatibel.
Neue lokale Tabellen koennen als trend_... Tabellen angelegt werden.
Der Collector speichert seine Quellen/Datenpunkte aktuell dateibasiert in sources.json.
Fuer vollstaendige Protokollintegration muessen je nach Feldbus noch Details wie Adressierung, Datentyp, Byteorder und Authentifizierung sauber projektspezifisch gepflegt werden.

19 KiB Raw Blame History