web tier در Cloudflare Workers

web tier محدودشدهٔ Quire را روی Cloudflare Workers اجرا کنید.

طرح در بخش ۶ از docs/architecture/23-ops.md آمده است. Workers نسخه‌ای محدود از web tier را اجرا می‌کنند. برابری کامل قابلیت‌ها در Workers خارج از محدوده است (بخش ۱۲ PRD): هر کاری که این مقصد نتواند انجام دهد هنگام راه‌اندازی، با نامش رد می‌شود.

وضعیت در این انتشار

پیکربندی آماده است (apps/web/wrangler.jsonc، preset نیتروی cloudflare-module، پل Hyperdrive و بررسی‌های هنگام راه‌اندازی). Worker برای R2 به ذخیره‌سازی سازگار با S3 نیاز دارد (QUIRE_STORAGE_DRIVER=s3)، driver بلادرنگ میان درخواست‌ها (QUIRE_REALTIME_DRIVER=durable_objects یا centrifugo)، cache مشترک (QUIRE_CACHE_DRIVER=postgres یا valkey) و ارائه‌دهندهٔ ایمیل HTTP. بدون این‌ها Worker آغاز نمی‌شود و گزارشش هر تنظیم را نام می‌برد. driver مربوط به Durable Objects مشتری realtime Worker در apps/realtime-worker است (برای پخش همگانی، حضور و تاریخچه برای هر کانال یک Durable Object و برای قطع‌اتصال‌ها به‌ازای هر شخص یکی)؛ مطابق ادامه آن را کنار Worker مستقر کنید یا از Centrifugo استفاده کنید.

اجزا

جزء	روی Cloudflare
`web`	یک Worker با `nodejs_compat`
Postgres	بیرونی و از راه Hyperdrive: `HYPERDRIVE` برای نقش برنامه و `REPORT_HYPERDRIVE` برای نقش گزارش در همان پایگاه فیزیکی. web tier هنگام آغاز هر رشتهٔ اتصال را به `DATABASE_URL` و `QUIRE_REPORT_DATABASE_URL` کپی می‌کند
فایل‌ها	R2 از راه S3 API (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`)؛ binding با نام `FILES` مخزن را وصل می‌کند
کارهای پس‌زمینه	کارهایی که باید با نوشتن صف شوند از pg-boss روی Hyperdrive می‌گذرند. اگر worker همکار `QUIRE_QUEUE_DRIVER=cloudflare` داشته باشد، کارهای سبک (اعلان‌های بی‌ترتیب و تحویل وب‌هوک) از Cloudflare Queues می‌گذرند و Postgres برایشان پول نمی‌شود. worker همکار هر دو را اجرا می‌کند
بلادرنگ	realtime Worker، یعنی `apps/realtime-worker`، با Durable Objects
`worker`، `scheduler`، `collab`، `content`، ClamAV، Gotenberg و ffmpeg	میزبان container همکار؛ Worker نمی‌تواند آن‌ها را اجرا کند
رهگیری	مشاهده‌پذیری Workers که در `wrangler.jsonc` فعال شده است

REPORT_HYPERDRIVE نقش گزارش را برای پایگاه فیزیکی‌ای فراهم می‌کند که HYPERDRIVE نام می‌برد. همان‌طور که پایین‌تر آمده، این مقصد برای tenantهای سنجاق‌شده به پایگاه فیزیکی افزوده خدمت نمی‌دهد.

کارهایی که این مقصد نمی‌تواند انجام دهد

هنگام آغاز همهٔ مشکلات یک‌جا فهرست و پیکربندی رد می‌شود:

SMTP وجود ندارد. از ارائه‌دهندهٔ HTTP در QUIRE_EMAIL_PROVIDER_CONFIG استفاده کنید.
دیسک محلی وجود ندارد. QUIRE_STORAGE_DRIVER باید به ذخیره‌سازی شیء اشاره کند.
بلادرنگ یا cache درون‌فرایندی وجود ندارد. حافظه میان درخواست‌ها مشترک نیست، پس QUIRE_REALTIME_DRIVER=inprocess و QUIRE_CACHE_DRIVER=memory رد می‌شوند.
Worker نمی‌تواند ClamAV، Gotenberg یا ffmpeg را اجرا کند. اگر CLAMAV_URL، GOTENBERG_URL و FFMPEG_PATH را روی Worker بگذارید رد می‌شوند؛ آن‌ها را روی worker همکار تنظیم کنید.
سازمان‌های دارای پایگاه اختصاصی پشتیبانی نمی‌شوند. bindingهای Hyperdrive مربوط به Worker هنگام استقرار ثابت‌اند، پس سازمان دارای پایگاه خودش صفحهٔ روشنِ «اینجا در دسترس نیست» می‌بیند. آن را از Compose یا Vercel ارائه کنید.

یک نکته هم هست که رد نمی‌شود اما باید بدانید: پیش‌رندر و بازتولید افزایشی ایستا روی Workers کار نمی‌کنند، هرچه مستندات چارچوب بگویند. هر مسیر به‌ازای هر درخواست رندر می‌شود.

در این مقصد transactionها را کوتاه نگه دارید و هیچ transactionای را میان فراخوانی‌های شبکه باز نگذارید: Hyperdrive هنگام بازگرداندن اتصال به pool، وضعیت نشست را پاک می‌کند؛ بنابراین زمینهٔ tenant به‌ازای هر transaction تنظیم می‌شود.

استقرار

منبع‌ها را بسازید:

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

realtime Worker را با QUIRE_REALTIME_WORKER_SECRET مربوط به web tier و راز tokenاش به‌شکل QUIRE_REALTIME_TOKEN_SECRET مستقر کنید (web tier tokenهای realtime را با QUIRE_REALTIME_TOKEN_SECRET خودش یا، اگر تنظیم نشده باشد، با QUIRE_SECRET_KEY امضا می‌کند؛ هرکدام را که به کار می‌برد انتخاب کنید) و QUIRE_REALTIME_WORKER_URL را در web tier روی نشانی‌اش بگذارید:
```
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، برای هر صف سبک یک queue بسازید و آن‌ها را روی worker همکار تنظیم کنید (token 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 اجرا کنید. migrationها پیش از هر استقرار Worker همان‌جا اجرا می‌شوند.

پیکربندی ردشده در bun run --bun wrangler tail با «The web tier did not start on cloudflare» نمایش می‌یابد و پس از آن هر تنظیمی را که باید تغییر کند فهرست می‌کند.