4. Versuch mit mehr Debug ausgeben

This commit is contained in:
concierge committed 2026-11-11 07:50:00 +01:00
1 parent 84aa7f9631
commit 572a881f72
8 files changed
+516 -4

No files matched your search

+4 -1
View File
@@ -182,7 +182,10 @@ lässt sich dieses zusätzliche Wecken abschalten.
Die Architektur, Trigger, Grenzen auf Android/iOS und alle Die Architektur, Trigger, Grenzen auf Android/iOS und alle
Konfigurationsvariablen stehen in Konfigurationsvariablen stehen in
[`docs/FCM_ARCHITEKTUR.md`](docs/FCM_ARCHITEKTUR.md). Die praktische [`docs/FCM_ARCHITEKTUR.md`](docs/FCM_ARCHITEKTUR.md). Der vollständige
Protokollablauf inklusive Funktionsnamen sowie die Anforderungen an Reverse
Proxy und CORS sind in
[`docs/FCM_PROTOKOLL.md`](docs/FCM_PROTOKOLL.md) beschrieben. Die praktische
Einrichtung von Firebase-Projekt, Web-App, VAPID-Schlüssel, Service-Account Einrichtung von Firebase-Projekt, Web-App, VAPID-Schlüssel, Service-Account
und PWA-Installation beschreibt und PWA-Installation beschreibt
[`docs/FCM_HOWTO.md`](docs/FCM_HOWTO.md). [`docs/FCM_HOWTO.md`](docs/FCM_HOWTO.md).
+7
View File
@@ -181,6 +181,12 @@ def wake_mobile_clients(**kwargs):
len(candidates), int(result.get('sent') or 0), len(candidates), int(result.get('sent') or 0),
int(result.get('failed') or 0) int(result.get('failed') or 0)
) )
error_details = list(result.get('errors') or [])[:5]
for item in error_details:
current_app.logger.warning(
'FCM-Wake-Fehler: tenant=%s token=%s error=%s',
g.tenant_id, item.get('fingerprint'), item.get('error')
)
return jsonify({ return jsonify({
'ok': True, 'ok': True,
@@ -190,5 +196,6 @@ def wake_mobile_clients(**kwargs):
'failed': int(result.get('failed') or 0), 'failed': int(result.get('failed') or 0),
'valid_tokens': stats['valid_tokens'], 'valid_tokens': stats['valid_tokens'],
'connected': stats['connected'], 'connected': stats['connected'],
'errors': error_details,
'error': result.get('error'), 'error': result.get('error'),
}) })
+44 -1
View File
@@ -7,6 +7,7 @@ Firebase-Konfiguration vollständig startet.
""" """
from __future__ import annotations from __future__ import annotations
import hashlib
import json import json
import logging import logging
import threading import threading
@@ -190,6 +191,24 @@ class FcmService:
raise FileNotFoundError(f'Service-Account-Datei fehlt: {path}') raise FileNotFoundError(f'Service-Account-Datei fehlt: {path}')
return credentials.Certificate(str(path)) return credentials.Certificate(str(path))
@staticmethod
def _token_fingerprint(token):
"""Verkürzter, stabiler Token-Fingerabdruck für Logs (kein Klartext)."""
if not token:
return '-'
return hashlib.sha256(str(token).encode('utf-8')).hexdigest()[:12]
@staticmethod
def _describe_send_error(token, exception):
"""Formatiert einen FCM-Fehler und entfernt das Token aus dem Text."""
name = type(exception).__name__ if exception is not None else 'UnknownError'
text = str(exception or '').strip()
if token:
text = text.replace(str(token), '<token>')
if text:
return f'{name}: {text}'
return name
def send_wake(self, tokens, reason='wake'): def send_wake(self, tokens, reason='wake'):
"""Sendet ein reines Daten-Signal an die angegebenen FCM-Tokens. """Sendet ein reines Daten-Signal an die angegebenen FCM-Tokens.
@@ -205,6 +224,7 @@ class FcmService:
'failed': 0, 'failed': 0,
'sent_tokens': [], 'sent_tokens': [],
'invalid_tokens': [], 'invalid_tokens': [],
'errors': [],
} }
if not tokens: if not tokens:
return result return result
@@ -246,6 +266,9 @@ class FcmService:
result['failed'] += batch_result['failed'] result['failed'] += batch_result['failed']
result['sent_tokens'].extend(batch_result['sent_tokens']) result['sent_tokens'].extend(batch_result['sent_tokens'])
result['invalid_tokens'].extend(batch_result['invalid_tokens']) result['invalid_tokens'].extend(batch_result['invalid_tokens'])
result['errors'].extend(batch_result['errors'])
if batch_result.get('error'):
result['error'] = batch_result['error']
return result return result
@@ -255,6 +278,7 @@ class FcmService:
'failed': 0, 'failed': 0,
'sent_tokens': [], 'sent_tokens': [],
'invalid_tokens': [], 'invalid_tokens': [],
'errors': [],
} }
message = messaging.MulticastMessage( message = messaging.MulticastMessage(
tokens=tokens, tokens=tokens,
@@ -266,8 +290,17 @@ class FcmService:
response = messaging.send_each_for_multicast(message) response = messaging.send_each_for_multicast(message)
responses = list(response.responses) responses = list(response.responses)
except Exception as exc: except Exception as exc:
logger.warning('FCM-Batchversand fehlgeschlagen: %s', exc) details = self._describe_send_error(None, exc)
logger.warning(
'FCM-Batchversand fehlgeschlagen (%s Empfänger): %s',
len(tokens), details
)
batch_result['failed'] += len(tokens) batch_result['failed'] += len(tokens)
batch_result['error'] = details
batch_result['errors'].append({
'fingerprint': '-',
'error': details,
})
return batch_result return batch_result
for token, send_response in zip(tokens, responses): for token, send_response in zip(tokens, responses):
@@ -277,6 +310,16 @@ class FcmService:
continue continue
batch_result['failed'] += 1 batch_result['failed'] += 1
exception = send_response.exception exception = send_response.exception
details = self._describe_send_error(token, exception)
fingerprint = self._token_fingerprint(token)
logger.warning(
'FCM-Signal abgelehnt: token=%s error=%s',
fingerprint, details
)
batch_result['errors'].append({
'fingerprint': fingerprint,
'error': details,
})
text = str(exception or '').upper() text = str(exception or '').upper()
if ( if (
isinstance(exception, messaging.UnregisteredError) isinstance(exception, messaging.UnregisteredError)
+1
View File
@@ -0,0 +1 @@
Thomas Kugelmeier,thomas,MacBookAir.lan,11.11.2026 07:42,file:///Users/thomas/Library/Application%20Support/LibreOffice/4;
+5
View File
@@ -14,6 +14,11 @@ Das Signal besteht aus einem Data-Payload mit den Feldern `type` und `reason`
Protokollierung und der Entscheidung, ob ein sichtbarer Hinweis sinnvoll ist. Protokollierung und der Entscheidung, ob ein sichtbarer Hinweis sinnvoll ist.
Sie sind kein Anwendungsinhalt. Sie sind kein Anwendungsinhalt.
Der vollständige Ablauf vom Laden der PWA bis zur Reaktion auf das
Aufwachsignal – mit allen Funktionsnamen, Endpunkten und Fehlerpfaden – steht
in [`FCM_PROTOKOLL.md`](FCM_PROTOKOLL.md). Dort sind auch die Anforderungen an
Reverse Proxy, Service Worker, WebSocket und CORS beschrieben.
## Beteiligte Komponenten ## Beteiligte Komponenten
| Komponente | Aufgabe | | Komponente | Aufgabe |
+437
View File
@@ -0,0 +1,437 @@
# FCM-Protokoll und Reverse-Proxy-Anforderungen
Diese Datei beschreibt zwei Dinge:
1. den vollständigen Ablauf vom Laden der PWA über die Token-Registrierung und
den WebSocket-Handshake bis zum manuellen FCM-Wake und der Reaktion des
Clients – mit den präzisen Funktionsnamen,
2. die Anforderungen an einen vorgeschalteten Reverse Proxy, insbesondere zu
CORS, Service Worker und WebSocket.
## Teil A – Protokollablauf
### Kurzsequenz
```
PWA-Seite (mobile.js) Service Worker (sw.js) Flask/API/Broker Google FCM / APNs
| | | |
|-- registerServiceWorker() ---------------------->| sw.js, fcm-sw-config.js |
|-- initFirebasePush() --> fcmMessaging.getToken() | |
|<-------------------------------------------------|------------------- Token |
|-- POST /push/register -------------------------->| register_push_token() |
|-- GET /auth/ws-token --------------------------->| ws_token() |
|-- WS /ws, Code 0 ------------------------------->| register_connection() |
|<-- Code 0 "authenticated" -----------------------| authenticate() |
| | | |
| | |-- send_wake() ---------->|
| |<-- onBackgroundMessage -| send_each_for_multicast|
|<-- postMessage cmbnet-wake ---------------------| |
|-- connectWebSocket(), Position ----------------->| |
| |-- showNotification() | |
```
### Beteiligte
| Komponente | Datei / Modul | Aufgabe |
| --- | --- | --- |
| HTML-Grundgerüst | `templates/base.html` | erzeugt die Client-ID, bindet Skripte ein |
| Mobile View | `static/js/views/mobile.js` | Firebase-Client, Token-Registrierung, WebSocket, Wake-Reaktion |
| Service Worker | `static/js/sw.js` | empfängt Hintergrund-Pushes, weckt ein Fenster, zeigt ggf. eine Benachrichtigung |
| HTTP-API | `cmbnet/api/push.py`, `cmbnet/api/auth.py` | Token-Registrierung, Wake-Button, WS-Einmal-Token |
| WebSocket | `cmbnet/ws/routes.py`, `cmbnet/ws/broker.py` | Handshake, Verbindungsverwaltung, Queue, Wake-Auslösung |
| Persistenz | `cmbnet/ws/store.py` | `ws_clients`, `ws_push_tokens`, `ws_worker`, Queues |
| Firebase Admin | `cmbnet/services/fcm_service.py` | serverseitiger FCM-Versand über die HTTP-v1-API |
| Google FCM | Firebase Cloud Messaging | Zustellung an Browser/PWA, bei iOS über APNs |
### Phase 1 – Laden der PWA
1. Der Browser lädt z. B. `/<tenant>/mobil` oder `/<tenant>/dispatcher-mobil`.
2. Das Inline-Skript in `templates/base.html` führt die IIFE `initClientId()`
aus und setzt:
- `window.CMBNET_CLIENT_ID`
- `window.CMBNET_CLIENT_SESSION_ID` (Kompatibilität)
3. Das Template setzt weitere Globals, u. a.:
- `window.CMBNET_TENANT`
- `window.CMBNET_VIEW_MODE`
- `window.CMBNET_CLIENT_TYPE` (`group_view` bzw. `dispatcher_mobile`)
- `window.CMBNET_SW_URL`
- `window.CMBNET_FCM_CONFIG` (Ergebnis von
`cmbnet/services/fcm_service.py:public_fcm_config()`)
4. `static/js/views/mobile.js` registriert
`document.addEventListener('DOMContentLoaded', initMobile)`.
5. `initMobile()` ruft u. a. auf:
- `loadSettings()`
- `initMap()`
- `registerServiceWorker()`
- `initNotifications()`
- `initPushWakeListener()`
- anschließend `connectWebSocket()`
### Phase 2 – Service Worker und Firebase-SDK
1. `registerServiceWorker()` registriert `window.CMBNET_SW_URL` über
`navigator.serviceWorker.register(swUrl)`.
2. Nach `load` und nur bei `Notification.permission === 'granted'` ruft sie
`initFirebasePush(registration)` auf.
3. Der Service Worker `static/js/sw.js` lädt beim Start:
- `importScripts('fcm-sw-config.js')` → serverseitig erzeugte öffentliche
Konfiguration (`cmbnet/__init__.py:fcm_service_worker_config()`)
- `importScripts('https://www.gstatic.com/firebasejs/<sdkVersion>/firebase-app-compat.js', '.../firebase-messaging-compat.js')`
4. Im Service Worker:
- `firebase.initializeApp(fcmConfig.firebase)`
- `fcmMessaging = firebase.messaging()`
- `fcmMessaging.onBackgroundMessage(payload => handleFcmWake(reason))`
### Phase 3 – Benachrichtigungsrecht und FCM-Token
1. `initNotifications()` bindet den Dialog und ruft bei Bedarf
`requestNotifications()` → `Notification.requestPermission()` auf.
2. `initFirebasePush(registration, force)` prüft:
- `window.CMBNET_FCM_CONFIG.enabled`
- gültigen `clientType`
- `Notification.permission === 'granted'`
- auf iOS: `isStandaloneMode()` (installierte PWA)
3. Danach:
- `loadScriptOnce()` lädt `firebase-app-compat.js` und
`firebase-messaging-compat.js` im Seitenkontext.
- `firebase.initializeApp(config.firebase)`
- `messaging = firebase.messaging()`
- `messaging.onMessage(payload => { showFirebaseDebugPopup(...); handlePushWake(reason); })`
für den Vordergrund.
- `messaging.getToken({vapidKey: config.vapidKey, serviceWorkerRegistration: swRegistration})`
4. Der Token wird in `state.fcmToken` gespeichert.
5. `syncPushRegistration()` sendet:
- `POST /<tenant>/api/push/register`
- Body: `token`, `client_id` (`window.CMBNET_CLIENT_ID`), `client_type`,
`platform`, `auto_position`
6. Serverseitig in `cmbnet/api/push.py:register_push_token()`:
- `TOKEN_RE.fullmatch(token)`
- `normalize_client_type(...)` (`cmbnet/ws/client_types.py`)
- `broker.normalize_client_id(...)` (`cmbnet/ws/broker.py`)
- `store.upsert_push_token(...)` (`cmbnet/ws/store.py`)
7. `store.upsert_push_token()`:
- legt bei Bedarf einen Platzhalter in `ws_clients` an
(`disconnected_at = now()`), damit das Token als Wake-Kandidat existiert,
- schreibt/aktualisiert `ws_push_tokens` (Token ist projektweit eindeutig),
- entfernt ältere Tokens derselben Client-ID.
8. Der Server loggt `FCM-Token registriert: tenant=… client=… type=…`.
### Phase 4 – WebSocket-Handshake
1. `connectWebSocket()` ruft `GET /<tenant>/api/auth/ws-token` auf.
Serverseitig: `cmbnet/api/auth.py:ws_token()` legt eine Zeile in
`ws_tokens` an und liefert `{token}`.
2. Der Client öffnet `new WebSocket(wsUrl)` gegen `/<tenant>/ws`.
3. Bei `open` sendet er Code 0:
```json
{"code":0,"msg":{"token":"…","client_type":"group_view"},
"client_id":"<window.CMBNET_CLIENT_ID>"}
```
4. Serverseitig in `cmbnet/ws/routes.py:ws()`:
- `_parse_auth_payload(msg.msg)` liefert Token, Client-ID und Client-Typ.
- `broker.normalize_client_id(...)`
- `broker.register_connection(...)`
→ `store.ensure_client(...)` (INSERT/UPDATE `ws_clients`,
`disconnected_at = NULL`)
→ `store.touch_worker(...)` (`ws_workers`)
- `broker.authenticate(...)` prüft `ws_tokens` (`used = 0`, Ablauf),
markiert das Token als benutzt, setzt `conn['last_seen_at']` und
`store.mark_authenticated(...)`.
- Bestätigung: `broker.send_to_connection(..., WSMessage(code=0,
msg='authenticated'))`.
5. Clientseitig verarbeitet `handleWsMessage()` Code 0:
- `state.authenticated = true`
- `flushWsOutbox()`
- `resolveWsAuthentication()`
- `syncPushRegistration()` (Token-Aktualität)
6. `waitForWsAuthentication()` wartet bei einem Wake bis zu
`PUSH_WAKE_AUTH_TIMEOUT_MS` (25 s) auf diesen Schritt.
### Phase 5 – Heartbeat und Offline-Erkennung
- `cmbnet/ws/heartbeat.py:HeartbeatManager._send_heartbeat()` sendet Code 1
an authentifizierte Verbindungen.
- Der Client antwortet in `handleWsMessage()` mit Code 2 (`pong`).
- `HeartbeatManager._check_presence()` bzw.
`broker.check_client_liveness(timeout)` schließt Verbindungen ohne
Lebenszeichen nach `CMBNET_WS_CLIENT_OFFLINE_TIMEOUT_SECONDS` (Default 180).
- `store.touch_worker()`, `store.mark_orphan_clients_disconnected()` und
`store.cleanup_worker_registry()` erkennen Clients aus beendeten
Worker-Prozessen.
### Phase 6 – Manueller Wake (Dispatcher-Button)
1. Desktop: `static/js/views/dispatcher.js:wakeMobileClients()`
Mobile Dispatcher: `static/js/views/mobile.js:wakeMobileClientsFromUi()`
2. Beide senden `POST /<tenant>/api/push/wake` (optional mit `group_id`).
3. Serverseitig `cmbnet/api/push.py:wake_mobile_clients()`:
- `public_fcm_config()` prüft die öffentliche Web-Konfiguration.
- `store.mobile_push_stats(tenant_id)` liefert `valid_tokens` und
`connected`.
- `fcm_service.server_status()` prüft die tatsächliche Sendefähigkeit
(`_server_config()` und `_ensure_app()`).
Ist der Server nicht sendebereit, antwortet der Endpunkt mit HTTP 503
und einer konkreten Fehlermeldung.
- `store.offline_mobile_wake_candidates(..., include_connected=True,
re_wake_before=None)` wählt **alle** mobilen Clients mit gültigem Token.
Ein ausdrücklicher Klick ignoriert die automatische `last_wake_at`-
Drosselung.
- `fcm_service.send_wake(tokens, reason='manual')`
4. `send_wake()`:
- `_ensure_app()` initialisiert `firebase-admin` einmalig mit
`credentials.Certificate(...)` und `firebase_admin.initialize_app(...,
name='cmbnet')`.
- baut `messaging.MulticastMessage(tokens=..., data={'type':
'cmbnet-wake','reason':...}, android=messaging.AndroidConfig(priority=
'high', ttl=...), webpush=messaging.WebpushConfig(headers={'Urgency':
'high','TTL':...}))`.
- ruft `_send_batch()` auf.
5. `_send_batch()` ruft
`messaging.send_each_for_multicast(message)` auf. Das ist ein
HTTPS-Aufruf an die FCM-HTTP-v1-API von Google.
6. Für jede Antwort:
- Erfolg → `sent_tokens`
- Fehler → `errors` mit Fehlerklasse und -text (Token nur als
Fingerabdruck) und ggf. `invalid_tokens` bei `UnregisteredError`,
`INVALID_ARGUMENT` oder `SENDER_ID_MISMATCH`.
7. Zurück in `wake_mobile_clients()`:
- `store.set_client_wake_sent(...)` für erfolgreiche Tokens
- `store.mark_push_token_invalid(...)` für von FCM abgelehnte Tokens
- Logzeilen:
- `FCM-Wake manuell: tenant=… tokens=… verbunden=… candidates=… sent=… failed=…`
- `FCM-Signal abgelehnt: token=<fingerprint> error=<Klasse>: <Text>`
- JSON-Antwort mit `candidates`, `sent`, `failed`, `valid_tokens`,
`connected`, `errors`, `error`.
### Phase 7 – Zustellung über Firebase
1. Google FCM nimmt die Nachricht an und stellt sie an das Gerät zu.
- Android/Desktop-Browser: direkt über den FCM-Web-Push-Endpunkt.
- iOS/iPadOS: über APNs; Voraussetzung ist eine installierte PWA
(Home-Bildschirm), iOS/iPadOS 16.4+ und die in der Firebase-Konsole
hinterlegte APNs-Konfiguration.
2. Ist die PWA im Hintergrund oder geschlossen, empfängt der Service Worker
die Nachricht über `fcmMessaging.onBackgroundMessage(...)`.
3. Ist die PWA im Vordergrund, empfängt die Seite die Nachricht über
`messaging.onMessage(...)` in `initFirebasePush()`.
### Phase 8 – Reaktion des Clients
**Hintergrund / Service Worker:**
1. `handleFcmWake(reason)`
2. `wakeOpenClients(reason)`:
- `self.clients.matchAll({type:'window', includeUncontrolled:true})`
- `client.postMessage({type:'cmbnet-wake', reason}, [channel.port2])`
- wartet über `MessageChannel` bis zu `FCM_WAKE_ACK_TIMEOUT_MS` (20 s)
auf die Antwort der Seite.
3. Ist kein Fenster offen: `showWakeNotification(reason)` →
`self.registration.showNotification(...)` mit `data.url =
fcmConfig.wakeUrl` (`/wake`).
**Seite:**
1. `initPushWakeListener()` empfängt die Service-Worker-Nachricht.
2. `handlePushWake(reason, port)`:
- `connectWebSocket()`
- `waitForWsAuthentication()`
- bei Gruppen-View und aktivierter Positionsübertragung:
`sendWakePosition()` → `navigator.geolocation.getCurrentPosition(...)`
bzw. `sendAutomaticPosition(true)` → `sendOwnPosition(...)`
- `port.postMessage({ok, positionSent, reason})`
**Klick auf die Benachrichtigung:**
- `notificationclick` im Service Worker fokussiert ein bestehendes Fenster
und sendet `{type:'cmbnet-wake', reason:'notification'}` oder öffnet
`fcmConfig.wakeUrl` (`/wake`).
- `cmbnet/__init__.py:wake()` leitet auf `views.index` mit dem Mandanten aus
der Session um.
### Fehlerbild „2 Fehler bei 2 Empfängern“
Das bedeutet: Es wurden **2 gültige Tokens als Empfänger gefunden**, aber
FCM hat beide Sendungen abgelehnt (`sent = 0`, `failed = 2`). Es fehlen also
keine Tokens. Typische Ursachen:
| Fehlertext (Auszug) | Bedeutung |
| --- | --- |
| `SenderIdMismatchError` / `SENDER_ID_MISMATCH` | Token gehört zu einem anderen Firebase-Projekt als der Service-Account. |
| `UnregisteredError` / `UNREGISTERED` | Token ist nicht mehr gültig (App gelöscht, Token rotiert, Projekt gewechselt). |
| `InvalidArgumentError` / `INVALID_ARGUMENT` | Tokenformat, VAPID-Schlüssel oder Web-Push-Konfiguration passt nicht. |
| `ThirdPartyAuthError`, `PermissionDenied` | Service-Account darf nicht senden, FCM-API im Projekt nicht aktiviert oder Projekt-ID falsch. |
| `QuotaExceededError`, `InternalError`, `Unavailable` | temporäres FCM-/Netzwerkproblem; später erneut versuchen. |
| `FirebaseError: … credential …` | Service-Account ungültig, abgelaufen oder falsche Datei. |
Seit der erweiterten Diagnose stehen die konkreten Fehler in der Antwort
(`errors[].error`) und im Serverlog (`FCM-Signal abgelehnt: token=…
error=…`). Die Oberfläche zeigt den ersten Fehler direkt an.
### Datenbankbezug
- `ws_clients`: `client_id`, `account_id`, `client_type`, `worker_id`,
`connected_at`, `disconnected_at`, `authenticated`, `last_wake_at`,
`last_wake_reason`.
- `ws_push_tokens`: `tenant_id`, `client_id`, `account_id`, `token`,
`client_type`, `platform`, `auto_position`, `invalid`, `updated_at`.
- `ws_workers`: `worker_id`, `started_at`, `heartbeat_at`.
- `ws_tokens`: Einmal-Token für den Code-0-Handshake.
- `ws_client_queue`: persistente Nachrichtenqueue je Client.
## Teil B – Reverse Proxy und CORS
### Kurzfassung
Für Firebase ist **keine besondere CORS-Konfiguration am Reverse Proxy
erforderlich**. Der Browser spricht direkt mit den Google-Endpunkten; der
Reverse Proxy liefert nur die eigene Anwendung aus. CORS wäre nur relevant,
wenn die PWA und die API auf unterschiedlichen Origins liegen oder wenn
Firebase-Aufrufe über den eigenen Proxy geleitet werden – beides ist nicht
vorgesehen.
Wichtig sind dagegen:
1. HTTPS,
2. korrekt ausgelieferter Service Worker,
3. WebSocket-Unterstützung,
4. passende Content-Security-Policy,
5. Ausgangszugriff des Servers zu Google.
### HTTPS und Sicherheitskontext
- Service Worker, Web Push und `getToken()` benötigen einen sicheren
Kontext. Außer `localhost` ist HTTPS Pflicht.
- Das TLS-Zertifikat muss vom Client akzeptiert werden; ein selbstsigniertes
Zertifikat verhindert die Service-Worker-Registrierung.
### Service Worker
- `/sw.js` muss unter der App-Wurzel erreichbar sein, damit der Scope die
App abdeckt. Bei einem Prefix (z. B. `/cmbnet/`) über
`SCRIPT_NAME`/`X-Forwarded-Prefix` den Pfad unverändert weiterleiten.
- MIME-Typ: `application/javascript` (setzt die Anwendung bereits).
- `Cache-Control: no-cache` muss erhalten bleiben. Ein CDN oder Proxy darf
`sw.js` nicht lange cachen, sonst bleiben alte Client-Versionen aktiv.
- Wird der Scope über ein Unterverzeichnis hinaus benötigt, kann der Header
`Service-Worker-Allowed: /` gesetzt werden. Die Anwendung liefert den
Worker bereits an der Wurzel aus; normalerweise ist das nicht nötig.
- `/fcm-sw-config.js` wird per `importScripts` geladen. Auch diese Datei
muss ohne langes Caching ausgeliefert werden (die Anwendung setzt
`Cache-Control: no-cache`).
- Der Service Worker lädt Skripte von `https://www.gstatic.com`. Ein Proxy
muss das nicht übernehmen; der Browser lädt sie direkt. Eine CSP muss
diese Quelle erlauben (siehe unten).
### WebSocket
Der WebSocket ist zwar nicht Teil von FCM, aber Voraussetzung für die
Wake-Reaktion:
- `/<tenant>/ws` muss als WebSocket durchgereicht werden:
`Upgrade: websocket`, `Connection: Upgrade`.
- Buffering im Proxy muss für diese Route deaktiviert sein.
- Lese-/Idle-Timeouts müssen über dem Heartbeat-Intervall liegen
(`CMBNET_WS_HEARTBEAT_INTERVAL`, Default 60 s). Ein zu kurzer Proxy-Timeout
trennt die Verbindung ständig neu.
- HTTP/1.1 für den Upgrade; HTTP/2 zum Backend ist für WebSocket nicht
erforderlich.
Beispiel nginx:
```nginx
location /cmbnet/ws {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Prefix /cmbnet;
proxy_buffering off;
proxy_read_timeout 3600s;
}
location = /cmbnet/sw.js {
proxy_pass http://127.0.0.1:8000;
add_header Cache-Control "no-cache";
}
location = /cmbnet/fcm-sw-config.js {
proxy_pass http://127.0.0.1:8000;
add_header Cache-Control "no-cache";
}
```
### Content-Security-Policy
Falls eine CSP gesetzt wird, müssen mindestens erlaubt sein:
- `script-src 'self' https://www.gstatic.com`
(Firebase-Compat-SDK im Seitenkontext und im Service Worker)
- `connect-src 'self' https://*.googleapis.com https://*.google.com
https://fcmregistrations.googleapis.com
https://firebaseinstallations.googleapis.com
https://www.gstatic.com`
- `worker-src 'self'` (Service Worker)
- `img-src 'self' data:` (Benachrichtigungssymbol)
- `frame-src` ist für FCM nicht erforderlich.
Nicht empfohlen:
- `Cross-Origin-Embedder-Policy: require-corp` kann Service Worker und
Push-Registrierung behindern.
- `Cross-Origin-Opener-Policy` sollte die PWA nicht isolieren, wenn
Firebase-Installationen genutzt werden; `same-origin-allow-popups` ist
unkritisch.
- `Permissions-Policy` darf `geolocation` nicht sperren, wenn die mobile View
beim Wake ein Positionsupdate senden soll.
### CORS im Detail
- **Browser → Google:** Die Firebase-JS-SDK-Aufrufe (`getToken`,
Installation, Token-Registrierung) gehen direkt an Google. Google liefert
die passenden CORS-Header. Der eigene Reverse Proxy ist daran nicht
beteiligt und muss keine CORS-Header setzen.
- **Browser → eigene API:** `/push/register`, `/push/wake`,
`/auth/ws-token` und `/ws` sind same-origin. CORS ist nicht nötig.
- **Server → Google:** `firebase-admin` sendet serverseitig an
`oauth2.googleapis.com` und `fcm.googleapis.com`. Das ist kein
Browser-CORS, sondern ein normaler HTTPS-Aufruf. Der Server braucht
Ausgangszugriff (Firewall/Proxy) zu diesen Hosts.
- Wenn die PWA und die API bewusst auf getrennten Origins laufen, müssen
Credentials-CORS (`Access-Control-Allow-Origin` exakt, `Vary: Origin`,
`Access-Control-Allow-Credentials: true`) und Cookie-Attribute
(`SameSite=None; Secure`) konfiguriert werden. Das ist nicht der
Standardaufbau dieses Projekts.
- Firebase-Aufrufe sollten **nicht** über den eigenen Reverse Proxy
geleitet werden. Das würde CORS, `Authorization`-Header und
Zertifikatsvertrauen unnötig verkomplizieren.
### Ausgangsverbindungen des Servers
Der Server muss per HTTPS erreichen können:
- `fcm.googleapis.com` (Nachrichtenversand)
- `oauth2.googleapis.com` (Service-Account-Token)
- `firebaseinstallations.googleapis.com` und
`fcmregistrations.googleapis.com` (nur Browser, nicht Server)
- `www.gstatic.com` (nur Browser)
Wenn der Server einen HTTP-Proxy für ausgehende Verbindungen benötigt,
müssen `HTTPS_PROXY`/`HTTP_PROXY` (und ggf. `NO_PROXY`) für den
WSGI-Prozess gesetzt sein. Die CA des ausgehenden Proxys muss im
Zertifikatsspeicher des Servers liegen. Eine falsche Systemzeit (JWT-
Signatur) führt ebenfalls zu Authentifizierungsfehlern.
### Weitere Hinweise
- `POST /push/register` und `POST /push/wake` nicht durch ein zu strenges
Rate-Limit blockieren; der Wake-Button ist eine bewusste Benutzeraktion.
- Cookies der Session müssen durch den Proxy unverändert weitergegeben
werden, sonst schlägt `login_required` fehl.
- `Vary`-Header und Kompression sind für FCM unkritisch; die
Service-Worker-Dateien sollten aber nicht komprimiert/umgeschrieben
werden.
- Für iOS muss in der Firebase-Konsole ein APNs-Schlüssel hinterlegt sein.
Das ist keine Reverse-Proxy-Einstellung, sondern eine
Firebase-Projektvoraussetzung.
+9 -1
View File
@@ -3669,9 +3669,17 @@ async function wakeMobileClients() {
true true
); );
} else { } else {
const firstError = result.error
|| (Array.isArray(result.errors)
&& result.errors[0]
&& result.errors[0].error)
|| '';
const detail = firstError
? ` Grund: ${String(firstError).slice(0, 240)}`
: '';
setStreetSearchStatus( setStreetSearchStatus(
`Wecken fehlgeschlagen: ${Number(result.failed) || 0} Fehler ` `Wecken fehlgeschlagen: ${Number(result.failed) || 0} Fehler `
+ `bei ${candidates} Empfängern.`, + `bei ${candidates} Empfängern.${detail}`,
true true
); );
} }
+9 -1
View File
@@ -680,9 +680,17 @@ async function wakeMobileClientsFromUi() {
+ `(registriert: ${tokens}, verbunden: ${connected}).` + `(registriert: ${tokens}, verbunden: ${connected}).`
); );
} else { } else {
const firstError = result.error
|| (Array.isArray(result.errors)
&& result.errors[0]
&& result.errors[0].error)
|| '';
const detail = firstError
? ` Grund: ${String(firstError).slice(0, 240)}`
: '';
showMobileToast( showMobileToast(
`Wecken fehlgeschlagen: ${Number(result.failed) || 0} Fehler ` `Wecken fehlgeschlagen: ${Number(result.failed) || 0} Fehler `
+ `bei ${candidates} Empfängern.`, + `bei ${candidates} Empfängern.${detail}`,
true true
); );
} }