mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 09:37:28 +00:00
333 lines
13 KiB
Text
333 lines
13 KiB
Text
---
|
||
title: 在 Vercel 上部署 LobeHub
|
||
description: 本文详细介绍如何在 Vercel 中部署 LobeHub，包括数据库配置、身份验证服务配置和 S3 存储服务的设置步骤。
|
||
tags:
|
||
- 服务端数据库
|
||
- Postgres
|
||
- Better Auth
|
||
- S3存储服务
|
||
- Vercel部署
|
||
- 数据库配置
|
||
- 身份验证服务
|
||
- 环境变量配置
|
||
---
|
||
|
||
# 在 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
|
||
，请自行参考[链接](https://stackoverflow.com/questions/14021998/using-psql-to-connect-to-postgresql-in-ssl-mode)进行设置
|
||
</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](https://www.better-auth.com)）：
|
||
|
||
点击下方按钮一键生成 `AUTH_SECRET`（会话加密密钥）：
|
||
|
||
<GenerateSecret envName="AUTH_SECRET" />
|
||
|
||
同时需要配置 `JWKS_KEY` 环境变量，用于签名和验证 JWT。点击下方按钮一键生成：
|
||
|
||
<GenerateJWKSKey />
|
||
|
||
配置这些变量后，用户即可使用邮箱和密码注册登录。
|
||
|
||
<Callout type={'info'}>
|
||
如需 SSO 登录、魔法链接登录、邮箱验证等高级功能，请参阅 [身份验证服务](/zh/docs/self-hosting/auth)。
|
||
</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 函数超时：**
|
||
|
||
| 套餐 | 超时时间 |
|
||
| ---------- | ----- |
|
||
| Hobby | 10 秒 |
|
||
| Pro | 60 秒 |
|
||
| Enterprise | 900 秒 |
|
||
|
||
在 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](https://github.com/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
|
||
```
|