mirror of
https://github.com/lobehub/lobe-chat.git
synced 2026-06-14 03:30:19 +00:00
YuTengjing
344 lines
12 KiB
Plaintext
344 lines
12 KiB
Plaintext
---
|
||
title: 从 Clerk 迁移到 Better Auth
|
||
description: 将 LobeHub 部署从 Clerk 身份验证迁移到 Better Auth 的指南，包括简单迁移和完整迁移选项。
|
||
tags:
|
||
- 身份验证服务
|
||
- Better Auth
|
||
- Clerk
|
||
- 迁移
|
||
---
|
||
|
||
# 从 Clerk 迁移到 Better Auth
|
||
|
||
本指南帮助您将现有的基于 Clerk 的 LobeHub 部署迁移到 Better Auth。
|
||
|
||
<Callout type={'info'}>
|
||
Better Auth 是 LobeHub 推荐的身份验证解决方案。它提供更简单的配置、更多的 SSO 提供商支持，以及更好的自托管体验。
|
||
</Callout>
|
||
|
||
<Callout type={'error'}>
|
||
**重要提醒**：
|
||
|
||
- **务必先备份数据库**！如使用 Neon，可通过 [Fork 分支](https://neon.tech/docs/manage/branches#create-a-branch) 创建备份
|
||
- 迁移过程中可能出现的任何数据丢失或问题，LobeHub 概不负责
|
||
- 本指南适合有一定开发背景的用户，不建议无技术经验的用户自行操作
|
||
- 如有任何疑问，欢迎到 [Discord](https://discord.com/invite/AYFPHvv2jT) 社区或 [GitHub Issue](https://github.com/lobehub/lobe-chat/issues/11707) 提问
|
||
</Callout>
|
||
|
||
## 选择迁移方式
|
||
|
||
| 方式 | 适用场景 | 用户影响 | 数据保留 |
|
||
| ------------- | ------------- | ------- | -------- |
|
||
| [简单迁移](#简单迁移) | 小型部署（≤ 10 用户） | 用户需重置密码 | 聊天记录、设置 |
|
||
| [完整迁移](#完整迁移) | 大型部署 | 对用户无感知 | 全部数据包括密码 |
|
||
|
||
## 简单迁移
|
||
|
||
对于小型自托管部署，最简单的方法是让用户重置密码。
|
||
|
||
<Callout type={'warning'}>
|
||
**限制**：此方法会丢失 SSO 连接数据。如需保留 SSO 连接，请使用 [完整迁移](#完整迁移)。
|
||
|
||
虽然 SSO 连接会丢失，但用户可以在使用邮箱密码登录后，通过个人资料页手动重新绑定社交账号。
|
||
|
||
**示例场景**：假设你之前的账户绑定了两个 SSO 账户：
|
||
|
||
- 主邮箱（Google）：`a@google.com`
|
||
- 副邮箱（Microsoft）：`b@outlook.com`
|
||
|
||
迁移后使用 `a@google.com` 重置密码，之后再用 `b@outlook.com` 登录将会**创建新用户**，而非关联到原有账户。
|
||
</Callout>
|
||
|
||
|
||
|
||
### 步骤
|
||
|
||
1. **配置邮件服务**
|
||
|
||
设置邮件服务以支持密码重置功能。参阅 [邮件服务配置](/zh/docs/self-hosting/auth#邮件服务配置)。
|
||
|
||
2. **更新环境变量**
|
||
|
||
移除 Clerk 变量并添加 Better Auth 变量：
|
||
|
||
<GenerateSecret envName="AUTH_SECRET" />
|
||
|
||
```bash
|
||
# 移除这些
|
||
# NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=xxx
|
||
# CLERK_SECRET_KEY=xxx
|
||
|
||
# 添加这些
|
||
AUTH_SECRET=your-secret-key # openssl rand -base64 32
|
||
|
||
# 可选：启用 Google SSO（示例）
|
||
AUTH_SSO_PROVIDERS=google
|
||
AUTH_GOOGLE_ID=your-google-client-id
|
||
AUTH_GOOGLE_SECRET=your-google-client-secret
|
||
```
|
||
|
||
<Callout type={'tip'}>
|
||
查阅 [身份验证服务配置](/zh/docs/self-hosting/auth) 了解完整的环境变量和 SSO 提供商配置。
|
||
</Callout>
|
||
|
||
3. **重新部署 LobeHub**
|
||
|
||
部署启用 Better Auth 的新版本。
|
||
|
||
4. **通知用户**
|
||
|
||
告知用户按以下步骤登录（聊天记录和设置将被保留）：
|
||
|
||
1. 访问登录页（如 `https://your-domain.com/signin`）
|
||
2. 输入之前使用的邮箱，回车
|
||
|
||
如果启用了 Magic Link：系统会自动发送登录链接邮件，用户点击邮件中的链接即可直接登录。
|
||
|
||
如果未启用 Magic Link：页面会显示提示信息，用户可以选择：
|
||
|
||
- 使用之前关联的社交账号（如 Google、GitHub）登录
|
||
- 点击「设置密码」链接，通过邮件设置新密码后登录
|
||
|
||
|
||
|
||
3. （可选）登录后可在个人资料页进行以下操作：
|
||
- 已关联账号：手动关联其他社交账号
|
||
- 密码：随时设置或更新密码
|
||
|
||
<Callout type={'tip'}>
|
||
这种方法快速且配置简单。用户可通过 Magic Link、社交账号或设置新密码登录，所有数据完整保留。
|
||
登录后可随时在 [个人资料页](/settings/profile) 管理密码和关联账号。
|
||
</Callout>
|
||
|
||
## 完整迁移
|
||
|
||
对于大型部署或需要保留用户密码和 SSO 连接的情况，请使用迁移脚本。
|
||
|
||
<Callout type={'error'}>
|
||
**重要说明**：
|
||
|
||
- **务必先备份数据库**！如使用 Neon，可通过 [Fork 分支](https://neon.tech/docs/manage/branches#create-a-branch) 创建备份
|
||
- 迁移脚本需要 **clone 仓库后在本地运行**，不是在部署环境中执行
|
||
- 由于迁移涉及用户数据，风险较高，**官方不提供部署时自动迁移功能**
|
||
- 请务必先使用 dry-run 模式测试脚本能够顺利运行再正式执行
|
||
- 请务必在测试环境验证后再操作生产数据库
|
||
</Callout>
|
||
|
||
### 前置条件
|
||
|
||
**环境要求：**
|
||
|
||
- Node.js 18+
|
||
- Git（用于 clone 仓库）
|
||
- pnpm（用于安装依赖）
|
||
|
||
**准备工作：**
|
||
|
||
1. Clone LobeHub 仓库并安装依赖：
|
||
|
||
```bash
|
||
git clone https://github.com/lobehub/lobe-chat.git
|
||
cd lobe-chat
|
||
pnpm install
|
||
```
|
||
|
||
2. 准备以下信息：
|
||
- Clerk 控制台访问权限（用于 CSV 导出）
|
||
- Clerk API 密钥（用于 API 导出）
|
||
- 数据库连接字符串
|
||
|
||
3. 确保数据库 schema 为最新版本
|
||
|
||
<Callout type={'info'}>
|
||
如果你长期停留在旧版本（如 1.x），数据库 schema 可能不是最新的。请在 clone 的仓库中运行：
|
||
|
||
```bash
|
||
DATABASE_URL=your-database-url pnpm db:migrate
|
||
```
|
||
</Callout>
|
||
|
||
### 步骤 1：配置迁移脚本环境变量
|
||
|
||
在项目根目录创建 `.env` 文件（脚本会自动加载），配置所有环境变量：
|
||
|
||
```bash
|
||
# ============================================
|
||
# 迁移模式：test 或 prod
|
||
# 建议先用 test 模式在测试数据库验证，确认无误后再切换到 prod
|
||
# ============================================
|
||
CLERK_TO_BETTERAUTH_MODE=test
|
||
|
||
# ============================================
|
||
# 数据库连接（根据模式使用对应的环境变量）
|
||
# TEST_ 前缀用于测试环境，PROD_ 前缀用于生产环境
|
||
# ============================================
|
||
TEST_CLERK_TO_BETTERAUTH_DATABASE_URL=postgresql://user:pass@test-host:5432/testdb
|
||
PROD_CLERK_TO_BETTERAUTH_DATABASE_URL=postgresql://user:pass@prod-host:5432/proddb
|
||
|
||
# ============================================
|
||
# Clerk API 密钥（用于通过 API 导出用户数据）
|
||
# 从 Clerk 控制台获取：Configure → Developers → API Keys
|
||
# ============================================
|
||
TEST_CLERK_TO_BETTERAUTH_CLERK_SECRET_KEY=sk_test_xxx
|
||
PROD_CLERK_TO_BETTERAUTH_CLERK_SECRET_KEY=sk_live_xxx
|
||
|
||
# ============================================
|
||
# 数据库驱动（可选）
|
||
# neon: Neon serverless 驱动（默认）
|
||
# node: node-postgres 驱动
|
||
# ============================================
|
||
CLERK_TO_BETTERAUTH_DATABASE_DRIVER=neon
|
||
|
||
# ============================================
|
||
# Dry Run 模式（可选）
|
||
# 设为 1 时只打印日志，不实际修改数据库
|
||
# 建议首次运行时启用，验证无误后再关闭
|
||
# ============================================
|
||
CLERK_TO_BETTERAUTH_DRY_RUN=1
|
||
```
|
||
|
||
### 步骤 2：导出 Clerk 数据
|
||
|
||
#### 停止新用户注册
|
||
|
||
在导出数据前，先禁止新用户注册，确保迁移期间数据不变：
|
||
|
||
1. 前往 [Clerk 控制台](https://dashboard.clerk.com) → Configure → Restrictions
|
||
2. 启用「Restricted」模式
|
||
|
||
#### 从 Clerk 控制台导出 CSV
|
||
|
||
1. 前往 [Clerk 控制台](https://dashboard.clerk.com) → Configure → Settings → User exports
|
||
2. 点击「Export users」下载 CSV 文件
|
||
3. 保存到 `scripts/clerk-to-betterauth/test/clerk_exported_users.csv`
|
||
|
||
详见 [Clerk 官方文档](https://clerk.com/docs/guides/development/migrating/overview#export-your-users-data-from-the-clerk-dashboard)。
|
||
|
||
|
||
|
||
#### 通过 API 导出 JSON
|
||
|
||
```bash
|
||
# 运行导出脚本（会根据 CLERK_TO_BETTERAUTH_MODE 自动选择密钥和输出路径）
|
||
npx tsx scripts/clerk-to-betterauth/export-clerk-users-with-api.ts
|
||
```
|
||
|
||
这将自动创建 `scripts/clerk-to-betterauth/test/clerk_users.json`，包含额外的用户数据。
|
||
|
||
### 步骤 3：Dry-Run 验证（测试环境）
|
||
|
||
```bash
|
||
# 运行迁移（CLERK_TO_BETTERAUTH_DRY_RUN=1，只打印日志不修改数据库）
|
||
npx tsx scripts/clerk-to-betterauth/index.ts
|
||
```
|
||
|
||
检查输出日志，确认无异常后继续下一步。
|
||
|
||
### 步骤 4：执行迁移并验证（测试环境）
|
||
|
||
修改 `.env` 将 `CLERK_TO_BETTERAUTH_DRY_RUN` 改为 `0`，然后执行：
|
||
|
||
```bash
|
||
# 执行迁移
|
||
npx tsx scripts/clerk-to-betterauth/index.ts
|
||
|
||
# 验证迁移结果
|
||
npx tsx scripts/clerk-to-betterauth/verify.ts
|
||
```
|
||
|
||
验证测试环境迁移结果无误后，继续下一步。
|
||
|
||
### 步骤 5：Dry-Run 验证（生产环境）
|
||
|
||
1. 将 CSV 文件复制到 prod 目录：`scripts/clerk-to-betterauth/prod/clerk_exported_users.csv`
|
||
2. 修改 `.env` 文件：
|
||
- 将 `CLERK_TO_BETTERAUTH_MODE` 改为 `prod`
|
||
- 将 `CLERK_TO_BETTERAUTH_DRY_RUN` 改回 `1`
|
||
3. 运行脚本：
|
||
|
||
```bash
|
||
# 导出生产环境用户数据
|
||
npx tsx scripts/clerk-to-betterauth/export-clerk-users-with-api.ts
|
||
|
||
# 运行迁移（dry-run 模式验证）
|
||
npx tsx scripts/clerk-to-betterauth/index.ts
|
||
```
|
||
|
||
检查输出日志，确认无异常后继续下一步。
|
||
|
||
### 步骤 6：执行迁移并验证（生产环境）
|
||
|
||
修改 `.env` 将 `CLERK_TO_BETTERAUTH_DRY_RUN` 改为 `0`，然后执行：
|
||
|
||
```bash
|
||
# 执行迁移
|
||
npx tsx scripts/clerk-to-betterauth/index.ts
|
||
|
||
# 验证迁移结果
|
||
npx tsx scripts/clerk-to-betterauth/verify.ts
|
||
```
|
||
|
||
### 步骤 7：配置 Better Auth 并重新部署
|
||
|
||
迁移完成后，参照 [简单迁移 - 步骤 2](#步骤) 配置 Better Auth 环境变量并重新部署。
|
||
|
||
<Callout type={'tip'}>
|
||
完整的 Better Auth 配置请参阅 [身份验证服务配置](/zh/docs/self-hosting/auth)，包括所有支持的 SSO 提供商和邮件服务配置。
|
||
</Callout>
|
||
|
||
## 迁移内容对比
|
||
|
||
| 数据 | 简单迁移 | 完整迁移 |
|
||
| ----------------------- | --------- | ---- |
|
||
| 用户账户 | ✅（通过密码重置） | ✅ |
|
||
| 密码哈希 | ❌ | ✅ |
|
||
| SSO 连接（Google、GitHub 等） | ❌ | ✅ |
|
||
| 双因素认证 | ❌ | ✅ |
|
||
| 聊天记录 | ✅ | ✅ |
|
||
| 用户设置 | ✅ | ✅ |
|
||
|
||
## 常见问题
|
||
|
||
### 访问前清除浏览器数据
|
||
|
||
迁移完成后，如果遇到登录问题，请先尝试清除浏览器的站点数据：
|
||
|
||
1. 打开浏览器开发者工具（F12 或右键 → 检查）
|
||
2. 进入 Application 标签页 → Storage → Clear site data
|
||
3. 刷新页面后重试
|
||
|
||
|
||
|
||
### 迁移后用户无法登录
|
||
|
||
- 确保邮件服务已配置用于密码重置
|
||
- 检查 `AUTH_SECRET` 是否正确设置
|
||
- 验证数据库连接是否正常
|
||
|
||
### SSO 用户无法连接
|
||
|
||
- 简单迁移：用户需要在重置密码后重新关联 SSO 账户
|
||
- 完整迁移：验证 SSO 提供商已在 `AUTH_SSO_PROVIDERS` 中配置
|
||
|
||
### 迁移脚本失败
|
||
|
||
- 检查数据库连接字符串
|
||
- 确保 CSV 和 JSON 文件位于正确位置
|
||
- 查看脚本日志了解具体错误
|
||
|
||
### column "xxx" of relation "users" does not exist
|
||
|
||
这是因为数据库 schema 未更新。请先运行 `pnpm db:migrate` 更新数据库结构，然后再执行迁移脚本。
|
||
|
||
## 相关阅读
|
||
|
||
<Cards>
|
||
<Card href={'/zh/docs/self-hosting/migration/v2/auth/migration-internals'} title={'迁移技术原理'} />
|
||
|
||
<Card href={'/zh/docs/self-hosting/auth'} title={'身份验证服务配置'} />
|
||
|
||
<Card href={'/zh/docs/self-hosting/environment-variables/auth'} title={'认证相关环境变量'} />
|
||
|
||
<Card href={'/zh/docs/self-hosting/auth/legacy'} title={'旧版身份验证（NextAuth 和 Clerk）'} />
|
||
</Cards>
|