242 lines
10 KiB
Markdown
242 lines
10 KiB
Markdown
# 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_MANUAL_WAKE_COOLDOWN_SECONDS=15
|
||
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.
|