LobeHub
LobeHub

在 Vercel 上部署 LobeHub

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

进行后续操作前,请务必确认以下事项:

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

一、 配置数据库

准备服务端数据库实例,获取连接 URL

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

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

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

在 Vercel 中添加环境变量

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

请确认您的供应商所提供的 Postgres 类型,若为 Node Postgres,请切换到 Node Postgres Tab 。

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

*.sh
Shell
# Serverless Postgres DB Url
DATABASE_URL=

在 Vercel 中填写的示例如下:

添加 Serverless Postgres DATABASE_URL

如果希望连接数据库时启用 SSL ,请自行参考链接进行设置

添加 KEY_VAULTS_SECRET 环境变量

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

Shell
KEY_VAULTS_SECRET='点击按钮生成'

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

添加 APP_URL 环境变量

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

二、 配置身份验证服务

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

添加身份验证环境变量

在 Vercel 的部署环境变量中,添加以下环境变量以启用身份验证(基于 Better Auth):

点击下方按钮一键生成 AUTH_SECRET(会话加密密钥):

Shell
AUTH_SECRET='点击按钮生成'

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

Shell
JWKS_KEY='点击按钮生成'

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

如需 SSO 登录、魔法链接登录、邮箱验证等高级功能,请参阅 身份验证服务。

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

三、 配置 S3 存储服务

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

在本文,S3 所指代的是指兼容 S3 存储方案,即支持 Amazon S3 API 的对象存储系统,常见例如 Cloudflare R2 、阿里云 OSS 等均支持 S3 兼容 API。

配置并获取 S3 存储桶

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

下图是 Cloudflare R2 的界面:

Cloudflare R2 存储界面

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

R2 创建存储桶

获取存储桶相关环境变量

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

查看存储桶的相关信息

其对应的环境变量为:

*.sh
Shell
# 存储桶的名称
S3_BUCKET=LobeHub
# 存储桶的请求端点(注意此处链接的路径带存储桶名称,必须删除该路径,或使用申请 S3 API token 页面所提供的链接)
S3_ENDPOINT=https://0b33a03b5c993fd2f453379dc36558e5.r2.cloudflarestorage.com
S3_ENDPOINT必须删除其路径,否则会无法访问所上传文件

获取 S3 密钥环境变量

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

查看存储桶的访问秘钥

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

创建对应 API token

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

配置 API token 权限

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

复制 API token

其对应的环境变量为:

*.sh
Shell
S3_ACCESS_KEY_ID=9998d6757e276cf9f1edbd325b7083a6
S3_SECRET_ACCESS_KEY=55af75d8eb6b99f189f6a35f855336ea62cd9c4751a5cf4337c53c1d3f497ac2

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

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

URL 的https://不可缺失,须保持 URL 的完整性
*.sh
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 的环境变量中:

在  Vercel 中添加 S3 的环境变量

配置跨域

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

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

Cloudflare R2 的跨域设置

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

配置允许你的站点域名

示例配置如下:

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

配置后点击保存即可。

四、部署并验证

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

重新部署最新的 commit

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

重新部署最新的 commit

检查功能是否正常

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

用户登录弹窗
登录成功状态

可选:使用 GitHub Actions 预构建

如果 Vercel 构建因内存不足或超过构建时限而失败,可以改在 GitHub Actions 中运行 vercel build,再通过 vercel deploy --prebuilt 将 .vercel/output 构建产物部署到 Vercel。该流程遵循 Vercel 官方的 GitHub Actions 部署方式。

此方式只将构建阶段移到 GitHub Actions。部署后的函数运行时、流量和套餐配额仍受 Vercel 限制。如果 Vercel 原生 Git 部署可以正常完成,则无需改用此方式。

准备 Vercel 凭据

准备以下三个值:

  • VERCEL_TOKEN:在 Vercel 的 Tokens 页面创建;
  • VERCEL_ORG_ID 和 VERCEL_PROJECT_ID:在仓库根目录执行 vercel link 后,可从生成的 .vercel/project.json 中获取。

在 Fork 仓库中进入 Settings → Secrets and variables → Actions,分别创建同名的 Repository secrets。请勿将这些值直接写入工作流文件。

添加 GitHub Actions 工作流

在 Fork 仓库中新建 .github/workflows/vercel-prebuilt-deploy.yml,写入以下内容:

*.yml
YAML
name: Vercel Prebuilt Deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: vercel-production
  cancel-in-progress: true

env:
  VERCEL: '1'
  VERCEL_ENV: production
  NEXT_PUBLIC_VERCEL_ENV: production
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 90

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Setup environment
        uses: ./.github/actions/setup-env

      - name: Install Vercel CLI
        run: npm install --global vercel@latest

      - name: Pull Vercel project settings
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: vercel pull --yes --environment=production --token="$VERCEL_TOKEN"

      - name: Build Vercel output
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: vercel build --prod --token="$VERCEL_TOKEN"

      - name: Deploy prebuilt output
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: vercel deploy --prebuilt --prod --archive=tgz --token="$VERCEL_TOKEN"

每次向 main 分支推送代码后,该工作流都会自动构建并部署。你也可以在 Actions → Vercel Prebuilt Deploy → Run workflow 中手动触发。

仓库内置的 Upstream Sync 工作流使用 GITHUB_TOKEN 推送,而这种推送不会启动另一个工作流。Upstream Sync 更新 Fork 后,请手动运行 Vercel Prebuilt Deploy 部署新版本。

关闭 Vercel 原生 Git 部署

确认上述工作流可以成功部署后,在 Vercel 项目的 Settings → Git → Connected Git Repository 中断开 Git 仓库连接,避免同一次推送同时触发 Vercel 原生构建和 GitHub Actions 构建。断开连接不会影响通过 Vercel CLI 部署预构建产物。

验证部署

打开 GitHub Actions 的运行详情。Deploy prebuilt output 步骤会输出生产部署地址;访问该地址并按上一节检查登录功能。

平台限制

部署前请了解 Vercel 平台的以下限制。

Serverless 函数超时:

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

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

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

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

文件大小限制 — 部署包:250 MB(压缩后);函数包:50 MB。

保持版本更新

如果你使用了一键部署按钮,Vercel 会创建一个全新的仓库,而非 Fork 原始仓库。这会导致无法自动同步上游更新。

若要接收 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 修复,最好只在构建步骤设置:若运行时也生效,更大的堆参数会覆盖解析 worker 的 768 MB 内存上限,文件解析会按这个更大的上限运行,并记录一次 file_parse.heap_budget_overridden)。

函数超时 — 在 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)、减少并发连接数或查看数据库日志。

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

附录

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

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

*.sh
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