---
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/lobehub/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>

![个人资料页 - 关联账号信息](https://hub-apac-1.lobeobjects.space/docs/43dfa498b82a58c9f99e805e88ea711a.png)

### 步骤

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）登录
   - 点击「设置密码」链接，通过邮件设置新密码后登录

   ![LobeHub 登录页面 - 社交账号登录提示](https://hub-apac-1.lobeobjects.space/docs/8d0563701fcd17ad7252a72b1746dd42.png)

   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/lobehub.git
   cd lobehub
   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)。

![Clerk Dashboard - 导出用户 CSV](https://hub-apac-1.lobeobjects.space/docs/6523e1805a69d3ece3804e2bcd5d4552.png)

#### 通过 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. 刷新页面后重试

![清除浏览器站点数据](https://hub-apac-1.lobeobjects.space/docs/733c50ee2302e5daa3d99dc0739238c8.png)

### 迁移后用户无法登录

- 确保邮件服务已配置用于密码重置
- 检查 `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>
