ContextQMD
Back to Lobehub

从 Clerk 迁移到 Better Auth

docs/self-hosting/migration/v2/auth/clerk-to-betterauth.zh-CN.mdx

2.1.5611.7 KB
Original Source

从 Clerk 迁移到 Better Auth

本指南帮助您将现有的基于 Clerk 的 LobeHub 部署迁移到 Better Auth。

<Callout type={'info'}> Better Auth 是 LobeHub 推荐的身份验证解决方案。它提供更简单的配置、更多的 SSO 提供商支持，以及更好的自托管体验。 </Callout>

<Callout type={'error'}> 重要提醒：

  • 务必先备份数据库！如使用 Neon，可通过 Fork 分支 创建备份
  • 迁移过程中可能出现的任何数据丢失或问题，LobeHub 概不负责
  • 本指南适合有一定开发背景的用户，不建议无技术经验的用户自行操作
  • 如有任何疑问，欢迎到 Discord 社区或 GitHub Issue 提问 </Callout>

选择迁移方式

方式适用场景用户影响数据保留
简单迁移小型部署（≤ 10 用户）用户需重置密码聊天记录、设置
完整迁移大型部署对用户无感知全部数据包括密码

简单迁移

对于小型自托管部署，最简单的方法是让用户重置密码。

<Callout type={'warning'}> 限制：此方法会丢失 SSO 连接数据。如需保留 SSO 连接，请使用 完整迁移。

虽然 SSO 连接会丢失，但用户可以在使用邮箱密码登录后，通过个人资料页手动重新绑定社交账号。

示例场景：假设你之前的账户绑定了两个 SSO 账户：

迁移后使用 [email protected] 重置密码，之后再用 [email protected] 登录将会创建新用户，而非关联到原有账户。 </Callout>

步骤

  1. 配置邮件服务

    设置邮件服务以支持密码重置功能。参阅 邮件服务配置。

  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'}> 查阅 身份验证服务配置 了解完整的环境变量和 SSO 提供商配置。 </Callout>

  1. 重新部署 LobeHub

    部署启用 Better Auth 的新版本。

  2. 通知用户

    告知用户按以下步骤登录（聊天记录和设置将被保留）：

    1. 访问登录页（如 https://your-domain.com/signin）
    2. 输入之前使用的邮箱，回车

    如果启用了 Magic Link：系统会自动发送登录链接邮件，用户点击邮件中的链接即可直接登录。

    如果未启用 Magic Link：页面会显示提示信息，用户可以选择：

    • 使用之前关联的社交账号（如 Google、GitHub）登录
    • 点击「设置密码」链接，通过邮件设置新密码后登录

    1. （可选）登录后可在个人资料页进行以下操作：
      • 已关联账号：手动关联其他社交账号
      • 密码：随时设置或更新密码

<Callout type={'tip'}> 这种方法快速且配置简单。用户可通过 Magic Link、社交账号或设置新密码登录，所有数据完整保留。 登录后可随时在 个人资料页 管理密码和关联账号。 </Callout>

完整迁移

对于大型部署或需要保留用户密码和 SSO 连接的情况，请使用迁移脚本。

<Callout type={'error'}> 重要说明：

  • 务必先备份数据库！如使用 Neon，可通过 Fork 分支 创建备份
  • 迁移脚本需要 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 控制台 → Configure → Restrictions
  2. 启用「Restricted」模式

从 Clerk 控制台导出 CSV

  1. 前往 Clerk 控制台 → Configure → Settings → User exports
  2. 点击「Export users」下载 CSV 文件
  3. 保存到 scripts/clerk-to-betterauth/test/clerk_exported_users.csv

详见 Clerk 官方文档。

通过 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 配置请参阅 身份验证服务配置，包括所有支持的 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>