Web-Tier auf Cloudflare Workers

Das Design ist in Abschnitt 6 von docs/architecture/23-ops.md beschrieben. Workers betreiben einen eingeschränkten Web-Tier. Funktionsgleichheit auf Workers ist nicht Teil des Umfangs (Abschnitt 12 des PRD): Was dieses Ziel nicht unterstützt, wird beim Start mit Angabe des Namens abgelehnt.

Status in dieser Version

Die Konfiguration ist vorhanden (apps/web/wrangler.jsonc, das Nitro-Preset cloudflare-module, die Hyperdrive-Brücke und die Startprüfungen). Ein Worker benötigt S3-kompatiblen Speicher für R2 (QUIRE_STORAGE_DRIVER=s3), einen Realtime-Treiber über Anfragen hinweg (QUIRE_REALTIME_DRIVER=durable_objects oder centrifugo), einen gemeinsam genutzten Cache (QUIRE_CACHE_DRIVER=postgres oder valkey) und einen HTTP-E-Mail-Anbieter. Fehlen diese Voraussetzungen, verweigert der Worker den Start und nennt jede Einstellung im Protokoll. Der Durable-Objects-Treiber ist ein Client des Realtime-Workers unter apps/realtime-worker (ein Durable Object pro Kanal für Fan-out, Präsenz und Verlauf, eines pro Person für Verbindungsabbrüche). Stellen Sie ihn wie unten beschrieben daneben bereit oder verwenden Sie Centrifugo.

Komponenten

Komponente	Auf Cloudflare
`web`	Ein Worker mit `nodejs_compat`
Postgres	Extern, erreichbar über Hyperdrive: `HYPERDRIVE` für die Anwendungsrolle, `REPORT_HYPERDRIVE` für die Report-Rolle derselben physischen Datenbank. Beim Start kopiert der Web-Tier jede Verbindungszeichenfolge nach `DATABASE_URL` und `QUIRE_REPORT_DATABASE_URL`
Dateien	R2 über seine S3-API (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); die Bindung `FILES` hängt den Bucket ein
Hintergrundjobs	pg-boss über Hyperdrive, wenn ein Job zusammen mit einem Schreibvorgang eingereiht werden muss. Mit `QUIRE_QUEUE_DRIVER=cloudflare` auf dem ergänzenden Worker laufen einfache Jobs (ungeordnete Benachrichtigungs- und Webhook-Zustellungen) stattdessen über Cloudflare Queues, sodass Postgres dafür nicht abgefragt wird. Der ergänzende Worker führt beides aus
Realtime	Der Realtime-Worker `apps/realtime-worker` mit Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg	Ein ergänzender Container-Host. Ein Worker kann diese nicht ausführen
Tracing	Workers Observability, in `wrangler.jsonc` aktiviert

REPORT_HYPERDRIVE stellt die Report-Rolle für die durch HYPERDRIVE bezeichnete physische Datenbank bereit. Wie unten beschrieben, unterstützt dieses Ziel keine Mandanten mit eigenen zusätzlichen physischen Datenbanken.

Was dieses Ziel nicht unterstützt

Beim Start abgelehnt; alle Probleme werden gemeinsam aufgeführt:

Kein SMTP. Verwenden Sie in QUIRE_EMAIL_PROVIDER_CONFIG einen HTTP-Anbieter.
Kein lokaler Datenträger. QUIRE_STORAGE_DRIVER muss Objektspeicher angeben.
Kein In-Process-Realtime oder -Cache. Workers teilen keinen Speicher zwischen Anfragen, daher werden QUIRE_REALTIME_DRIVER=inprocess und QUIRE_CACHE_DRIVER=memory abgelehnt.
Kein ClamAV, Gotenberg oder ffmpeg im Worker. CLAMAV_URL, GOTENBERG_URL und FFMPEG_PATH werden abgelehnt, wenn sie auf dem Worker gesetzt sind. Legen Sie sie stattdessen auf dem ergänzenden Worker fest.
Keine Organisationen mit dedizierter Datenbank. Die Hyperdrive-Bindungen eines Workers stehen beim Bereitstellen fest, daher erhält eine Organisation mit eigener Datenbank eine klare Seite „hier nicht verfügbar“. Betreiben Sie sie mit Compose oder Vercel.

Außerdem wird eine Einschränkung nicht abgelehnt, muss aber bekannt sein: Prerendering und inkrementelle statische Regenerierung funktionieren auf Workers nicht, ungeachtet der Dokumentation des Frameworks. Jede Route wird pro Anfrage gerendert.

Halten Sie Transaktionen auf diesem Ziel kurz und führen Sie innerhalb einer Transaktion niemals einen Netzwerkaufruf aus: Wenn eine Verbindung in den Pool zurückkehrt, setzt Hyperdrive den Sitzungszustand zurück. Deshalb wird der Mandantenkontext für jede Transaktion festgelegt.

Bereitstellung

Erstellen Sie die Ressourcen:

bun run --bun wrangler hyperdrive create quire-app --connection-string="postgres://quire_app:...@db.example.com:5432/quire"
bun run --bun wrangler hyperdrive create quire-report --connection-string="postgres://quire_report:...@db.example.com:5432/quire"
bun run --bun wrangler r2 bucket create quire-files
bun run --bun wrangler queues create quire-jobs

Tragen Sie die beiden Hyperdrive-IDs in apps/web/wrangler.jsonc ein.

Legen Sie die Secrets einzeln mit bun run --bun wrangler secret put <NAME> aus apps/web fest: QUIRE_SECRET_KEY, QUIRE_MASTER_KEY, QUIRE_EMAIL_PROVIDER_CONFIG, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, QUIRE_COLLAB_SIGNING_KEY, QUIRE_REALTIME_WORKER_SECRET. Einfache Einstellungen (QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, QUIRE_PLATFORM_DOMAINS, QUIRE_DATABASE_ID, S3_ENDPOINT, S3_BUCKET, QUIRE_COLLAB_URL) gehören in vars.

Erstellen Sie den Build und stellen Sie ihn aus apps/web bereit:

NITRO_PRESET=cloudflare-module bun run build
bun run --bun wrangler deploy

Stellen Sie den Realtime-Worker mit QUIRE_REALTIME_WORKER_SECRET aus dem Web-Tier und dessen Token-Secret als QUIRE_REALTIME_TOKEN_SECRET bereit. Der Web-Tier signiert Realtime-Tokens mit seinem eigenen QUIRE_REALTIME_TOKEN_SECRET oder, wenn dieses nicht gesetzt ist, mit QUIRE_SECRET_KEY. Verwenden Sie also denselben Schlüssel wie der Web-Tier. Setzen Sie QUIRE_REALTIME_WORKER_URL im Web-Tier auf dessen Adresse:
```
cd apps/realtime-worker
bun run --bun wrangler secret put QUIRE_REALTIME_WORKER_SECRET
bun run --bun wrangler secret put QUIRE_REALTIME_TOKEN_SECRET
bun run --bun wrangler deploy
```
Erstellen Sie für einfache Jobs in Cloudflare Queues je eine Queue für jede einfache Warteschlange und legen Sie Folgendes auf dem ergänzenden Worker fest (ein API-Token mit Lese- und Schreibrechten für Queues):
```
bun run --bun wrangler queues create quire-events-notifications
bun run --bun wrangler queues create quire-events-notifications-dead
bun run --bun wrangler queues create quire-events-webhooks
bun run --bun wrangler queues create quire-events-webhooks-dead
```
QUIRE_QUEUE_DRIVER=cloudflare, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_QUEUES_TOKEN sowie QUIRE_QUEUE_PREFIX, falls das Präfix nicht quire- lautet.
Starten Sie den ergänzenden Host wie in Schritt 3 der Vercel-Anleitung. Migrationen werden dort vor jeder Worker-Bereitstellung ausgeführt.

Bei einer abgelehnten Konfiguration zeigt bun run --bun wrangler tail „The web tier did not start on cloudflare“ an, gefolgt von jeder zu ändernden Einstellung.