Вэб-узровень на Cloudflare Workers

Запускайце абмежаваны вэб-узровень Quire на Cloudflare Workers.

Архітэктура апісана ў раздзеле 6 docs/architecture/23-ops.md. Workers запускаюць абмежаваны вэб-узровень. Поўная адпаведнасць магчымасцей на Workers не ўваходзіць у задачу (PRD, раздзел 12): пры запуску платформа называе і адхіляе тое, чаго яна не можа.

Стан у гэтым выпуску

Канфігурацыя гатовая (apps/web/wrangler.jsonc, перадусталёўка Nitro 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 праз API S3 (`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-.
Запусціце дапаможны хост як у даведніку Vercel, крок 3. Міграцыі запускаюцца там перад кожным разгортваннем Worker.

Калі канфігурацыя адхілена, bun run --bun wrangler tail пакажа “The web tier did not start on cloudflare” і пералік параметраў для змены.