Technische Dokumentation Thingsboard Frost Adapter

Die technische Dokumentation gliedert sich in neun weitere Seiten. Sie stehen in Leserichtung: die ersten fünf beschreiben den Adapter, die letzten beiden richten sich an andere Leser.

Diese Seite beantwortet die Fragen, die sich beim ersten Öffnen des Repositories stellen: Was liegt hier, wie bekomme ich es zum Laufen, wie lasse ich die Tests laufen, und welche Einstellung gehört in eine Umgebungsvariable statt in die Datenbank. Der innere Aufbau des Adapters steht in Architektur im Detail, die Abläufe des Betriebs in Betriebsanleitungen.

Unterhalb von src/ liegen damit zwei Pakete nebeneinander: der Adapter und das Frontend. Sie teilen sich das Poetry‑Projekt und eine Abhängigkeitsliste, laufen aber als zwei getrennte Prozesse und sprechen ausschließlich über die REST‑API des Adapters miteinander.

Die Umgebung ist auf zwei Compose‑Dateien verteilt, die denselben Projektnamen (name: frost_allinone) und damit dasselbe Netz benutzen:

Für die tägliche Arbeit reicht die erste Datei — Adapter und Frontend laufen dann lokal aus dem Poetry‑Environment gegen die Container:

Abhängigkeiten installieren — das installiert auch das Projekt selbst und nicht nur seine Abhängigkeiten, was den src‑Layout‑Import überhaupt erst auflöst:

Backend:

Frontend — setzt ein laufendes Backend voraus:

Beim Start legt bootstrap() das Schema an und füllt die Stammdaten. Es spricht dabei kein externes System an und prüft insbesondere keinen Mandanten (Architekturüberblick).

Die oberste Achse von tests/ ist die Abhängigkeit, nicht der Umfang.

Die zentrale Unterscheidung: Eine Umgebungsvariable ist ein Wert, den der Prozess nur einmal halten kann. Alles, was sich je Mandant unterscheidet — die FROST‑Server‑URL, deren Keycloak‑Client, die ThingsBoard‑Zugangsdaten — steht in der Tabelle tenant und nicht in der Konfiguration. Die ThingsBoard‑Edition ist genau deshalb Konfiguration: Sie ist eine Eigenschaft der einen Installation hinter THINGSBOARD_URL, nicht der einzelnen Mandantenzeile.

Der Keycloak‑Zugang ist die Ausnahme, die die Regel bestätigt: Es gibt einen globalen Adapter‑Benutzer, dem die Client‑Rollen des FROST‑Clients jedes Mandanten zugewiesen sind. Deshalb sind Realm, Benutzername und Passwort deployment‑weit, und nur keycloak_client_id ist mandantenspezifisch.

Der Dockerfile ist mehrstufig und endet in drei Zielen, die sich eine gemeinsame runtime‑Stufe teilen:

Die CI baut beide getrennt (build_and_publish_backend_docker_image, build_and_publish_frontend_docker_image) und veröffentlicht anschließend diese Dokumentation als GitLab Pages.

src/thingsboard_frost_adapter/ ist in vier Schichten gegliedert. Der Pfad eines Moduls sagt, was es tut, bevor man die Datei öffnet:

Importe zeigen ausschließlich nach unten: routers/ → services/ → repositories/db/, repositories/external/ und clients/; dazu repositories/external/ → clients/. Unterhalb von services/ importiert nichts eine Schicht über sich, und ein Repository importiert kein anderes Repository. db/, redis/, model/, exceptions/, configuration/ und bootstrap/ sind keine Schichten, sondern Querschnittspakete und dürfen von überall importiert werden.

Die Regel wird ausschließlich in Prosa durchgesetzt – es gibt kein Lint‑ oder CI‑Werkzeug dafür. Die Begründungen, die Verträge zwischen den Schichten und die beiden benannten Ausnahmen stehen in Architektur im Detail.

Änderungen oder das Löschen von Geräten bzw. Standort‑Assets in ThingsBoard werden über die Endpunkte POST /ingest/{slug}/device/update, POST /ingest/{slug}/device/delete und POST /ingest/{slug}/asset/update entsprechend in FROST nachgezogen.

Ob die Abhängigkeiten eines Mandanten funktionieren, wird nicht persistiert, sondern auf Anfrage in Echtzeit überprüft.

Dieser Abschnitt beschreibt den inneren Aufbau von src/thingsboard_frost_adapter/: die vier Schichten, die Regel, in welche Richtung Importe zeigen, und die Verträge, die die Schichten einander geben. Der Architekturüberblick beschreibt die Komponenten um den Adapter herum; hier geht es um seinen Inhalt.

Der Zugehörigkeitstest, wenn bei einem neuen Modul unklar ist, wohin es gehört:

db/, redis/, model/, exceptions/, configuration/ und bootstrap/ sind keine Schichten, sondern Querschnittspakete. Sie dürfen von überall importiert werden.

Importe zeigen ausschließlich nach unten.

bootstrap/ ist kein Router und importiert repositories/db/ direkt.

Die Module, deren Zuschnitt sich nicht aus dem Namen allein ergibt:

Jedes Modul, das ein Subjekt besitzt, trägt seine Schicht als Suffix — _client, _repository, _service, _router —, auch wenn das Paket sie bereits nennt. Dieselben Substantive (tenant, frost, observed_property) wiederholen sich über alle vier Schichten; ohne Suffix hätte man drei Editor-Tabs namens tenant.py.

Ein Modul ohne eigenes Subjekt trägt kein Suffix. Davon gibt es genau zwei: crud.py, benannt nach einem Mechanismus, und cross_tenant.py, benannt nach einer Beziehung. Das fehlende Suffix sagt: Das ist ein Helfer, kein Einstiegspunkt.

Bindung: an einen Mandanten gebunden → Objekt, konstruiert aus TenantClients. Global → Modul von Funktionen. Postgres ist eine Engine für den ganzen Prozess, also ist repositories/db/ ein Modul von Funktionen; FROST und ThingsBoard gibt es je Mandant, also ist repositories/external/ objektbasiert. Innerhalb von services/ und repositories/db/ gibt es keine Klassen und keine Modul-Singletons.

Zu jeder mandantengebundenen Klasse steht eine Fabrik <name>_for(tenant) neben ihr. Es gibt drei:

„Nur routers/ spricht HTTP" gilt hier nicht: HTTPException ist in tenant_ingest_router.reported() tragendes Transportmittel — fangen, .status_code lesen, mit angereichertem Detail erneut werfen —, und from fastapi import HTTPException zeigt seitwärts auf das Framework, nicht nach oben.

Vier Stellen brechen eine der obigen Regeln. Alle vier sind bewusst und abschließend:

Die oberste Achse von tests/ ist die Abhängigkeit (unit / integration), das Schichtschema ist der Baum darunter.

Die Spiegelregel, die der Docstring in tests/unit/init.py hält:

repositories/ erscheint in keinem der beiden Bäume: Nichts ruft ein Repository als seinen Einstiegspunkt auf. Die Repository-Primitive sind durch den Service abgedeckt.

tests/integration/conftest.py gibt je Mandant ein Fixture pro Subjekt heraus, statt eines Bündels, das alle Handles auf einmal trägt:

Drei prüfbare Formen dienen als Leitfaden für das Code-Review — das, worauf man beim Lesen eines Diffs achtet:

Alle drei binden src/ und nicht tests/. Das ist Absicht: Tests lesen FROST bewusst roh, damit sie einen Schreibvorgang unabhängig von dem Code prüfen können, der ihn ausgelöst hat. Ein Test, der dieselbe Abstraktion benutzt wie der Code unter Test, prüft sie nicht.

src/frontend/ ist die Verwaltungsoberfläche für die Stammdaten und die Mandanten‑Registry. Sie ist eine eigenständige Anwendung neben dem Adapter: eigener Prozess, eigener Container, eigener Port (8501), eigene Konfigurationsdatei. Sie greift nie auf die Datenbank zu, sondern ausschließlich auf die REST‑API des Adapters.

Was die Oberfläche tut, beschreibt die Nutzerdokumentation — Zuordnungen pflegen und Mandanten verwalten. Hier steht, wie sie gebaut ist.

Die Schichtung ist flach und hat nur eine Regel:

Keine Seite setzt einen HTTP‑Aufruf ab. requests kommt ausschließlich in api/frost_adapter_api_service.py vor; eine Seite kennt nur benannte Funktionen wie get_all_uoms() oder sync_observed_properties(id).

main.py ist der Einstiegspunkt und tut zwei Dinge. Ohne Anmeldung zeigt es ausschließlich eine Login‑Seite und ruft st.login(); die Anmeldung selbst läuft über den OIDC‑Block [auth] in .streamlit/secrets.toml gegen Keycloak. Nach der Anmeldung baut es die Navigation aus fünf st.Page‑Objekten und stellt einen Logout‑Knopf in die Seitenleiste.

Die Reihenfolge in der Navigation ist gesetzt: Tenants steht vorn, danach die vier Stammdatentabellen.

Vier der fünf Seiten sind dieselbe Seite mit anderen Spalten: ein st.data_editor über einen DataFrame, darüber ein Save‑Knopf. Beim Speichern liest submit() die drei Listen, die Streamlit im Session State führt, und übersetzt jede in einen API‑Aufruf:

api/frost_adapter_api_service.py kennt genau zwei Werte, und die Unterscheidung ist inhaltlich:

Die zweite Gruppe braucht das längere Limit, weil eine Seite, die vorher aufgibt, eine funktionierende Prüfung oder einen bereits committeten Schreibvorgang als Fehlschlag meldet.

Die meisten Funktionen geben einen DataFrame zurück, und ein leerer DataFrame ist zugleich das, womit ein fehlgeschlagener Aufruf antwortet — für eine Tabelle heißt beides „nichts anzuzeigen“.

Die Mandanten‑Schreibvorgänge sind die Ausnahme und lesen rohes JSON. create_tenant und update_tenant antworten mit dem verschachtelten {tenant, sync}, und die Seite muss den Bericht daraus lesen. Ein DataFrame könnte hier den entscheidenden Unterschied nicht ausdrücken: Schreibvorgang fehlgeschlagen (None) ist etwas anderes als Mandant angelegt, Replikation nicht durchgelaufen (sync: null).

unreached_tenants.py enthält die eine Warnung, die jede Stammdatenseite nach einem Speichern zeigt, wenn failed_tenants gefüllt ist. Der Schreibvorgang hat Postgres erreicht — und Postgres ist kanonisch —, aber nicht den FROST jedes Mandanten. Das ist eine Verzögerung und keine verlorene Änderung, deshalb eine Warnung mit einer Handlungsanweisung statt eines Fehlers.

Der Wiederholungsweg ist der einzige Grund, warum der Text ein Parameter ist:

Sie folgt demselben Tabellenmuster, hat aber drei Eigenheiten:

Im Session State stehen zwei Dinge, und beide halten bewusst nur das Handlungsbedürftige: Die Prüfergebnisse pro Slug, und aus einem Abgleichbericht ausschließlich die Liste unmanaged_in_use. Ein sauberer Abgleich ist ein Toast und hinterlässt nichts — was im Zustand steht, bedeutet damit „braucht Aufmerksamkeit“ und nicht „das ist zuletzt passiert“.

Das Frontend liest .streamlit/secrets.toml und nicht .env. Vorlage ist .streamlit/secrets-example.toml; keine der beiden echten Dateien ist eingecheckt.

Im Compose‑Betrieb wird die Container‑Fassung als Datei eingehängt:

Der Adapter hält eine eigene PostgreSQL‑Datenbank mit sechs Tabellen. Sie enthält keine Messwerte — die stehen ausschließlich im FROST‑Server jedes Mandanten. Was hier liegt, ist die Mandanten‑Registry und die Stammdaten, die eine ThingsBoard‑Telemetrie in einen SensorThings‑Begriff übersetzen.

Diese Seite beschreibt die Tabellen und ihre Beziehungen. Welche Regeln beim Schreiben und Löschen gelten, steht in Geschäftsregeln; wie diese Zeilen auf SensorThings‑Entitäten abgebildet werden, in Datenmodell. Alle Modelle stehen in model/sql/models.py; das Schema wird beim Start von bootstrap() angelegt, es gibt keine Migrationswerkzeuge.

Zwei Gruppen: tenant und tenantobservedproperty bilden die Registry, die übrigen vier die mandantenübergreifenden Stammdaten. Die einzige Verbindung zwischen beiden Gruppen ist tenantobservedproperty — die Tabelle, die festhält, welche FROST‑Entität in welchem Mandanten die Kopie einer ObservedProperty ist.

Ein Repository gibt ein vollständig geladenes Objekt zurück, weil die Zeile nach dem Session‑Block abgelöst ist. Drei Beziehungen sind deshalb auf lazy=False gesetzt:

Die beiden Sammlungen auf UnitOfMeasurement (telemetry_keys, uom_keys) bleiben lazy und werden dort, wo sie gebraucht werden, innerhalb der Session berührt. Der Vertrag dazu steht in Architektur im Detail.

Im selben Modul liegen die Modelle, die die REST‑API nach außen gibt. Zwei Formen fallen auf, weil sie eine Eigenschaft des Systems tragen und nicht nur eine Zeile:

Diese Seite beantwortet für jede SensorThings‑Entität, die der Adapter anlegt, woher jedes ihrer Felder kommt. Die Entitäten selbst und ihre Abfragesyntax beschreibt Schnittstellenbeschreibung SensorThings API; die Tabellen, aus denen die Zuordnungen stammen, Datenbankschema des Adapters.

Alles hier Beschriebene wird in den FROST‑Server eines Mandanten geschrieben — den, dessen Slug in der Ingest‑URL stand.

Zwei Quellen also: die Gerätedaten kommen aus ThingsBoard, die Bedeutung der Telemetrie aus den Stammdaten des Adapters.

Ein Thing entspricht genau einem Gerät in ThingsBoard.

Der Standort stammt aus dem Asset, das über eine Contains‑Relation mit dem Gerät verknüpft ist und den Typ building trägt. Findet der Adapter kein solches Asset, lehnt er mit 404 ab und schreibt nichts.

Ein Sensor entspricht einem Geräteprofil in ThingsBoard — nicht einem einzelnen Gerät. Alle Geräte desselben Profils teilen sich einen Sensor.

Die einzige Entität, die nicht aus ThingsBoard stammt. Ihre Wahrheit liegt in der Tabelle observedproperty des Adapters; jeder Mandant hält in seinem FROST eine abgeleitete Kopie mit name, definition und description aus der kanonischen Zeile.

Welche Observed Property zu einer Telemetrie gehört, entscheidet die Tabelle telemetrykey: Ein Schlüssel ohne Zuordnung erzeugt keinen Datastream und damit auch keine Observation — er wird still übergangen und protokolliert.

Ein Datastream je Telemetrie‑Schlüssel und Gerät. Er verbindet Thing, Sensor und ObservedProperty.

Für jeden Telemetrie‑Schlüssel einer eingehenden Nachricht, der einen Datastream hat, entsteht eine Observation.

Wird nicht verwendet. Der Adapter legt keine FeaturesOfInterest an; FROST erzeugt sie bei Bedarf selbst aus der Location des Things.

Die folgenden Ausschnitte zeigen die Entitäten eines Luftqualitätssensors, wie der Adapter sie anlegt.

Die Stammdaten des Adapters – UnitOfMeasurement, UnitOfMeasurementKey, TelemetryKey und ObservedProperty – liegen in der Adapter‑Datenbank und referenzieren sich gegenseitig; ObservedProperty wird zusätzlich als Kopie in den FROST‑Server jedes Mandanten repliziert (siehe unten). Damit über die REST‑API bzw. die Verwaltungsoberfläche keine inkonsistenten Zustände entstehen können, prüfen die jeweiligen Module unter src/thingsboard_frost_adapter/services/ vor Lösch‑ und Umbenennungs‑Operationen die Referenzen auf verwandte Entitäten. Die Regeln liegen dort und nirgends sonst: Die Router setzen einen Aufruf ab, die Repositories entscheiden nichts (siehe Architektur im Detail).

Alle Regelverletzungen werden über die Exception BusinessRuleViolationError (thingsboard_frost_adapter/exceptions/business_rule_violation_error.py) signalisiert. Ein globaler FastAPI‑Exception‑Handler in main.py wandelt diese Exception in eine HTTP‑Antwort mit Status 422 Unprocessable Entity und einer sprechenden Fehlermeldung im Body um.

Die Stammdatentabellen sind global – ihre Routen führen keinen Mandanten‑Slug –, ihre FROST‑Prüfungen laufen deshalb über alle Mandanten. Jede Prüfung fragt pro Mandant dessen eigenen FROST‑Server über das TenantFrostRepository dieses Mandanten (repositories/external/frost_repository.py, konstruiert über frost_repository_for(tenant)):

Alle drei Prüfungen sind fail‑closed (services/cross_tenant.py::reject_if_any_tenant_uses): Sie müssen von jedem Mandanten ein „nicht in Benutzung“ hören. Ein Mandant, der nicht antworten kann, verhindert das Löschen genauso wie einer, der die Daten noch benutzt – „nicht erreichbar“ ist kein Beleg für „nicht in Benutzung“. Die Fehlermeldung nennt in beiden Fällen den Mandanten.

UnitOfMeasurementKey selbst hat keine eigene Löschsperre, da keine Entität darauf zurückverweist.

telemetry_key_service.update prüft beim Setzen von observed_property_id, dass unter dieser Id tatsächlich eine ObservedProperty existiert – ein Select gegen die kanonische Postgres‑Tabelle (observed_property_repository.get_by_id), nicht gegen FROST. Existiert sie nicht, wird die Änderung mit einer BusinessRuleViolationError abgelehnt, statt einen Telemetry Key mit einer nicht existenten Zuordnung zu speichern.

Die Spalte trägt seit dem Umbau auf einen echten Fremdschlüssel (ondelete="RESTRICT") die Id und nicht mehr den Namen der Observed Property. Der Wächter bleibt trotzdem: RESTRICT verweigert mit einem IntegrityError, der weder sagt, welches Feld falsch war, noch als 422 beim Aufrufer ankommt. Die Prüfung läuft nur auf dem PATCH‑Pfad, weil dort der Wert steht, den ein Mensch in der Oberfläche ausgewählt hat; eine unsinnige Id an POST fängt die Bedingung ab.

ObservedProperty ist die einzige Stammdatenentität mit einer eigenen physischen FROST‑Identität. Die Wahrheit liegt in der Postgres‑Tabelle observedproperty; jeder Mandant hält in seinem FROST eine abgeleitete Kopie. Welche FROST‑Entität die Kopie ist, steht in tenantobservedproperty (tenant_id, observed_property_id → frost_id); die Spalten dieser Tabelle stehen in Datenbankschema des Adapters.

Die Aufnahme eines Mandanten ist eine Abfolge, keine eigene Operation: es gibt weder einen onboard‑Endpunkt noch eine Spalte onboarded_at. POST /tenant (services/tenant_service.py::onboard) erledigt beides in einem Aufruf und ohne Neustart:

Die beiden letzten Schritte folgen bewusst nicht derselben Regel: Ein fehlgeschlagener Abgleich rollt die Zeile nicht zurück. Die Kopien entstehen spätestens beim ersten Telemetriezugriff, ein fehlgeschlagener Abgleich ist also eine Verzögerung und kein Defekt – eine geprüfte Zeile dafür zu verwerfen wäre schlechter. Die Antwort trägt deshalb beides: {tenant, sync}, wobei sync: null bedeutet, dass die Replikation nicht durchgelaufen ist und über den Sync‑Button wiederholt werden sollte.

Die Zugangsdaten werden ausschließlich beim Schreiben geprüft und danach nie wieder; ein rotiertes ThingsBoard‑Zugangsdatum fällt erst durch Telemetrieverkehr auf und wird über GET /tenant/{id}/health sichtbar. Was der Adapter von selbst überbrückt, ist nur die ablaufende Sitzung: Der Client‑Cache baut das Paar eines Mandanten neu, bevor dessen ThingsBoard‑Token abläuft. Nötig ist das unter der Community Edition, weil deren Token nach 150 Minuten stirbt, der Cache aber die Lebensdauer des Prozesses hat. Der Adapter schreibt dabei zu keinem Zeitpunkt in ThingsBoard – die Rule Chain des Mandanten wird von Hand angelegt und bleibt in der Hand des Betreibers.

Wird der Name bzw. das Symbol/die Definition einer lokal verwalteten Entität geändert, überträgt der jeweilige Service diese Änderung best‑effort auf die zugehörigen FROST‑Datastreams:

Alle drei Übertragungen laufen über alle Mandanten (services/cross_tenant.py::push_to_every_tenant) und sind best‑effort: Schlägt die Aktualisierung eines einzelnen Datastreams fehl, wird der Fehler protokolliert (logger.exception) und die Verarbeitung der übrigen Datastreams fortgesetzt; schlägt ein ganzer Mandant fehl, werden die übrigen trotzdem bedient. Die lokale Änderung wird in jedem Fall übernommen; es erfolgt kein Rollback. Nicht erreichte Mandanten stehen im Feld failed_tenants der Antwort, das die Oberfläche als Hinweis anzeigt.

Jeder Schreibzugriff auf einen Datastream läuft dabei unter dem Thing‑Lock dieses Mandanten (entity_lock(slug, LockedEntity.THING, …)), damit eine Umbenennung nicht mit dem Telemetriepfad kollidiert und Mandanten sich nicht gegenseitig blockieren, wenn sie zufällig ein gleichnamiges Gerät haben.

Für ObservedProperty ist die Wiederholung der Abgleich („Sync observed properties“). Für Telemetry Keys und Maßeinheiten gibt es sie nicht: Diese Entitäten haben keine eigene FROST‑Identität, sondern stehen nur als Name bzw. eingebetteter Wert in den Datastreams. Sobald die kanonische Zeile den neuen Namen trägt, findet keine Abfrage die nicht umbenannten Datastreams mehr – sie müssen im FROST des betroffenen Mandanten von Hand korrigiert werden.

Diese Antwort wird mit HTTP‑Status 422 zurückgegeben, sobald eine der oben beschriebenen Regeln verletzt wird.

Der FROST‑Server ist die Referenzimplementierung des OGC SensorThings API Standards (Version 1.1) und die Schnittstelle, über die die vom Adapter exportierten Daten gelesen werden. Diese Seite ist eine Kurzreferenz für den Zugriff darauf — der vollständige Standard und die vollständige Serverdokumentation stehen unter Weiterführende Referenzen.

Die SensorThings API modelliert IoT‑Daten anhand von sieben Kern‑Entitäten.

Der Adapter legt sechs davon selbst an; FeaturesOfInterest erzeugt FROST bei Bedarf selbst. Womit der Adapter die Felder jeder Entität füllt, steht in Datenmodell.

Die Beziehungen zwischen den Entitäten folgen dem UML‑Modell des OGC SensorThings Standards:

Quelle: OGC SensorThings API – Data Model

Jeder Entitätstyp wird über einen eigenen Pfad angesprochen. Die folgende Konvention gilt durchgängig für alle sieben:

Die SensorThings API unterstützt standardisierte Query‑Optionen, die als URL‑Parameter übergeben werden.

Neben den Entity‑Endpunkten stellt der FROST‑Server System‑Endpunkte bereit, die für Betrieb und Monitoring relevant sind. Sie liegen unterhalb der Service‑Root, also nicht unter /v1.1.

Der Adapter authentifiziert niemanden. Er hat keine API‑Keys, keine Tokens, keine Benutzer — jeder, der ihn über das Netz erreicht, kann GET /tenant aufrufen und die Konfiguration aller Mandanten lesen sowie über POST /ingest/{slug}/…​ in jeden FROST‑Server schreiben. Der einzige Schutz ist, dass er ausschließlich innerhalb des Docker‑Netzes erreichbar ist.

Deshalb gilt für die echte Installation:

Wer eine Shell auf dem Docker‑Host hat, liest ohnehin jede Mandantenkonfiguration; das ist eine bewusst akzeptierte Einschränkung (siehe Bewusst akzeptierte Einschränkungen).

Wird vom Betreiber ausgeführt, bevor die Mandantenzeile angelegt wird — die Registrierung prüft fail‑closed gegen die realen Systeme und schlägt fehl, solange der FROST‑Server nicht steht. Dauer etwa eine Stunde.

Jeder Mandant bekommt eine eigene FROST‑Instanz mit eigener Datenbank und eigenem Keycloak‑Client. Das ist die Topologie, aus der sich alles Weitere ergibt: getrennte Datenhaltung, getrennte Leserechte und ein frost_server_url, der in der Registry eindeutig ist.

rulechain/thingsboard_frost_adapter.json ist eine exportierte Rule Chain mit vier TbRestApiCallNode und einem TBEL‑Filterknoten, der auf den Gerätenamen Frost Adapter Test Device festgelegt ist.

Die Datei im Repository trägt den Slug fest verdrahtet in der URL, nicht als Templating‑Stufe ({{SLUG}}) — eine solche Datei ließe sich ohne einen Substitutionsschritt gar nicht erst in ThingsBoard importieren, und ein solcher Schritt existiert nicht. Angestrebt ist der Slug des ersten Mandanten: nur so dokumentiert die eingecheckte Chain eine Endpunkt‑Oberfläche, die es wirklich gibt.

Ablauf je weiterem Mandant:

Die Reihenfolge ist verbindlich; der 409 beim Löschen erzwingt sie. Die Schritte in der Oberfläche sind unter Einen Mandanten stilllegen beschrieben; hier stehen sie in der Fassung, die der Betrieb braucht.

TENANT_SECRET_KEY ist der Fernet‑Schlüssel, mit dem das ThingsBoard‑Geheimnis jedes Mandanten in der Datenbank verschlüsselt ist — der API‑Key unter PE, das Passwort unter CE. Er ist Pflicht, hat keinen Standardwert, keinen Klartext‑Rückfallweg — und keinen Rotationsmechanismus.

Geht er verloren oder wird er neu erzeugt, ist jedes gespeicherte Geheimnis nicht mehr entschlüsselbar. Der Adapter startet weiterhin; der Fehler zeigt sich pro Mandant beim Bau seiner Clients mit einer expliziten Meldung, und andere Mandanten arbeiten weiter — allerdings nur, sofern sie unter einem noch gültigen Schlüssel verschlüsselt wurden, was nach einem vollständigen Schlüsselverlust auf keinen zutrifft.

Die Wiederherstellung besteht darin, den neuen Schlüssel zu setzen und anschließend für jeden Mandanten das ThingsBoard‑Geheimnis über die Verwaltungsoberfläche neu einzugeben. Bei zwei bis drei Mandanten sind das Minuten. Derselbe Ablauf gilt, wenn ein Datenbank‑Dump in eine Installation mit einem anderen Schlüssel eingespielt wird.

Ein neuer Schlüssel wird erzeugt mit:

THINGSBOARD_EDITION sagt, welche ThingsBoard‑Installation hinter THINGSBOARD_URL steht: pe (Standard) oder ce. Sie wird nie ermittelt, sondern konfiguriert — ein Client zu bauen hieße sonst, ein Fremdsystem zu fragen, was es ist, und das Urteil darüber zwischenzuspeichern.

Die Edition entscheidet beides zugleich, Client‑Klasse und Zugangsdaten:

Der Ablauf auf dem Entwicklungssystem, auf dem der Adapter läuft:

Es gibt keine Migration. Die Umstellung ist docker compose down -v und ein Neuaufbau — der Adapter läuft nur auf dem Entwicklungssystem des Teams, und alles, was er bisher geschrieben hat, ist entbehrlich. Diese eine Tatsache lässt Datenübernahme, Wartungsfenster und verwaiste Redis‑Sperrschlüssel zu einem einzigen zerstörenden Schritt zusammenfallen.

Die folgenden acht Punkte sind ausgewählt, nicht übersehen worden. Jeder ist bei zwei bis drei Mandanten günstig und wäre bei zehn eine Überprüfung wert.