---
title: "在 Vercel 上运行 Web 层"
description: "在 Vercel 上运行 Quire Web 层，并在配套主机上运行 worker。"
image: "https://docs.quirelms.com/og.png"
---

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

# 在 Vercel 上运行 Web 层

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

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

## 本版本状态 <!--quire:status-in-this-release-->

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

## 组件 <!--quire:the-pieces-->

| 组件 | 运行位置 |
| --- | --- |
| `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 数据发送到您的收集器 |

## 此部署目标不支持的功能 <!--quire:what-this-target-cannot-do-->

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` 会被拒绝。服务器发送事件受函数超时限制；客户端会带游标重新连接，因此不会丢失事件，但无法提供在线状态。
- **固定到专用数据库的租户数量**大约最多为八个，因为每个数据库都会额外占用一个连接池，而此环境无法共享连接池。

## 部署 <!--quire:deploying-->

1. 从代码库创建 Vercel 项目，并将**根目录**设为 `apps/web`。`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` 指定的物理数据库。对每个额外注册的数据库，都要在 web 和 worker 环境中添加其 `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 部署，最后滚动升级配套主机的 worker；顺序见 [upgrade.md](/zh-Hans/ops/upgrade/)。Vercel 即时回滚属于代码回滚，在同一版本内始终安全。

Source: https://docs.quirelms.com/zh-Hans/ops/vercel/index.mdx