在 Vercel 上运行 Web 层

架构设计见 docs/architecture/23-ops.md 第 5 节。Vercel 只运行 Web 层。其余所有服务都必须在您负责管理的配套主机上运行。

本版本状态

配置已经就绪（apps/web/vercel.json、vercel Nitro 预设和启动检查）。Vercel 需要共享文件存储（QUIRE_STORAGE_DRIVER=s3 或 azure）、可跨函数实例使用的实时驱动（QUIRE_REALTIME_DRIVER=sse 或 centrifugo）以及 HTTP 电子邮件服务提供商。缺少其中任何一项，Web 层都会拒绝启动，并在日志中列出缺失设置。

组件

组件	运行位置
`web`	Vercel Functions，Node 运行时：页面、REST、MCP、LTI、接收 webhook
`worker`、`scheduler`、`collab`、`content`	配套主机：Fly、Railway、ECS，或使用 `docker/compose.yaml` 的自有 Docker 主机
Postgres	外部数据库，通过事务池化器连接：Neon、Supabase 或使用 PgBouncer 的 RDS
文件	S3 或 R2。没有持久磁盘
后台任务	在请求事务中通过 pg-boss 加入队列，再由配套 worker 执行。若在配套 worker 上设置 `QUIRE_QUEUE_DRIVER=vercel`，轻量任务（无序通知和 webhook 投递）会改用 Vercel Queues（`VERCEL_QUEUE_REGION`、`VERCEL_QUEUE_TOKEN`），因此不会为这些任务轮询池化 Postgres
定期任务	由配套 scheduler 执行。没有 Vercel Cron 路由，因为在函数中处理任务会超时
跟踪	通过 `OTEL_EXPORTER_OTLP_ENDPOINT` 将 OpenTelemetry 数据发送到您的收集器

此部署目标不支持的功能

Web 层启动时会检查下列设置，并一次列出所有问题后拒绝启动，避免等到第一次邮件无法发送时才失败：

**不支持 SMTP。**Vercel 会阻止外发 SMTP。请将 QUIRE_EMAIL_PROVIDER_CONFIG 设为 HTTP 服务提供商（Postmark、SES、Mailgun、SendGrid 或 Resend）。设置 QUIRE_SMTP_URL 会被拒绝。
**不支持本地磁盘。**设置 QUIRE_STORAGE_DRIVER=local 会被拒绝。
**调用之间没有共享内存。**设置 QUIRE_REALTIME_DRIVER=inprocess 会被拒绝。服务器发送事件受函数超时限制；客户端会带游标重新连接，因此不会丢失事件，但无法提供在线状态。
固定到专用数据库的租户数量大约最多为八个，因为每个数据库都会额外占用一个连接池，而此环境无法共享连接池。

部署

从代码库创建 Vercel 项目，并将根目录设为 apps/web。apps/web/vercel.json 会设置安装和构建命令（NITRO_PRESET=vercel），并让 /sw.js 不经过缓存。
设置环境变量。至少需要从 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 指定的物理数据库。对每个额外注册的数据库，都要在 web 和 worker 环境中添加其 quire_report 连接 URL，然后在平台控制台中将环境变量名注册为 env:NAME。缺少某数据库的报告 URL 时，分析功能会以安全失败方式拒绝运行。
在配套主机上运行 docker/compose.yaml，不启动 web 服务，并使用相同的 docker/.env：
```
docker compose -f docker/compose.yaml up -d migrate init worker scheduler collab content
```
每次提升新的 Vercel 部署前，都要先在此处运行迁移。
执行部署。如果配置被拒绝，函数日志会以 “The web tier did not start on vercel” 开头，并列出需要更改的每项设置。

升级

先在配套主机上运行迁移，再提升新的 Vercel 部署，最后滚动升级配套主机的 worker；顺序见 upgrade.md。Vercel 即时回滚属于代码回滚，在同一版本内始终安全。