Cloudflare Workers 위의 웹 계층

설계는 docs/architecture/23-ops.md 6절입니다. Workers는 축소된 웹 계층을 실행합니다. Workers에서의 기능 동등성은 범위 밖입니다(PRD 12절). 이 타깃이 할 수 없는 것은 시작할 때 이름을 밝히며 거부됩니다.

이번 릴리스의 상태

설정은 준비되어 있습니다(apps/web/wrangler.jsonc, cloudflare-module Nitro 프리셋, Hyperdrive 브리지, 시작 점검). Worker에는 R2용 S3 호환 저장소 (QUIRE_STORAGE_DRIVER=s3), 요청 전반의 실시간 드라이버 (QUIRE_REALTIME_DRIVER=durable_objects 또는 centrifugo), 공유 캐시 (QUIRE_CACHE_DRIVER=postgres 또는 valkey), HTTP 이메일 공급자가 필요합니다. 없으면 Worker는 시작을 거부하고 로그에 각 설정을 명시합니다. Durable Objects 드라이버는 apps/realtime-worker의 실시간 Worker를 클라이언트로 사용합니다(채널마다 하나의 Durable Object가 팬아웃·프레즌스·히스토리를, 사람마다 하나가 끊김을 담당합니다). 아래와 같이 함께 배포하거나 Centrifugo를 사용하세요.

구성 요소

REPORT_HYPERDRIVE는 HYPERDRIVE가 가리키는 물리 데이터베이스의 리포트 역할을 제공합니다. 이 타깃은 아래에 설명한 대로 추가 물리 데이터베이스에 고정된 테넌트를 서비스하지 않습니다.

이 타깃이 할 수 없는 것

시작 시 거부되며, 모든 문제를 한 번에 나열합니다.

• SMTP 없음. QUIRE_EMAIL_PROVIDER_CONFIG에 HTTP 공급자를 사용하세요.
• 로컬 디스크 없음. QUIRE_STORAGE_DRIVER는 객체 저장소를 지정해야 합니다.
• 인프로세스 실시간·캐시 없음. Worker는 요청 사이에 메모리를 공유하지 않으므로 QUIRE_REALTIME_DRIVER=inprocess와 QUIRE_CACHE_DRIVER=memory는 거부됩니다.
• Worker에 ClamAV, Gotenberg, ffmpeg 없음. Worker에 설정된 CLAMAV_URL, GOTENBERG_URL, FFMPEG_PATH는 거부됩니다. 대신 동반 워커에 설정하세요.
• 전용 데이터베이스 조직 없음. Worker의 Hyperdrive 바인딩은 배포 시점에 고정되므로 자체 데이터베이스를 가진 조직은 명확한 “여기서는 사용할 수 없습니다” 페이지를 받습니다. Compose나 Vercel에서 서비스하세요.

거부되지는 않지만 알아야 할 한 가지: 프리렌더링과 증분 정적 재생성은 Workers에서 동작하지 않습니다. 프레임워크 문서가 뭐라고 하든 모든 라우트는 요청마다 렌더링됩니다.

이 타깃에서는 트랜잭션을 짧게 유지하고 네트워크 호출을 가로질러 절대 유지하지 마세요. Hyperdrive는 연결이 풀로 돌아갈 때 세션 상태를 초기화하므로 테넌트 컨텍스트는 트랜잭션마다 설정됩니다.

배포

1. 자원을 만드세요.

   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 ID를 apps/web/wrangler.jsonc에 넣으세요.
2. 시크릿을 하나씩 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에 넣습니다.
3. apps/web에서 빌드하고 배포하세요.

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

4. 실시간 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

5. Cloudflare Queues의 가벼운 작업을 위해서는 가벼운 큐마다 하나씩 큐를 만들고, 동반 워커에 다음을 설정하세요(Queues 읽기·쓰기가 있는 API 토큰).

   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-)이 아닐 때만 설정합니다.
6. Vercel 가이드의 3단계처럼 동반 호스트를 실행하세요. 마이그레이션은 각 배포 전에 거기서 실행됩니다.

거부된 설정은 bun run --bun wrangler tail에서 “The web tier did not start on cloudflare”로 보이고, 이어서 바꿀 설정이 나옵니다.