ContextQMD
Back to Lobehub

在 Vercel 上部署 LobeHub

docs/self-hosting/platform/vercel.zh-CN.mdx

2.1.5612.3 KB
Original Source

在 Vercel 上部署 LobeHub

本文将详细介绍如何在 Vercel 中部署 LobeHub，包括： 1）数据库配置；2）身份验证服务配置；3） S3 存储服务的设置步骤。

<Callout type={'warning'}> 进行后续操作前，请务必确认以下事项：

  • 导出所有数据，部署服务端数据库后，原有用户数据无法自动迁移，只能提前备份后进行手动导入！
  • 配置服务端数据库所需要的环境变量时，需全部填入后再进行部署，否则可能遭遇数据库迁移问题！ </Callout>

一、 配置数据库

<Steps> ### 准备服务端数据库实例，获取连接 URL

在部署之前，请确保你已经准备好 Postgres 数据库实例，你可以选择以下任一方式：

  • A. 使用 Vercel / Neon 等 Serverless Postgres 实例；
  • B. 使用 Docker 等自部署 Postgres 实例。

两者的配置方式略有不同，在下一步会有所区分。

在 Vercel 中添加环境变量

在 Vercel 的部署环境变量中，添加 DATABASE_URL 等环境变量，将上一步准备好的 Postgres 数据库连接 URL 填入其中。数据库连接 URL 的通常格式为 postgres://username:password@host:port/database。

<Tabs items={['Serverless Postgres', 'Node Postgres']}> <Tab> <Callout type={'warning'}> 请确认您的供应商所提供的 Postgres 类型，若为 Node Postgres，请切换到 Node Postgres Tab 。 </Callout>

  Serverless Postgres 需要填写的变量如下：

  ```shell
  # Serverless Postgres DB Url
  DATABASE_URL=
  ```

  在 Vercel 中填写的示例如下：

  <Image alt={'添加 Serverless Postgres DATABASE_URL'} src={'/blog/assets28616219/d4a710cd-6404-4196-90d0-cd08ca385074.webp'} />
</Tab>

<Tab>
  Node Postgres 需要填写的变量如下：

  ```shell
  # Node Postgres DB Url
  DATABASE_URL=

  # 指定 Postgres database driver 为 node
  DATABASE_DRIVER=node
  ```

  在 Vercel 中填写的示例如下：

  <Image alt={'添加 Node Postgres DATABASE_URL'} src={'/blog/assets28616219/1c689738-809b-4199-b305-ba5770d39da7.webp'} />
</Tab>
</Tabs>

<Callout type={'info'}> 如果希望连接数据库时启用 SSL ，请自行参考链接进行设置 </Callout>

添加 KEY_VAULTS_SECRET 环境变量

在完成数据库 DATABASE_URL 环境变量添加后，需要添加一个 KEY_VAULTS_SECRET 环境变量。该变量用于加密用户存储的 apikey 等敏感信息。点击下方按钮一键生成：

<GenerateSecret envName="KEY_VAULTS_SECRET" />

同样需要将其添加到 Vercel 环境变量中。

添加 APP_URL 环境变量

该部分最后需要添加 APP_URL 环境变量，用于指定 LobeHub 应用的 URL 地址。 </Steps>

二、 配置身份验证服务

服务端数据库需要搭配用户身份验证服务才可以正常使用。因此需要配置对应的身份验证服务。

<Steps> ### 添加身份验证环境变量

在 Vercel 的部署环境变量中，添加以下环境变量以启用身份验证（基于 Better Auth）：

点击下方按钮一键生成 AUTH_SECRET（会话加密密钥）：

<GenerateSecret envName="AUTH_SECRET" />

同时需要配置 JWKS_KEY 环境变量，用于签名和验证 JWT。点击下方按钮一键生成：

<GenerateJWKSKey />

配置这些变量后，用户即可使用邮箱和密码注册登录。

<Callout type={'info'}> 如需 SSO 登录、魔法链接登录、邮箱验证等高级功能，请参阅 身份验证服务。 </Callout> </Steps>

这样，你已经成功配置了身份验证服务。接下来我们将配置 S3 存储服务。

三、 配置 S3 存储服务

在服务端数据库中我们需要配置 S3 存储服务来存储文件。

<Callout type={'info'}> 在本文，S3 所指代的是指兼容 S3 存储方案，即支持 Amazon S3 API 的对象存储系统，常见例如 Cloudflare R2 、阿里云 OSS 等均支持 S3 兼容 API。 </Callout>

<Steps> ### 配置并获取 S3 存储桶

你需要前往你的 S3 服务提供商（如 AWS S3、Cloudflare R2 等）并创建一个新的存储桶（Bucket）。接下来以 Cloudflare R2 为例，介绍创建流程。

下图是 Cloudflare R2 的界面：

<Image alt={'Cloudflare R2 存储界面'} src={'/blog/assets28616219/41f7f677-0153-4a96-b849-5ac9b7ebefee.webp'} />

创建存储桶时将指定其名称，然后点击创建。

<Image alt={'R2 创建存储桶'} src={'/blog/assets28616219/9c0d184c-3169-40fa-9115-011cfffb9ca7.webp'} />

获取存储桶相关环境变量

在 R2 存储桶的设置中，可以看到桶配置的信息：

<Image alt={'查看存储桶的相关信息'} src={'/blog/assets28616219/2ceb210c-eca0-4439-ba27-8734d4ebb3ee.webp'} />

其对应的环境变量为：

shell
# 存储桶的名称
S3_BUCKET=LobeHub
# 存储桶的请求端点(注意此处链接的路径带存储桶名称，必须删除该路径，或使用申请 S3 API token 页面所提供的链接)
S3_ENDPOINT=https://0b33a03b5c993fd2f453379dc36558e5.r2.cloudflarestorage.com

<Callout type={'warning'}>S3_ENDPOINT必须删除其路径，否则会无法访问所上传文件</Callout>

获取 S3 密钥环境变量

你需要获取 S3 的访问密钥，以便 LobeHub 的服务端有权限访问 S3 存储服务。在 R2 中，你可以在账户详情中配置访问密钥：

<Image alt={'查看存储桶的访问秘钥'} src={'/blog/assets28616219/be0c95c0-6693-44ee-a490-7e8dfaa8b34d.webp'} />

点击右上角按钮创建 API token，进入创建 API Token 页面

<Image alt={'创建对应 API token'} src={'/blog/assets28616219/7b0ea46c-5157-40a8-888f-f47664a4884f.webp'} />

鉴于我们的服务端数据库需要读写 S3 存储服务，因此权限需要选择对象读与写，然后点击创建。

<Image alt={'配置 API token 权限'} src={'/blog/assets28616219/d6f5a918-7b50-4d6e-83a6-3894ab930ddf.webp'} />

创建完成后，就可以看到对应的 S3 API token

<Image alt={'复制 API token'} src={'/blog/assets28616219/763b18f9-2b5f-44bb-a479-9b56d46f7397.webp'} />

其对应的环境变量为：

shell
S3_ACCESS_KEY_ID=9998d6757e276cf9f1edbd325b7083a6
S3_SECRET_ACCESS_KEY=55af75d8eb6b99f189f6a35f855336ea62cd9c4751a5cf4337c53c1d3f497ac2

在 Vercel 中添加对应的环境变量

不同 S3 服务商获取所需环境变量的步骤可能有所不同，但最终获得到的环境变量应该都是一致的：

<Callout type={'warning'}>URL 的https://不可缺失，须保持 URL 的完整性</Callout>

shell
# S3 秘钥
S3_ACCESS_KEY_ID=9998d6757e276cf9f1edbd325b7083a6
S3_SECRET_ACCESS_KEY=55af75d8eb6b99f189f6a35f855336ea62cd9c4751a5cf4337c53c1d3f497ac2

# 存储桶的名称
S3_BUCKET=LobeHub
# 存储桶的请求端点
S3_ENDPOINT=https://0b33a03b5c993fd2f453379dc36558e5.r2.cloudflarestorage.com
# 桶的区域，如 us-west-1，一般来说不需要添加，但某些服务商则需要配置
# S3_REGION=us-west-1

然后将上述环境变量填入 Vercel 的环境变量中：

<Image alt={'在 Vercel 中添加 S3 的环境变量'} src={'/blog/assets28616219/cd74152d-0ae8-44fd-b815-3307c56a3c18.webp'} />

配置跨域

由于 S3 存储服务往往是一个独立的网址，因此需要配置跨域访问。

在 R2 中，你可以在存储桶的设置中找到跨域配置：

<Image alt={'Cloudflare R2 的跨域设置'} src={'/blog/assets28616219/ab008be7-26b2-4b78-8bd9-24301bf34d23.webp'} />

添加跨域规则，允许你的域名（在上文是 https://your-project.vercel.app）来源的请求：

<Image alt={'配置允许你的站点域名'} src={'/blog/assets28616219/dfcc2cb3-2958-4498-a8a4-51bec584fe7d.webp'} />

示例配置如下：

json
[
  {
    "AllowedOrigins": ["https://your-project.vercel.app"],
    "AllowedMethods": ["GET", "PUT", "HEAD", "POST", "DELETE"],
    "AllowedHeaders": ["*"]
  }
]

配置后点击保存即可。 </Steps>

四、部署并验证

通过上述步骤之后，我们应该就完成了服务端数据库的配置。接下来我们可以将 LobeHub 部署到 Vercel 上，然后访问你的 Vercel 链接，验证服务端数据库是否正常工作。

<Steps> ### 重新部署最新的 commit

配置好环境变量后，你需要重新部署最新的 commit，并等待部署完成。

<Image alt={'重新部署最新的 commit'} src={'/blog/assets28616219/b3a78112-adc8-4837-b4e3-48f67058f16e.webp'} />

检查功能是否正常

如果你点击左上角登录，可以正常显示登录弹窗，那么说明你已经配置成功了，尽情享用吧～

<Image alt={'用户登录弹窗'} src={'/blog/assets28616219/da84edc3-46f7-4e2b-a0cd-dc33a98bf5cb.webp'} />

<Image alt={'登录成功状态'} src={'/blog/assets28616219/9cb5150d-6e1e-4c59-9a18-4e418dce1a5d.webp'} /> </Steps>

平台限制

<Callout type={'warning'}> 部署前请了解 Vercel 平台的以下限制。 </Callout>

Serverless 函数超时：

套餐超时时间
Hobby10 秒
Pro60 秒
Enterprise900 秒

在 Hobby 套餐上，长时间运行的 AI 请求可能会超时。默认启用的流式响应有助于保持连接活跃。

不支持 WebSocket — Vercel Serverless 函数不支持持久 WebSocket 连接，实时功能使用服务端发送事件（SSE）代替。

冷启动 — Serverless 函数在空闲后的首次请求可能较慢（1–3 秒），这是 Serverless 平台的正常行为。

文件大小限制 — 部署包：250 MB（压缩后）；函数包：50 MB。

保持版本更新

<Callout type={'warning'}> 如果你使用了一键部署按钮，Vercel 会创建一个全新的仓库，而非 Fork 原始仓库。这会导致无法自动同步上游更新。 </Callout>

若要接收 LobeHub 的后续更新：

  1. 在 Vercel 控制台删除当前项目（设置 → 删除项目）
  2. 在 GitHub 上手动 Fork lobehub/lobehub
  3. 将 Fork 后的仓库导入到 Vercel（新增项目 → 导入）
  4. 重新配置环境变量并部署
  5. 在 Fork 仓库的 GitHub Actions 标签页，启用 upstream-sync 工作流 —— 它会每日自动检查上游更新

手动同步：Actions → Upstream Sync → Run workflow。

故障排查

部署失败 — 在 Vercel 控制台 → 部署记录 → 点击失败的部署 → 构建日志中查看详情。常见原因：环境变量缺失、TypeScript 报错、内存不足（通过 NODE_OPTIONS=--max-old-space-size=4096 修复）。

函数超时 — 在 Hobby 套餐遇到超时时：升级到 Pro（60 秒超时）、使用更快的模型（如 GPT-4o-mini 代替 GPT-4o）、减少最大 token 数，或确认已启用流式响应。

数据库连接失败 — 检查 DATABASE_URL 格式。对于托管数据库，确保末尾追加了 ?sslmode=require。检查数据库 IP 白名单是否包含 Vercel IP（或使用 0.0.0.0/0 开放访问）。本地测试：psql "$DATABASE_URL"。

502 网关错误 — 常见原因：函数超时、内存溢出、数据库连接池耗尽。使用连接池（PgBouncer）、减少并发连接数或查看数据库日志。

环境变量修改后未生效 — 在部署记录中点击某次部署的三点菜单 → 重新部署，选择 "不使用现有构建缓存"。

附录

服务端数据库环境变量一览

为方便一键复制，在此汇总配置服务端数据库所需要的环境变量：

shell
APP_URL=https://your-project.com

# Postgres 数据库 URL
DATABASE_URL=
KEY_VAULTS_SECRET=jgwsK28dspyVQoIf8/M3IIHl1h6LYYceSYNXeLpy6uk=

# 身份验证
AUTH_SECRET=jgwsK28dspyVQoIf8/M3IIHl1h6LYYceSYNXeLpy6uk=
JWKS_KEY='{"keys":[...]}'

# S3 相关配置
# S3 秘钥
S3_ACCESS_KEY_ID=9998d6757e276cf9f1edbd325b7083a6
S3_SECRET_ACCESS_KEY=55af75d8eb6b99f189f6a35f855336ea62cd9c4751a5cf4337c53c1d3f497ac2

# 存储桶的名称
S3_BUCKET=LobeHub
# 存储桶的请求端点
S3_ENDPOINT=https://0b33a03b5c993fd2f453379dc36558e5.r2.cloudflarestorage.com
# 桶的区域，如 us-west-1，一般来说不需要添加，但某些服务商则需要配置
# S3_REGION=us-west-1