LobeHub 1.x 升级到 2.0 需要处理哪些破坏性变更？

如果你正在把自托管的 LobeHub 1.x 部署升级到 2.0，需要处理的核心变更集中在四件事：认证系统从 NextAuth / Clerk 全面切换到 Better Auth、一批旧环境变量被移除、Client DB（PGlite）模式被移除（只保留 Server DB）、以及 PostgreSQL 版本与全文搜索后端的要求变化。本文基于仓库中的 2.0 破坏性变更文档、NextAuth 迁移指南 和 Clerk 迁移指南，给出逐条变更的核对清单、环境变量改法、迁移脚本执行步骤和验证方式。

升级前先做好三件事（文档明确要求）：

• 先备份数据库。Neon 用户可通过 Fork Branch 创建备份；
• 迁移脚本必须在克隆仓库后的本地环境运行，不能在部署环境里跑，部署过程也不提供自动迁移；
• 完整迁移要求本地具备 Node.js 18+、Git、pnpm。

一、对照变更清单：哪些东西被移除、哪些新增

移除的环境变量

2.0 移除了以下变量，升级前应从部署配置中删掉：

环境变量	移除原因
ACCESS_CODE	不再支持，改用 Better Auth 认证系统
NEXT_PUBLIC_SERVICE_MODE	2.0 仅支持 Server DB 模式，Client DB (PGlite) 已移除
NEXT_PUBLIC_ENABLE_BETTER_AUTH	通过 AUTH_SECRET 是否存在自动检测
NEXT_PUBLIC_AUTH_URL / AUTH_URL	从请求头中自动检测
NEXT_PUBLIC_ENABLE_NEXT_AUTH	NextAuth 已移除
NEXT_AUTH_SECRET	NextAuth 已移除
NEXT_AUTH_SSO_PROVIDERS	NextAuth 已移除
NEXTAUTH_URL	NextAuth 已移除
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Clerk 已移除
CLERK_SECRET_KEY	Clerk 已移除

另外两个 NextAuth 变量也一并废弃：NEXT_PUBLIC_ENABLE_NEXT_AUTH 不再需要（Better Auth 有数据库时自动启用），NEXT_AUTH_SSO_SESSION_STRATEGY 也不再需要（Better Auth 使用数据库会话）。

新增的必需环境变量

2.0 只支持 Better Auth，以下两个变量成为必需（详见 认证环境变量参考）：

• AUTH_SECRET：用于加密会话令牌，可用 openssl rand -base64 32 生成；
• JWKS_KEY：用于签名和验证 JWT，包括 OIDC JWT token 和内部服务调用认证 token。文档要求它必须是包含 RS256 RSA 密钥对的 JWKS JSON 字符串，环境变量文档中提供了生成该密钥的工具，仓库内也有对应的 密钥生成脚本。

可选变量按需配置：AUTH_SSO_PROVIDERS（逗号分隔的 SSO 提供商列表）、INTERNAL_JWT_EXPIRATION（默认 30s）、AUTH_EMAIL_VERIFICATION（设为 1 要求邮箱验证），以及 SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASS 等邮件功能变量。

数据库模式变更

2.0 只支持 Server DB 模式，Client DB（PGlite）不再支持。如果你之前使用 NEXT_PUBLIC_SERVICE_MODE=client，必须迁移到 Server DB 部署方式，部署入口见 快速开始。

PostgreSQL 版本与全文搜索后端

• 2.0 推荐使用 PostgreSQL 17 及以上版本；
• 2.0 引入了 pg_search 扩展做全文搜索。如果你使用 Neon：Neon 已停止为新项目提供 pg_search，并通知受影响的现有客户该扩展将在 2026 年 9 月 21 日移除，现有 Neon 部署应完成 从 pg_search 迁移到 Elasticsearch；选择搜索后端前建议先阅读 全文搜索 文档；
• 如果使用 Docker 自建数据库，推荐 paradedb/paradedb:latest-pg17 镜像。

二、按你原来的认证方式选择迁移路径

两条路径适用于所有场景：简单迁移保留聊天记录和设置（用户身份不变），完整迁移额外保留 SSO 连接（NextAuth 场景）或密码、SSO 连接、两步验证（Clerk 场景）。

方法	适用	用户侧影响	保留的数据
简单迁移	小规模部署（≤ 10 用户）	用户需重新登录（NextAuth）或重置密码（Clerk）	聊天记录、设置
完整迁移	较大规模部署	用户无感知	全部数据，包括 SSO 连接

文档同时提醒：NextAuth 从未支持邮箱/密码登录，没有密码哈希需要迁移，完整迁移的主要收益是保留 SSO 连接（Google、GitHub 等）。简单迁移的已知限制是 SSO 连接数据会丢失——用户登录后可在个人资料页手动重新绑定社交账号，但用旧的第二个 SSO 账号登录会创建新用户而不是关联到原账号。

NextAuth 场景：简单迁移

1. 更新环境变量：删除 NextAuth 变量，加入 Better Auth 变量：

   # 删除这些
   # NEXT_AUTH_SECRET=xxx
   # AUTH_xxx 相关的 NextAuth provider 配置
   
   # 添加这些
   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
   

   其中 AUTH_SECRET 用 openssl rand -base64 32 的生成结果替换；AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET 替换为你自己的 Google OAuth 凭据，不启用 SSO 可省略。

2. 重新部署 LobeHub。

3. 通知用户用原来的 SSO 账号重新登录。用户 ID 不变，聊天记录和设置会保留。

环境变量新旧对照（常用项）：

NextAuth（旧）	Better Auth（新）
NEXT_AUTH_SECRET	AUTH_SECRET
AUTH_URL	APP_URL
NEXT_AUTH_SSO_PROVIDERS	AUTH_SSO_PROVIDERS
AUTH_MICROSOFT_ENTRA_ID_ID / _SECRET / _TENANT_ID / _BASE_URL	AUTH_MICROSOFT_ID / AUTH_MICROSOFT_SECRET / AUTH_MICROSOFT_TENANT_ID / AUTH_MICROSOFT_AUTHORITY_URL

注意 Microsoft Entra ID 的 provider 名从 microsoft-entra-id 改成了 microsoft，环境变量前缀从 AUTH_MICROSOFT_ENTRA_ID_ 改为 AUTH_MICROSOFT_。GitHub、Google、Auth0、Authentik 等 provider 的 AUTH_<PROVIDER>_ID / AUTH_<PROVIDER>_SECRET 命名格式不变。

NextAuth 场景：完整迁移（保留 SSO 连接）

脚本将数据从 nextauth_accounts 表迁移到 Better Auth 的 accounts 表。

准备：

git clone https://github.com/lobehub/lobehub.git
cd lobehub
pnpm install

如果数据库 schema 较旧（在 1.x 上运行了较长时间），先在克隆的仓库里更新结构：

DATABASE_URL=your-database-url pnpm db:migrate

Step 1：在项目根目录创建 .env（脚本会自动加载），按 test/prod 双环境配置：

# 迁移模式：test 或 prod。建议先用 test 模式在测试库验证，再切 prod
NEXTAUTH_TO_BETTERAUTH_MODE=test

# 数据库连接（按模式取对应变量：TEST_ 前缀为测试环境，PROD_ 前缀为生产环境）
TEST_NEXTAUTH_TO_BETTERAUTH_DATABASE_URL=postgresql://user:pass@test-host:5432/testdb
PROD_NEXTAUTH_TO_BETTERAUTH_DATABASE_URL=postgresql://user:pass@prod-host:5432/proddb

# 数据库驱动（可选）：neon 为 Neon serverless 驱动（默认），node 为 node-postgres 驱动
NEXTAUTH_TO_BETTERAUTH_DATABASE_DRIVER=neon

# 批大小（可选，默认 300）
NEXTAUTH_TO_BETTERAUTH_BATCH_SIZE=300

# Dry Run 模式（可选）：设为 1 时只打印日志、不修改数据库。首次运行建议开启
NEXTAUTH_TO_BETTERAUTH_DRY_RUN=1

Step 2：测试环境 dry-run。 保持 NEXTAUTH_TO_BETTERAUTH_DRY_RUN=1（只打印日志、不改库），执行：

bun run scripts/nextauth-to-betterauth/index.ts

检查输出日志确认无问题后再进入下一步。

Step 3：测试环境正式执行并验证。 将 .env 中 NEXTAUTH_TO_BETTERAUTH_DRY_RUN 改为 0：

# 执行迁移
bun run scripts/nextauth-to-betterauth/index.ts

# 验证迁移
bun run scripts/nextauth-to-betterauth/verify.ts

测试环境验证通过后，Step 4/5 对生产环境重复同样的 dry-run → 正式执行 → verify 流程：先把 .env 的 NEXTAUTH_TO_BETTERAUTH_MODE 改为 prod、NEXTAUTH_TO_BETTERAUTH_DRY_RUN 改回 1 跑一次 dry-run，确认日志无问题后再把 dry-run 关掉执行 index.ts 和 verify.ts。

Step 6： 迁移完成后，按上面「简单迁移」第 1 步的方式配置 Better Auth 环境变量（含 AUTH_SECRET、JWKS_KEY 及各 SSO provider 变量）并重新部署。

Clerk 场景

• 简单迁移：先配置邮件服务（用于密码重置），再删除 Clerk 变量、加入 Better Auth 变量，重新部署后通知用户走登录页流程：输入原邮箱回车，开启 Magic Link 时会直接收到登录链接；未开启时可选择用已绑定的社交账号登录，或点击 "Set Password" 收邮件设置新密码。聊天历史和设置会保留。

• 完整迁移：流程与 NextAuth 完整迁移类似，.env 变量前缀换成 CLERK_TO_BETTERAUTH_（含 CLERK_TO_BETTERAUTH_MODE、TEST_/PROD_CLERK_TO_BETTERAUTH_DATABASE_URL、CLERK_TO_BETTERAUTH_CLERK_SECRET_KEY、CLERK_TO_BETTERAUTH_DATABASE_DRIVER、CLERK_TO_BETTERAUTH_DRY_RUN），额外多一步数据导出：在导出前先去 Clerk Dashboard 的 Configure → Restrictions 开启 "Restricted" 模式停止新用户注册；导出方式二选一——Dashboard 导出 CSV 并放到 scripts/clerk-to-betterauth/test/clerk_exported_users.csv，或运行 API 导出脚本：

  bun run scripts/clerk-to-betterauth/export-clerk-users-with-api.ts
  

  之后同样是 test 环境 dry-run → 执行 → bun run scripts/clerk-to-betterauth/verify.ts 验证 → prod 环境重复一遍。完整步骤以 Clerk 迁移指南 为准。

三、升级后的验证与常见问题

验证迁移结果：

• 脚本层面：test 和 prod 两个环境都运行了对应的 verify.ts（bun run scripts/nextauth-to-betterauth/verify.ts 或 bun run scripts/clerk-to-betterauth/verify.ts）；
• 登录层面：会话和验证 token 属于临时数据不会被迁移，升级后所有用户都需要重新登录。用户如遇登录问题，可先清除浏览器站点数据（DevTools → Application → Storage → Clear site data）再刷新重试。

登录不上去时，文档给出的检查项：

• AUTH_SECRET 是否设置正确；
• 数据库连接是否正常；
• SSO provider 是否已配置进 AUTH_SSO_PROVIDERS（完整迁移时 provider ID 要与其一致）。

迁移脚本报错：

• 检查数据库连接字符串，查看脚本日志中的具体错误；NextAuth 场景还需确认数据库中存在 nextauth_accounts 表；Clerk 场景确认 CSV/JSON 文件位置正确；
• 出现 column "xxx" of relation "users" does not exist 说明数据库 schema 过期，先运行 pnpm db:migrate 更新结构再跑迁移脚本。

email_not_found 错误： 如果看到重定向到 signin?callbackUrl=...&error=email_not_found，说明 LobeHub 拿不到用户邮箱。Better Auth 要求所有 SSO provider 必须配置为返回邮箱信息，否则用户无法登录。常见原因：SSO 连接未申请邮箱权限（需在 provider 的 Attributes 中启用 Email Address），或身份提供方（如 Casdoor、Logto）中用户未配置邮箱。文档给出的处理顺序：先按 Casdoor Webhook 配置 或 Logto Webhook 配置 配置 Webhook 同步用户数据，再在身份提供方管理端为用户补配邮箱，之后用户即可登录。

四、边界与限制

• 会话（sessions）和验证 token 不迁移，属临时数据；
• 简单迁移丢失 SSO 连接（Clerk 场景还丢失密码哈希和两步验证数据），用户需重新绑定社交账号；
• 迁移脚本只应在克隆仓库的本地环境运行，部署时不提供自动迁移；
• 使用 Neon 的部署要注意 pg_search 扩展的移除时间线（2026 年 9 月 21 日），需要另行完成 Elasticsearch 迁移，这是独立于认证迁移的一条工作项，参见 pg_search 迁移文档。

更多变量细节可继续查阅 认证环境变量 与 迁移技术细节。