Уеб слоят в Cloudflare Workers

Изпълнявайте ограничен уеб слой на Quire в Cloudflare Workers.

Проектът е описан в раздел 6 на docs/architecture/23-ops.md. Workers изпълняват ограничен уеб слой на Quire. Пълното съответствие на възможностите на Workers не е цел (раздел 12 на PRD): при стартиране целта отказва неподдържаните възможности и посочва причината.

Състояние в тази версия

Конфигурацията е подготвена (apps/web/wrangler.jsonc, Nitro preset cloudflare-module, Hyperdrive мостът и проверките при стартиране). На Worker са нужни съвместимо със S3 хранилище за R2 (QUIRE_STORAGE_DRIVER=s3), драйвер за реално време между заявките (QUIRE_REALTIME_DRIVER=durable_objects или centrifugo), споделен кеш (QUIRE_CACHE_DRIVER=postgres или valkey) и HTTP доставчик на поща. Без тях Worker отказва стартиране, а журналът му посочва всяка настройка. Драйверът Durable Objects е клиент на Worker за реално време в apps/realtime-worker (по един Durable Object на канал за разпращане, присъствие и история, и по един на човек за прекъсвания); разгърнете го наблизо, както е описано по-долу, или използвайте Centrifugo.

Компоненти

Компонент	В Cloudflare
`web`	Worker с `nodejs_compat`
Postgres	Външна база, достъпвана през Hyperdrive: `HYPERDRIVE` за ролята на приложението, `REPORT_HYPERDRIVE` за ролята на отчетите в същата физическа база. При стартиране уеб слоят копира всеки низ за връзка в `DATABASE_URL` и `QUIRE_REPORT_DATABASE_URL`
Файлове	R2 през неговия S3 API (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); свързването `FILES` прикача кофата
Фонови задачи	pg-boss през Hyperdrive, когато задача трябва да бъде добавена заедно със запис. Когато на придружаващия worker е зададено `QUIRE_QUEUE_DRIVER=cloudflare`, леките задачи (несортирани известия и доставки на уебкуки) се изпълняват през Cloudflare Queues и затова Postgres не се проверява периодично. Придружаващият worker изпълнява и двете системи
Реално време	Worker за реално време `apps/realtime-worker` с Durable Objects
`worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg	Придружаващ хост с контейнери. Worker не може да ги изпълнява
Проследяване	Наблюдаемост на Workers, активирана в `wrangler.jsonc`

REPORT_HYPERDRIVE предоставя ролята за отчети за физическата база, посочена чрез HYPERDRIVE. Тази цел не обслужва организации, фиксирани към допълнителни физически бази, както е описано по-долу.

Възможности, които тази цел не поддържа

При стартиране се отказват всички проблемни настройки наведнъж:

Няма SMTP. Използвайте HTTP доставчик в QUIRE_EMAIL_PROVIDER_CONFIG.
Няма локален диск. QUIRE_STORAGE_DRIVER трябва да указва хранилище за обекти.
Няма реално време или кеш в процеса. Workers не споделят памет между заявките, затова се отказват QUIRE_REALTIME_DRIVER=inprocess и QUIRE_CACHE_DRIVER=memory.
Няма ClamAV, Gotenberg или ffmpeg в Worker. Настройки CLAMAV_URL, GOTENBERG_URL и FFMPEG_PATH, зададени за Worker, се отхвърлят; задайте ги на придружаващия worker.
Няма организации със самостоятелни бази данни. Hyperdrive свързванията на Worker се фиксират при разгръщане, затова организация със собствена база получава ясна страница „тук не е налично“. Обслужвайте я чрез Compose или Vercel.

Има и едно неотказано ограничение, което трябва да се знае: предварителното рендиране и инкременталното генериране на статични страници не работят в Workers, независимо от документацията на рамката. Всеки маршрут се рендира при всяка заявка.

За тази цел дръжте транзакциите кратки и не ги оставяйте отворени по време на мрежово повикване: Hyperdrive нулира състоянието на сесията, когато връзка се върне в пула, затова контекстът на клиента се задава за всяка транзакция.

Разгръщане

Създайте ресурсите:

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

Запишете двата Hyperdrive идентификатора в apps/web/wrangler.jsonc.

Задайте тайните поотделно чрез bun run --bun wrangler secret put <NAME> от apps/web: 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. Обикновените настройки (QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN, QUIRE_PLATFORM_DOMAINS, QUIRE_DATABASE_ID, S3_ENDPOINT, S3_BUCKET, QUIRE_COLLAB_URL) се задават в vars.

Компилирайте и разгърнете от apps/web:

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

Разгърнете Worker за реално време със QUIRE_REALTIME_WORKER_SECRET на уеб слоя и тайния токен като QUIRE_REALTIME_TOKEN_SECRET (уеб слоят подписва токени за реално време със собствения си QUIRE_REALTIME_TOKEN_SECRET, а ако той не е зададен — с QUIRE_SECRET_KEY, затова използвайте съответната стойност) и задайте QUIRE_REALTIME_WORKER_URL на уеб слоя като неговия адрес:
```
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
```
За леки задачи през Cloudflare Queues създайте отделна опашка за всяка от тях и задайте тези стойности на придружаващия worker (API токенът трябва да има права за четене и запис в 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 и QUIRE_QUEUE_PREFIX, ако не използвате quire-.
Стартирайте придружаващия хост според стъпка 3 от ръководството за Vercel. Миграциите се изпълняват там преди всяко разгръщане на Worker.

Отхвърлена конфигурация се показва в bun run --bun wrangler tail като „The web tier did not start on cloudflare“, след което са изброени настройките за корекция.