---
title: "Vercel 위의 웹 계층"
description: "동반 워커와 함께 Quire 웹 계층을 Vercel에서 실행하기."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/ko/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel 위의 웹 계층

<span id="the-web-tier-on-vercel"></span>

설계는 `docs/architecture/23-ops.md` 5절입니다. Vercel은 웹 계층만 실행합니다.
나머지는 직접 운영하는 동반 호스트에서 실행되며, 이것은 선택 사항이 아닙니다.

## 이번 릴리스의 상태 <!--quire:status-in-this-release-->

설정은 준비되어 있습니다(`apps/web/vercel.json`, `vercel` Nitro 프리셋,
시작 점검). Vercel에는 공유 파일 저장소(`QUIRE_STORAGE_DRIVER=s3` 또는
`azure`), 함수 인스턴스 전반에서 동작하는 실시간 드라이버
(`QUIRE_REALTIME_DRIVER=sse` 또는 `centrifugo`), HTTP 이메일 공급자가
필요합니다. 없으면 웹 계층은 시작을 거부하고 로그에 누락된 설정을 하나씩
명시합니다.

## 구성 요소 <!--quire:the-pieces-->

| 요소 | 실행 위치 |
| --- | --- |
| `web` | Vercel Functions, Node 런타임: 페이지, REST, MCP, LTI, 수신 웹훅 |
| `worker`, `scheduler`, `collab`, `content` | 동반 호스트: Fly, Railway, ECS, 또는 `docker/compose.yaml`가 있는 직접 운영하는 Docker 호스트 |
| Postgres | 외부, 트랜잭션 풀러 뒤: Neon, Supabase, 또는 PgBouncer가 있는 RDS |
| 파일 | S3 또는 R2. 영구 디스크는 없습니다 |
| 백그라운드 작업 | 요청의 트랜잭션 안에서 pg-boss로 대기열에 넣고 동반 워커가 실행합니다. 동반 워커에 `QUIRE_QUEUE_DRIVER=vercel`을 쓰면 가벼운 작업(순서 없는 알림·웹훅 전달)은 Vercel Queues(`VERCEL_QUEUE_REGION`, `VERCEL_QUEUE_TOKEN`)로 가므로 풀링된 Postgres를 폴링하지 않습니다 |
| 반복 작업 | 동반 스케줄러. 함수 안에서 작업하는 cron은 타임아웃이 나기 때문에 Vercel Cron 라우트는 없습니다 |
| 추적 | 수집기로 보내는 OpenTelemetry, `OTEL_EXPORTER_OTLP_ENDPOINT` |

## 이 타깃이 할 수 없는 것 <!--quire:what-this-target-cannot-do-->

웹 계층은 시작할 때 이것들을 점검하고, 나중에 보내지지 않는 첫 이메일에서
실패하는 대신 문제를 모두 명시하며 거부합니다.

- **SMTP 없음.** Vercel은 발신 SMTP를 막습니다. `QUIRE_EMAIL_PROVIDER_CONFIG`를
  HTTP 공급자(Postmark, SES, Mailgun, SendGrid, Resend)로 설정하세요.
  `QUIRE_SMTP_URL`은 거부됩니다.
- **로컬 디스크 없음.** `QUIRE_STORAGE_DRIVER=local`은 거부됩니다.
- **호출 간 공유 메모리 없음.** `QUIRE_REALTIME_DRIVER=inprocess`는
  거부됩니다. 서버 전송 이벤트는 함수 타임아웃까지만 지속되며, 클라이언트는
  커서로 재연결하므로 이벤트는 잃지 않지만 프레즌스는 사용할 수 없습니다.
- **고정된 테넌트 데이터베이스는 약 여덟 개로 제한**됩니다. 각각 풀을 공유할
  수 없는 환경에서 또 하나의 연결 풀이기 때문입니다.

## 배포 <!--quire:deploying-->

1. 저장소에서 **Root Directory**를 `apps/web`로 두고 Vercel 프로젝트를
   만드세요. `apps/web/vercel.json`이 설치·빌드 명령(`NITRO_PRESET=vercel`)을
   정하고 `/sw.js`를 캐시 없이 제공합니다.
2. 환경 변수를 설정하세요. `docker/.env.example`을 기준으로 최소한:
   `QUIRE_DEPLOY_TARGET=vercel`, `QUIRE_APP_ORIGIN`, `QUIRE_CONTENT_ORIGIN`,
   `QUIRE_PLATFORM_DOMAINS`, `QUIRE_SECRET_KEY`, `QUIRE_MASTER_KEY`,
   `DATABASE_URL`(풀러 주소), `QUIRE_REPORT_DATABASE_URL`,
   `QUIRE_AUDIT_DATABASE_URL`, `QUIRE_DATABASE_ID`,
   `QUIRE_EMAIL_PROVIDER_CONFIG`, `QUIRE_MAIL_FROM`, 저장소 설정,
   그리고 동반 서비스의 collab을 가리키는 `QUIRE_COLLAB_URL`과
   `QUIRE_COLLAB_SIGNING_KEY`.
   `QUIRE_REPORT_DATABASE_URL`은 `DATABASE_URL`이 가리키는 물리 데이터베이스에
   속합니다. 추가로 등록하는 데이터베이스마다 `quire_report` 연결 URL을 웹과
   워커 환경에 각각 추가한 뒤, 플랫폼 콘솔에서 그 환경 변수 이름을
   `env:NAME`으로 등록하세요. 해당 데이터베이스의 리포트 URL이 없으면
   분석은 실패 시 차단됩니다.
3. 동반 호스트에서 `docker/compose.yaml`을 `web` 서비스를 뺀 채 같은
   `docker/.env`로 실행하세요.
   ```sh
   docker compose -f docker/compose.yaml up -d migrate init worker scheduler collab content
   ```
   마이그레이션은 각 Vercel 배포가 승격되기 전에 거기서 실행됩니다.
4. 배포하세요. 설정이 거부되면 함수 로그가 "The web
   tier did not start on vercel"로 시작하고 바꿀 설정을 하나씩 나열합니다.

## 업그레이드 <!--quire:upgrading-->

먼저 동반 호스트에서 마이그레이션한 뒤 새 Vercel 배포를 승격하고, 마지막에
동반 워커를 굴립니다. 순서는 [upgrade.md](/ko/ops/upgrade/)에 있습니다. Vercel의
즉시 롤백은 코드 롤백이며 릴리스 내에서는 항상 안전합니다.

Source: https://docs.quirelms.com/ko/ops/vercel/index.mdx