Files
Sternsinger/CMBNet/docs/FCM_HOWTO.md
T

241 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Firebase/FCM einrichten – Howto
Dieses Dokument beschreibt die praktischen Schritte, um die im Code
vorbereiteten FCM-Aufwachsignale für die mobilen PWA-Ansichten zu aktivieren.
FCM überträgt ausschließlich das Signal; Nachrichten und Positionen laufen
weiterhin über WebSocket und die Broker-Queue. Die Architektur und die
Plattformgrenzen stehen in [`FCM_ARCHITEKTUR.md`](FCM_ARCHITEKTUR.md).
## Voraussetzungen
- Ein Google-Konto und Zugriff auf die [Firebase Console](https://console.firebase.google.com/).
- Die CMBNet-Installation läuft über **HTTPS** (auch im Test). Web Push und
Service Worker funktionieren nicht über eine reine HTTP-Adresse, außer auf
`localhost`.
- Die mobile Ansicht ist als PWA installiert (zum Home-Bildschirm
hinzugefügt). Besonders auf iOS/iPadOS ist das Voraussetzung für Web Push.
- Python-Umgebung der Anwendung kann Pakete installieren.
## 1. Firebase-Projekt anlegen
1. In der Firebase Console **Projekt hinzufügen** wählen.
2. Projektnamen vergeben (z. B. `cmbnet-push`) und die Analytics-Option nach
Bedarf aktivieren. Für FCM ist Analytics nicht erforderlich.
3. Nach dem Anlegen die Projekt-ID notieren. Sie wird später als
`CMBNET_FCM_PROJECT_ID` bzw. `CMBNET_FCM_WEB_PROJECT_ID` verwendet.
## 2. Web-App registrieren
1. In den **Projekteinstellungen → Allgemein** unter *Meine Apps* die
Plattform **Web** (`</>`) hinzufügen.
2. Einen Spitznamen vergeben und die App registrieren.
3. Den angezeigten `firebaseConfig`-Block notieren. Er enthält ausschließlich
öffentliche Werte:
```js
{
apiKey: "...",
authDomain: "cmbnet-push.firebaseapp.com",
projectId: "cmbnet-push",
storageBucket: "cmbnet-push.appspot.com",
messagingSenderId: "...",
appId: "..."
}
```
Diese Werte sind **keine Geheimnisse** und werden vom Server an Browser
und Service Worker ausgeliefert. Der Service-Account aus Schritt 4 darf
dagegen niemals in eine Webseite oder in das Repository gelangen.
## 3. Cloud Messaging und VAPID-Schlüssel
1. In der Firebase Console unter **Cloud Messaging** die Web-Push-
Konfiguration öffnen.
2. Falls noch kein Schlüsselpaar existiert, unter *Web-Push-Zertifikate*
ein Schlüsselpaar erzeugen.
3. Den angezeigten **VAPID-Schlüssel** (öffentlicher Schlüssel) notieren. Er
wird als `CMBNET_FCM_VAPID_KEY` benötigt.
4. Die Web-Push-Konfiguration muss zum selben Firebase-Projekt wie die
Web-App gehören.
## 4. Service-Account für den Server erzeugen
1. In der Firebase Console **Projekteinstellungen → Dienstkonten** öffnen.
2. **Neuen privaten Schlüssel generieren** wählen und die JSON-Datei
herunterladen.
3. Die Datei außerhalb des Repositories ablegen, z. B.
`/etc/cmbnet/firebase-service-account.json`, und nur für den
Anwendungsbenutzer lesbar machen:
```bash
sudo install -m 600 firebase-service-account.json \
/etc/cmbnet/firebase-service-account.json
```
4. Alternativ kann der JSON-Inhalt als eine Zeile in
`CMBNET_FCM_SERVICE_ACCOUNT_JSON` gesetzt werden. Für den Dauerbetrieb ist
eine Datei mit restriktiven Rechten vorzuziehen, weil Umgebungsvariablen
leichter in Prozesslisten oder Logs auftauchen.
## 5. Python-Abhängigkeit installieren
FCM nutzt das optionale Paket `firebase-admin`. Es ist in
`requirements.txt` eingetragen, muss aber in der aktiven Umgebung installiert
sein:
```bash
cd CMBNet
source .venv/bin/activate
pip install -r requirements.txt
```
Ohne dieses Paket startet die Anwendung weiterhin; FCM bleibt dann deaktiviert
und protokolliert einen entsprechenden Hinweis.
## 6. Umgebungsvariablen setzen
Die Anwendung liest die Konfiguration aus Umgebungsvariablen (siehe
`config.py`). Ein vollständiges Beispiel für einen Dienstmanager oder eine
`.env`-Datei:
```bash
CMBNET_FCM_ENABLED=1
# Serverseitiger Versand
CMBNET_FCM_PROJECT_ID=cmbnet-push
CMBNET_FCM_SERVICE_ACCOUNT_FILE=/etc/cmbnet/firebase-service-account.json
# Alternativ statt der Datei:
# CMBNET_FCM_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
# Öffentliche Web-Konfiguration aus Schritt 2
CMBNET_FCM_WEB_API_KEY=...
CMBNET_FCM_WEB_AUTH_DOMAIN=cmbnet-push.firebaseapp.com
CMBNET_FCM_WEB_PROJECT_ID=cmbnet-push
CMBNET_FCM_WEB_STORAGE_BUCKET=cmbnet-push.appspot.com
CMBNET_FCM_WEB_MESSAGING_SENDER_ID=...
CMBNET_FCM_WEB_APP_ID=...
# Web-Push aus Schritt 3
CMBNET_FCM_VAPID_KEY=...
# Optional: Zeitverhalten
CMBNET_FCM_OFFLINE_WAKE_MINUTES=5
CMBNET_FCM_QUEUE_WAKE_COOLDOWN_SECONDS=60
CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS=30
```
Die Datei mit den Umgebungsvariablen muss dieselben Rechte wie die
Service-Account-Datei besitzen. Nach Änderungen den WSGI-Prozess neu starten;
Python liest die Werte beim Start.
### Prüfen, ob die Konfiguration vollständig ist
`public_fcm_config()` aktiviert FCM nur, wenn `CMBNET_FCM_ENABLED` gesetzt ist
**und** API-Key, Projekt-ID, Sender-ID, App-ID und VAPID-Schlüssel vorhanden
sind. Prüfen lässt sich das über die vom Server erzeugte Datei:
```bash
curl -s https://example.com/fcm-sw-config.js
```
Erwartet wird ein JavaScript-Objekt mit `"enabled": true` und gefüllten
`firebase`-Werten. Bei `"enabled": false` fehlt mindestens einer der oben
genannten Werte oder `firebase-admin` ist nicht installiert.
## 7. Datenbankmigration
Beim nächsten Start führt `ensure_schema()` die idempotenten Migrationen aus.
Neu sind die Spalten `ws_clients.client_type`, `ws_clients.last_wake_at`,
`ws_clients.last_wake_reason` sowie die Tabelle `ws_push_tokens`. Eine
manuelle Migration ist nicht nötig; ein Backup der SQLite-Datei vor dem
ersten Start ist trotzdem empfehlenswert.
## 8. Mobile PWA installieren und Benachrichtigungen erlauben
1. Die mobile Ansicht (Gruppen-View bzw. mobiler Dispatcher) über HTTPS
öffnen.
2. Im Browsermenü **Zum Home-Bildschirm** bzw. **App installieren** wählen.
3. Die PWA aus dem Home-Bildschirm starten.
4. In den Einstellungen der mobilen Ansicht **Benachrichtigungen aktivieren**
antippen und die Browserabfrage bestätigen.
5. Danach lädt die Seite das Firebase-SDK, fordert ein FCM-Token an und
registriert es über `POST /<tenant>/api/push/register`. Der Client-Typ
(`group_view` bzw. `dispatcher_mobile`) wird dabei gegen die Rolle geprüft.
Auf iOS/iPadOS muss die App wirklich installiert sein; in einem normalen
Safari-Tab wird kein Token registriert. Nach dem Entfernen der PWA vom
Home-Bildschirm oder dem Entziehen der Benachrichtigungserlaubnis endet die
Zustellung.
## 9. Funktion testen
### Token-Registrierung prüfen
Nach dem Aktivieren der Benachrichtigungen in der Datenbank nachsehen:
```bash
sqlite3 instance/cmbnet.sqlite3 \
"SELECT tenant_id, client_id, account_id, client_type, platform, auto_position, invalid
FROM ws_push_tokens;"
```
Es muss ein Eintrag für den mobilen Client vorhanden sein. Ein leeres Ergebnis
bedeutet meist: keine HTTPS-Verbindung, keine installierte PWA, keine
Benachrichtigungserlaubnis oder `enabled: false` in `fcm-sw-config.js`.
### Manuellen Wake auslösen
Im Desktop-Dispatcher oder im mobilen Dispatcher den Radar-Button antippen.
Der Button ruft `POST /<tenant>/api/push/wake` auf. Die Antwort enthält
`candidates`, `sent` und `failed`.
- `sent > 0`: FCM hat das Signal angenommen.
- `candidates = 0`: kein getrennter mobiler Client mit gültigem Token.
- HTTP 503: FCM ist nicht vollständig konfiguriert.
- HTTP 403: Rolle darf nicht wecken (nur Dispatcher/Administrator).
Da nur getrennte Clients geweckt werden, muss die mobile PWA vor dem Test
geschlossen oder die WebSocket-Verbindung unterbrochen sein.
### Offline-Timeout prüfen
`CMBNET_FCM_OFFLINE_WAKE_MINUTES` testweise auf `1` setzen, PWA schließen und
nach ein bis zwei Minuten den Radar-Button im Desktop-Dispatcher verwenden.
Bei aktiver automatischer Positionsübertragung sollte die Gruppen-View nach
dem Wake eine neue Position senden. Der Service Worker zeigt nur dann eine
Benachrichtigung, wenn kein PWA-Fenster erreichbar ist.
### FCM-Versand direkt prüfen
Bei aktiviertem Debug-Logging des WSGI-Servers erscheinen Warnungen, wenn
`firebase-admin` fehlt, die Initialisierung scheitert oder FCM einen Batch
ablehnt. Ungültige Tokens werden als `invalid` markiert und nicht mehr
verwendet.
## Troubleshooting
| Symptom | Ursache / Lösung |
| --- | --- |
| `fcm-sw-config.js` liefert `enabled: false` | `CMBNET_FCM_ENABLED` nicht gesetzt oder einer der Web-Werte/VAPID fehlt. |
| Kein Token in `ws_push_tokens` | PWA nicht installiert, keine Benachrichtigungserlaubnis, kein HTTPS oder Client-Typ/Rolle passt nicht. |
| `firebase-admin ist nicht installiert` im Log | `pip install -r requirements.txt` in der aktiven Umgebung ausführen. |
| `FCM-Initialisierung fehlgeschlagen` | Service-Account-Datei fehlt, ist nicht lesbar oder gehört zu einem anderen Projekt. |
| `SENDER_ID_MISMATCH` bzw. Token wird ungültig | Web-Konfiguration und Service-Account stammen aus verschiedenen Firebase-Projekten. |
| Radar-Button meldet 0 Kandidaten | Der Client ist noch verbunden, hat kein Token oder wurde bereits innerhalb des Cooldowns geweckt. |
| iOS erhält keine Push-Nachricht | PWA nicht installiert, iOS < 16.4 oder Benachrichtigungen nicht erlaubt. |
| Benachrichtigung erscheint, aber keine Position | Kein PWA-Fenster aktiv oder Standort im Hintergrund nicht erlaubt; die letzte bekannte Position wird verwendet. |
| Doppelte Wakes bei mehreren Workern | `CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS` und `CMBNET_WS_BUS_POLL_INTERVAL` prüfen; die Reservierung erfolgt über `last_wake_at`. |
## Sicherheit und Datenschutz
- Der Service-Account-Schlüssel bleibt auf dem Server und gehört nicht ins
Repository, in Templates oder in Browser-JavaScript.
- FCM-Tokens sind installationsbezogene Kennungen. Sie werden nicht geloggt
und beim Abmelden über `DELETE /<tenant>/api/push/register` entfernt.
- Das FCM-Signal enthält nur `type` und `reason`. Mandant, Rolle, Nachricht,
Absender und Position werden nicht über Firebase übertragen.
- Firebase ist ein externer Google-Dienst. Der Betrieb muss die daraus
folgenden Datenschutz- und Verfügbarkeitsanforderungen bewerten.
- Die PWA muss über HTTPS laufen; der Server sollte nur hinter dem
Reverse-Proxy erreichbar sein.