Files
Sternsinger/CMBNet/README_CMBNet.md
T

4.8 KiB

CMBNet

Webanwendung für die Verwaltung von Straßen und Gruppen mit Kartendarstellung.

Setup

cd CMBNet
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdir -p instance logs data migrations
flask --app cmbnet init-db
flask --app cmbnet run --debug --host 127.0.0.1 --port 5000

Zugriff

Öffne http://127.0.0.1:5000 und wähle einen Mandanten (BV, RV, SV).

Betrieb hinter einem Reverse-Proxy (URI-Prefix)

Die Anwendung kann unter einem beliebigen Pfad ausgeliefert werden, z. B. https://example.com/cmbnet/. Dazu muss der Proxy den öffentlichen Prefix im Header X-Forwarded-Prefix setzen:

example.com {
    redir /cmbnet /cmbnet/ 308

    handle_path /cmbnet/* {
        reverse_proxy 127.0.0.1:5000 {
            header_up X-Forwarded-Prefix /cmbnet
        }
    }
}

Die Middleware in cmbnet/__init__.py setzt daraus SCRIPT_NAME, sodass url_for alle Links, Formularziele und statischen Dateien mit Prefix erzeugt. Der Prefix wird außerdem als CMBNET_BASE_URL an JavaScript übergeben; AJAX- und WebSocket-Aufrufe bilden ihre URLs damit korrekt. Eine vollständige Beispielkonfiguration (auch für Proxys, die den Prefix nicht entfernen) steht in Caddyfile.example.

Wichtig: Der Flask-Port sollte nur für den Reverse-Proxy erreichbar sein, damit Clients den Header nicht selbst setzen können.

WebSocket-Synchronisierung

Jede Webview erzeugt beim Laden einmalig eine Client-ID. Sie wird bewusst nicht in sessionStorage gespeichert: Ein Seiten-Reload erzeugt eine neue Client-ID und damit eine neue Broker-Verbindung. Nicht zustellbare Nachrichten mit Code >= 100 werden beim Broker pro (Mandant, Client-ID) gepuffert und bei der nächsten WebSocket-Verbindung mit derselben Client-ID ausgeliefert. Mehrere Clients desselben Accounts werden getrennt verwaltet und alle beliefert.

Die Zeitfenster lassen sich über Umgebungsvariablen konfigurieren:

  • CMBNET_WS_QUEUE_MAX_AGE_MINUTES (Default 15): Maximales Alter einer Client-Queue. Ältere Queues werden verworfen; beim nächsten Reconnect mit derselben Client-ID wird stattdessen eine Code-99-Nachricht mit Hinweis auf die zu lange Unterbrechung zugestellt.
  • CMBNET_WS_CLIENT_RETENTION_MINUTES (Default 60): Wie lange eine nicht mehr verbundene Webview samt Queue registriert bleibt, bevor der Broker sie endgültig aufräumt.
  • CMBNET_WS_GROUP_ONLINE_TIMEOUT_SECONDS (Default 120): Zeit ohne Code-2- Lebenszeichen, nach der eine Gruppe von online auf unterwegs wechselt.
  • CMBNET_WS_DEBUG_MESSAGES (Default 1): schreibt jede beim Broker eingehende Nachricht inklusive Absender, Client-ID, Code und ermitteltem Empfängerkreis nach logs/cmbnet-ws-YYYY-MM-DD.log. Mit 0 lässt sich die Ausgabe abschalten.
  • CMBNET_WS_BUS_POLL_INTERVAL (Default 0.5): Intervall in Sekunden, in dem jeder Worker die gemeinsame Queue für seine lokal verbundenen Clients prüft.
  • CMBNET_WS_EPHEMERAL_TTL_SECONDS (Default 30): Lebensdauer kurzlebiger Code-2-Zustellaufträge.
  • CMBNET_WS_WORKER_ID: optionale feste Worker-ID; muss je Worker-Prozess eindeutig sein. Standardmäßig wird <hostname>:<pid> verwendet.

Die Client-Queues und Sequenznummern liegen in der gemeinsamen SQLite-Datenbank (ws_clients, ws_client_queue). Dadurch überstehen sie einen Worker-Neustart und einen Reconnect auf einem anderen WSGI-Worker. Jeder Worker betreibt eine eigene Zustellschleife und liefert nur an seine lokal verbundenen Clients aus. Die Latenz für workerübergreifende Nachrichten ergibt sich aus CMBNET_WS_BUS_POLL_INTERVAL (Default 0.5 Sekunden). Der mobile Client puffert zusätzlich ausgehende fachliche Nachrichten kurzzeitig im Speicher und sendet sie nach erfolgreicher Authentifizierung automatisch nach.

Für den Betrieb mit mehreren Workern muss Gunicorn ohne preload_app laufen, damit Heartbeat und Zustellschleife in jedem Worker-Prozess starten:

gunicorn --worker-class gevent --workers 4 --bind 127.0.0.1:5000 wsgi:app

SQLite läuft dabei im WAL-Modus mit einem busy_timeout. Bei sehr vielen Clients oder hoher Schreiblast sollte statt SQLite ein Redis- oder PostgreSQL-Bus verwendet werden.

Eine ausführliche Beschreibung des Protokolls, der Brokerlogik, der Nebenläufigkeit und der aktuellen Abweichungen steht in ../doc/broker.md.

Erste Einrichtung

Nach der Initialisierung der Datenbank müssen noch Mandanten und ein Admin-Account angelegt werden.

sqlite3 instance/cmbnet.sqlite3
INSERT INTO tenants (code, name) VALUES ('BV', 'Bezirk BV'), ('RV', 'Bezirk RV'), ('SV', 'Bezirk SV');
INSERT INTO accounts (tenant_id, name, password_hash, role) VALUES (2, 'admin', '...', 'Administrator');

Für den Passwort-Hash kann python3 -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('admin'))" verwendet werden.