A capa web en Cloudflare Workers

O deseño descríbese na sección 6 de docs/architecture/23-ops.md. Workers executa unha versión reducida da capa web. A igualdade de funcións con Workers queda fóra do alcance (sección 12 do PRD): o destino rexeita ao iniciarse, e identifica polo nome, o que non pode facer.

Estado nesta versión

A configuración xa está preparada (apps/web/wrangler.jsonc, o preaxuste Nitro cloudflare-module, a ponte Hyperdrive e as comprobacións de inicio). Un Worker necesita almacenamento compatible con S3 mediante R2 (QUIRE_STORAGE_DRIVER=s3), un controlador de tempo real para varias peticións (QUIRE_REALTIME_DRIVER=durable_objects ou centrifugo), unha caché compartida (QUIRE_CACHE_DRIVER=postgres ou valkey) e un provedor HTTP de correo. Se faltan, o Worker non se inicia e o rexistro indica cada axuste pendente. O controlador Durable Objects é cliente do Worker de tempo real en apps/realtime-worker (un Durable Object por canle para distribución, presenza e historial, e un por persoa para desconexións); despregao tamén, como se indica máis abaixo, ou utiliza Centrifugo.

Compoñentes

Compoñente	En Cloudflare
`web`	Un Worker con `nodejs_compat`
Postgres	Externo, accesible mediante Hyperdrive: `HYPERDRIVE` para o rol da aplicación e `REPORT_HYPERDRIVE` para o rol de informes na mesma base de datos física. Ao iniciarse, a capa web copia cada cadea de conexión en `DATABASE_URL` e `QUIRE_REPORT_DATABASE_URL`
Ficheiros	R2, mediante a súa API S3 (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); a vinculación `FILES` conecta o bucket
Tarefas en segundo plano	pg-boss sobre Hyperdrive cando a tarefa debe engadirse cunha escritura. Se o traballador complementario utiliza `QUIRE_QUEUE_DRIVER=cloudflare`, as tarefas lixeiras (notificacións sen orde e entregas de webhooks) pasan por Cloudflare Queues, para que non se consulten esas tarefas en Postgres. O traballador complementario executa ambas as opcións
Tempo real	O Worker de tempo real, `apps/realtime-worker`, con Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg	Un host complementario de contedores. Non se poden executar nun Worker
Trazas	Observabilidade de Workers, activada en `wrangler.jsonc`

REPORT_HYPERDRIVE fornece o rol de informes para a base de datos física indicada por HYPERDRIVE. Este destino non serve inquilinos vinculados a outras bases de datos físicas, como se explica máis abaixo.

Limitacións deste destino

Rexeitamentos que se comunican ao iniciar, coa lista completa dos problemas:

Non admite SMTP. Utiliza un provedor HTTP en QUIRE_EMAIL_PROVIDER_CONFIG.
Non admite disco local. QUIRE_STORAGE_DRIVER debe indicar un almacén de obxectos.
Non admite tempo real nin caché na memoria do proceso. Workers non comparte memoria entre peticións e, polo tanto, rexeita QUIRE_REALTIME_DRIVER=inprocess e QUIRE_CACHE_DRIVER=memory.
Non executa ClamAV, Gotenberg nin ffmpeg no Worker. Rexeita CLAMAV_URL, GOTENBERG_URL e FFMPEG_PATH se se establecen no Worker; configúraos no traballador complementario.
Non admite organizacións con bases de datos dedicadas. As vinculacións Hyperdrive dun Worker quedan fixadas no momento do despregamento, polo que as organizacións coa súa propia base de datos ven unha páxina clara que indica que o servizo non está dispoñible aquí. Sírveas desde Compose ou Vercel.

Hai tamén unha limitación que non se rexeita pero que cómpre coñecer: a xeración previa e a rexeneración incremental estática non funcionan en Workers, diga o que diga a documentación da infraestrutura. Todas as rutas se renderizan en cada petición.

Neste destino, mantén curtas as transaccións e nunca as deixes abertas durante unha chamada de rede: Hyperdrive restablece o estado da sesión cando a conexión volve ao grupo, polo que o contexto do inquilino se establece en cada transacción.

Despregamento

Crea os recursos:

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

Introduce os dous ID de Hyperdrive en apps/web/wrangler.jsonc.

Establece os segredos un por un con bun run --bun wrangler secret put <NAME> desde apps/web: QUIRE_SECRET_KEY, QUIRE_MASTER_KEY, QUIRE_EMAIL_PROVIDER_CONFIG, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, QUIRE_COLLAB_SIGNING_KEY e QUIRE_REALTIME_WORKER_SECRET. As opcións sen segredo (QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, QUIRE_PLATFORM_DOMAINS, QUIRE_DATABASE_ID, S3_ENDPOINT, S3_BUCKET, QUIRE_COLLAB_URL) van en vars.

Compila e desprega desde apps/web:

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

Despregue o Worker de tempo real con QUIRE_REALTIME_WORKER_SECRET da capa web e o seu segredo de token como QUIRE_REALTIME_TOKEN_SECRET (a capa web asina os tokens de tempo real co seu propio QUIRE_REALTIME_TOKEN_SECRET ou con QUIRE_SECRET_KEY se aquel non se define; utiliza o que corresponda) e establece QUIRE_REALTIME_WORKER_URL na capa web co seu enderezo:
```
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
```
Para utilizar Cloudflare Queues nas tarefas lixeiras, crea unha cola para cada cola lixeira e establece estes axustes no traballador complementario (necesitarás un token da API con permisos de lectura e escritura para 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
```
Define QUIRE_QUEUE_DRIVER=cloudflare, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_QUEUES_TOKEN e QUIRE_QUEUE_PREFIX se non é quire-.
Configura o host complementario como se describe no paso 3 da guía de Vercel. As migracións execútanse alí antes de cada despregamento de Worker.

Se a configuración se rexeita, bun run --bun wrangler tail amosa «The web tier did not start on cloudflare» e, a continuación, cada axuste que hai que cambiar.