@lobehub/lobehub 2.0.0-next.354 → 2.0.0-next.356

package/docs/self-hosting/advanced/auth/legacy.mdx

@@ -36,6 +36,10 @@ By setting the environment variables `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CL
 
 ## Next Auth
 
+<Callout type={'tip'}>
+  To migrate from NextAuth to Better Auth, see the [NextAuth Migration Guide](/docs/self-hosting/advanced/auth/nextauth-to-betterauth).
+</Callout>
+
 Before using NextAuth, please set the following variables in LobeChat's environment variables:
 
 | Environment Variable             | Type     | Description                                                                                                                                                                                                                                |

package/docs/self-hosting/advanced/auth/legacy.zh-CN.mdx

@@ -34,6 +34,10 @@ LobeChat 与 Clerk 做了深度集成，能够为用户提供安全、便捷的
 
 ## Next Auth
 
+<Callout type={'tip'}>
+  如需从 NextAuth 迁移到 Better Auth，请参阅 [NextAuth 迁移指南](/zh/docs/self-hosting/advanced/auth/nextauth-to-betterauth)。
+</Callout>
+
 在使用 NextAuth 之前，请先在 LobeChat 的环境变量中设置以下变量：
 
 | 环境变量                             | 类型 | 描述                                                                                                           |

package/docs/self-hosting/advanced/auth/nextauth-to-betterauth.mdx

@@ -0,0 +1,326 @@
+---
+title: Migrating from NextAuth to Better Auth
+description: >-
+  Guide for migrating your LobeChat deployment from NextAuth authentication to
+  Better Auth, including simple and full migration options.
+tags:
+  - Authentication Service
+  - Better Auth
+  - NextAuth
+  - Migration
+---
+
+# Migrating from NextAuth to Better Auth
+
+This guide helps you migrate your existing NextAuth-based LobeChat deployment to Better Auth.
+
+<Callout type={'info'}>
+  Better Auth is the recommended authentication solution for LobeChat. It offers simpler configuration, more SSO providers, and better self-hosting support.
+</Callout>
+
+<Callout type={'error'}>
+  **Important Notice**:
+
+  - **Always backup your database first!** For Neon users, create a backup via [Fork Branch](https://neon.tech/docs/manage/branches#create-a-branch)
+  - LobeChat is not responsible for any data loss or issues that may occur during the migration process
+  - This guide is intended for users with development experience; not recommended for users without technical background
+  - If you have any questions, feel free to ask in our [Discord](https://discord.com/invite/AYFPHvv2jT) community or [GitHub Issue](https://github.com/lobehub/lobe-chat/issues)
+</Callout>
+
+## Choose Your Migration Path
+
+| Method                                | Best For                       | User Impact            | Data Preserved                       |
+| ------------------------------------- | ------------------------------ | ---------------------- | ------------------------------------ |
+| [Simple Migration](#simple-migration) | Small deployments (≤ 10 users) | Users need to re-login | Chat history, settings               |
+| [Full Migration](#full-migration)     | Large deployments              | Seamless for users     | Everything including SSO connections |
+
+<Callout type={'info'}>
+  **Note**: NextAuth never supported email/password login, so there are no password hashes to migrate. The main benefit of full migration is preserving SSO connections (Google, GitHub, etc.).
+</Callout>
+
+## Environment Variable Migration Reference
+
+### General Variables
+
+| NextAuth (Old)                   | Better Auth (New)    | Notes                                                    |
+| -------------------------------- | -------------------- | -------------------------------------------------------- |
+| `NEXT_PUBLIC_ENABLE_NEXT_AUTH`   | *(Deprecated)*       | No longer needed, Better Auth auto-enables with database |
+| `NEXT_AUTH_SECRET`               | `AUTH_SECRET`        | Session encryption key                                   |
+| `AUTH_URL`                       | `APP_URL`            | Application URL (for OAuth callbacks)                    |
+| `NEXT_AUTH_SSO_PROVIDERS`        | `AUTH_SSO_PROVIDERS` | SSO provider list (comma-separated)                      |
+| `NEXT_AUTH_SSO_SESSION_STRATEGY` | *(Deprecated)*       | No longer needed, Better Auth uses DB sessions           |
+
+### SSO Provider Variables
+
+SSO provider environment variables follow the same format: `AUTH_<PROVIDER>_ID` and `AUTH_<PROVIDER>_SECRET`.
+
+| NextAuth (Old)                   | Better Auth (New)       | Notes               |
+| -------------------------------- | ----------------------- | ------------------- |
+| `AUTH_GITHUB_ID`                 | `AUTH_GITHUB_ID`        | ✅ Unchanged         |
+| `AUTH_GITHUB_SECRET`             | `AUTH_GITHUB_SECRET`    | ✅ Unchanged         |
+| `AUTH_GOOGLE_ID`                 | `AUTH_GOOGLE_ID`        | ✅ Unchanged         |
+| `AUTH_GOOGLE_SECRET`             | `AUTH_GOOGLE_SECRET`    | ✅ Unchanged         |
+| `AUTH_AUTH0_ID`                  | `AUTH_AUTH0_ID`         | ✅ Unchanged         |
+| `AUTH_AUTH0_SECRET`              | `AUTH_AUTH0_SECRET`     | ✅ Unchanged         |
+| `AUTH_AUTH0_ISSUER`              | `AUTH_AUTH0_ISSUER`     | ✅ Unchanged         |
+| `AUTH_AUTHENTIK_ID`              | `AUTH_AUTHENTIK_ID`     | ✅ Unchanged         |
+| `AUTH_AUTHENTIK_SECRET`          | `AUTH_AUTHENTIK_SECRET` | ✅ Unchanged         |
+| `AUTH_AUTHENTIK_ISSUER`          | `AUTH_AUTHENTIK_ISSUER` | ✅ Unchanged         |
+| `microsoft-entra-id`             | `microsoft`             | ⚠️ Provider renamed |
+| `AUTH_MICROSOFT_ENTRA_ID_ID`     | `AUTH_MICROSOFT_ID`     | ⚠️ Variable renamed |
+| `AUTH_MICROSOFT_ENTRA_ID_SECRET` | `AUTH_MICROSOFT_SECRET` | ⚠️ Variable renamed |
+
+<Callout type={'warning'}>
+  **Note**: Microsoft Entra ID provider name changed from `microsoft-entra-id` to `microsoft`, and the environment variable prefix changed from `AUTH_MICROSOFT_ENTRA_ID_` to `AUTH_MICROSOFT_`.
+</Callout>
+
+### New Feature Variables
+
+Better Auth supports additional features with these new environment variables:
+
+| Environment Variable      | Description                               |
+| ------------------------- | ----------------------------------------- |
+| `AUTH_ALLOWED_EMAILS`     | Email whitelist (restrict registration)   |
+| `AUTH_EMAIL_VERIFICATION` | Enable email verification (set to `1`)    |
+| `ENABLE_MAGIC_LINK`       | Enable magic link login (set to `1`)      |
+| `EMAIL_SERVICE_PROVIDER`  | Email provider (`nodemailer` or `resend`) |
+
+## Simple Migration
+
+For small self-hosted deployments, the simplest approach is to let users re-login with their SSO accounts.
+
+<Callout type={'warning'}>
+  **Limitation**: This method loses SSO connection data. Use [Full Migration](#full-migration) to preserve SSO connections.
+
+  Although SSO connections will be lost, users can manually re-bind social accounts through the profile page after logging in.
+
+  **Example scenario**: If your previous account had two SSO accounts linked:
+
+  - Primary email (Google): `mail1@google.com`
+  - Secondary email (Microsoft): `mail2@outlook.com`
+
+  After migrating, logging in with `mail2@outlook.com` will create a **new user** instead of linking to your existing account.
+</Callout>
+
+### Steps
+
+1. **Update Environment Variables**
+
+   Remove NextAuth variables and add Better Auth variables:
+
+   ```bash
+   # Remove these
+   # NEXT_AUTH_SECRET=xxx
+   # AUTH_xxx related NextAuth provider configs
+
+   # Add these
+   AUTH_SECRET=your-secret-key  # openssl rand -base64 32
+
+   # Optional: Enable Google SSO (example)
+   AUTH_SSO_PROVIDERS=google
+   AUTH_GOOGLE_ID=your-google-client-id
+   AUTH_GOOGLE_SECRET=your-google-client-secret
+   ```
+
+   <Callout type={'tip'}>
+     See [Authentication Service Configuration](/docs/self-hosting/advanced/auth) for complete environment variables and SSO provider setup.
+   </Callout>
+
+2. **Redeploy LobeChat**
+
+   Deploy the new version with Better Auth enabled.
+
+3. **Notify Users**
+
+   Inform users to log in again with their previous SSO account. Chat history and settings will be preserved since user IDs remain the same.
+
+<Callout type={'tip'}>
+  This method is quick and requires minimal setup. Users just need to re-login with their existing SSO provider.
+</Callout>
+
+## Full Migration
+
+For larger deployments or when you need to preserve SSO connections, use the migration script. This migrates data from the `nextauth_accounts` table to the Better Auth `accounts` table.
+
+<Callout type={'error'}>
+  **Important Notice**:
+
+  - **Always backup your database first!** For Neon users, create a backup via [Fork Branch](https://neon.tech/docs/manage/branches#create-a-branch)
+  - Migration scripts must be **run locally after cloning the repository**, not in the deployment environment
+  - Due to the high-risk nature of user data migration, **we do not provide automatic migration during deployment**
+  - Always use dry-run mode first to verify the script runs successfully before executing
+  - Always verify in a test environment before operating on production database
+</Callout>
+
+### Prerequisites
+
+**Environment Requirements:**
+
+- Node.js 18+
+- Git (for cloning the repository)
+- pnpm (for installing dependencies)
+
+**Preparation:**
+
+1. Clone the LobeChat repository and install dependencies:
+
+   ```bash
+   git clone https://github.com/lobehub/lobe-chat.git
+   cd lobe-chat
+   pnpm install
+   ```
+
+2. Prepare the database connection string
+
+3. Ensure database schema is up to date
+
+<Callout type={'info'}>
+  If you've been on an older version for a while, your database schema may be outdated. Run this in the cloned repository:
+
+  ```bash
+  DATABASE_URL=your-database-url pnpm db:migrate
+  ```
+</Callout>
+
+### Step 1: Configure Migration Script Environment Variables
+
+Create a `.env` file in the project root (the script will automatically load it) with all environment variables:
+
+```bash
+# ============================================
+# Migration mode: test or prod
+# Recommended: Start with test mode to verify on a test database,
+# then switch to prod after confirming everything works
+# ============================================
+NEXTAUTH_TO_BETTERAUTH_MODE=test
+
+# ============================================
+# Database connection (uses corresponding variable based on mode)
+# TEST_ prefix for test environment, PROD_ prefix for production
+# ============================================
+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
+
+# ============================================
+# Database driver (optional)
+# neon: Neon serverless driver (default)
+# node: node-postgres driver
+# ============================================
+NEXTAUTH_TO_BETTERAUTH_DATABASE_DRIVER=neon
+
+# ============================================
+# Batch size (optional)
+# Number of records to process per batch, default is 300
+# ============================================
+NEXTAUTH_TO_BETTERAUTH_BATCH_SIZE=300
+
+# ============================================
+# Dry Run mode (optional)
+# Set to 1 to only print logs without modifying the database
+# Recommended: Enable for first run, disable after verification
+# ============================================
+NEXTAUTH_TO_BETTERAUTH_DRY_RUN=1
+```
+
+### Step 2: Dry-Run Verification (Test Environment)
+
+```bash
+# Run migration (NEXTAUTH_TO_BETTERAUTH_DRY_RUN=1, only logs without modifying database)
+npx tsx scripts/nextauth-to-betterauth/index.ts
+```
+
+Review the output logs, confirm no issues, then proceed to the next step.
+
+### Step 3: Execute Migration and Verify (Test Environment)
+
+Update `.env` to set `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` to `0`, then execute:
+
+```bash
+# Execute migration
+npx tsx scripts/nextauth-to-betterauth/index.ts
+
+# Verify the migration
+npx tsx scripts/nextauth-to-betterauth/verify.ts
+```
+
+After verifying the test environment migration is successful, proceed to the next step.
+
+### Step 4: Dry-Run Verification (Production Environment)
+
+1. Update `.env` file:
+   - Change `NEXTAUTH_TO_BETTERAUTH_MODE` to `prod`
+   - Change `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` back to `1`
+2. Run the script:
+
+```bash
+# Run migration (dry-run mode to verify)
+npx tsx scripts/nextauth-to-betterauth/index.ts
+```
+
+Review the output logs, confirm no issues, then proceed to the next step.
+
+### Step 5: Execute Migration and Verify (Production Environment)
+
+Update `.env` to set `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` to `0`, then execute:
+
+```bash
+# Execute migration
+npx tsx scripts/nextauth-to-betterauth/index.ts
+
+# Verify the migration
+npx tsx scripts/nextauth-to-betterauth/verify.ts
+```
+
+### Step 6: Configure Better Auth and Redeploy
+
+After migration is complete, follow [Simple Migration - Step 1](#steps) to configure Better Auth environment variables and redeploy.
+
+<Callout type={'tip'}>
+  For complete Better Auth configuration, see [Authentication Service Configuration](/docs/self-hosting/advanced/auth), including all supported SSO providers and email service configuration.
+</Callout>
+
+## What Gets Migrated
+
+| Data                                   | Simple Migration | Full Migration |
+| -------------------------------------- | ---------------- | -------------- |
+| User accounts                          | ✅ (via re-login) | ✅              |
+| SSO connections (Google, GitHub, etc.) | ❌                | ✅              |
+| Chat history                           | ✅                | ✅              |
+| User settings                          | ✅                | ✅              |
+
+<Callout type={'info'}>
+  **Note**: Sessions and verification tokens are not migrated as they are temporary data. Users will need to log in again after migration.
+</Callout>
+
+## Troubleshooting
+
+### Users can't log in after migration
+
+- Check that `AUTH_SECRET` is set correctly
+- Verify database connection is working
+- Ensure SSO provider is configured in `AUTH_SSO_PROVIDERS`
+
+### SSO users can't connect
+
+- For simple migration: Users need to log in again with their SSO account
+- For full migration: Verify the SSO provider is configured in `AUTH_SSO_PROVIDERS` with the same provider ID
+
+### Migration script fails
+
+- Check database connection string
+- Review script logs for specific errors
+- Ensure the `nextauth_accounts` table exists in your database
+
+### column "xxx" of relation "users" does not exist
+
+This error occurs because the database schema is outdated. Run `pnpm db:migrate` to update the database structure before running the migration script.
+
+## Related Reading
+
+<Cards>
+  <Card href={'/docs/self-hosting/advanced/auth'} title={'Authentication Service Configuration'} />
+
+  <Card href={'/docs/self-hosting/environment-variables/auth'} title={'Auth Environment Variables'} />
+
+  <Card href={'/docs/self-hosting/advanced/auth/legacy'} title={'Legacy Authentication (NextAuth & Clerk)'} />
+</Cards>

package/docs/self-hosting/advanced/auth/nextauth-to-betterauth.zh-CN.mdx

@@ -0,0 +1,323 @@
+---
+title: 从 NextAuth 迁移到 Better Auth
+description: 将 LobeChat 部署从 NextAuth 身份验证迁移到 Better Auth 的指南，包括简单迁移和完整迁移选项。
+tags:
+  - 身份验证服务
+  - Better Auth
+  - NextAuth
+  - 迁移
+---
+
+# 从 NextAuth 迁移到 Better Auth
+
+本指南帮助您将现有的基于 NextAuth 的 LobeChat 部署迁移到 Better Auth。
+
+<Callout type={'info'}>
+  Better Auth 是 LobeChat 推荐的身份验证解决方案。它提供更简单的配置、更多的 SSO 提供商支持，以及更好的自托管体验。
+</Callout>
+
+<Callout type={'error'}>
+  **重要提醒**：
+
+  - **务必先备份数据库**！如使用 Neon，可通过 [Fork 分支](https://neon.tech/docs/manage/branches#create-a-branch) 创建备份
+  - 迁移过程中可能出现的任何数据丢失或问题，LobeChat 概不负责
+  - 本指南适合有一定开发背景的用户，不建议无技术经验的用户自行操作
+  - 如有任何疑问，欢迎到 [Discord](https://discord.com/invite/AYFPHvv2jT) 社区或 [GitHub Issue](https://github.com/lobehub/lobe-chat/issues) 提问
+</Callout>
+
+## 选择迁移方式
+
+| 方式            | 适用场景          | 用户影响    | 数据保留          |
+| ------------- | ------------- | ------- | ------------- |
+| [简单迁移](#简单迁移) | 小型部署（≤ 10 用户） | 用户需重新登录 | 聊天记录、设置       |
+| [完整迁移](#完整迁移) | 大型部署          | 对用户无感知  | 全部数据包括 SSO 连接 |
+
+<Callout type={'info'}>
+  **注意**：NextAuth 从未支持邮箱密码登录，因此没有密码哈希需要迁移。完整迁移的主要好处是保留 SSO 连接（Google、GitHub 等）。
+</Callout>
+
+## 环境变量迁移对照表
+
+### 通用变量
+
+| NextAuth (旧)                     | Better Auth (新)      | 说明                           |
+| -------------------------------- | -------------------- | ---------------------------- |
+| `NEXT_PUBLIC_ENABLE_NEXT_AUTH`   | *(已废弃)*              | 不再需要，Better Auth 在配置数据库后自动启用 |
+| `NEXT_AUTH_SECRET`               | `AUTH_SECRET`        | 会话加密密钥                       |
+| `AUTH_URL`                       | `APP_URL`            | 应用 URL（用于 OAuth 回调）          |
+| `NEXT_AUTH_SSO_PROVIDERS`        | `AUTH_SSO_PROVIDERS` | SSO 提供商列表（逗号分隔）              |
+| `NEXT_AUTH_SSO_SESSION_STRATEGY` | *(已废弃)*              | 不再需要，Better Auth 使用数据库会话     |
+
+### SSO 提供商变量
+
+SSO 提供商的环境变量格式保持一致：`AUTH_<PROVIDER>_ID` 和 `AUTH_<PROVIDER>_SECRET`。
+
+| NextAuth (旧)                     | Better Auth (新)         | 说明               |
+| -------------------------------- | ----------------------- | ---------------- |
+| `AUTH_GITHUB_ID`                 | `AUTH_GITHUB_ID`        | ✅ 保持不变           |
+| `AUTH_GITHUB_SECRET`             | `AUTH_GITHUB_SECRET`    | ✅ 保持不变           |
+| `AUTH_GOOGLE_ID`                 | `AUTH_GOOGLE_ID`        | ✅ 保持不变           |
+| `AUTH_GOOGLE_SECRET`             | `AUTH_GOOGLE_SECRET`    | ✅ 保持不变           |
+| `AUTH_AUTH0_ID`                  | `AUTH_AUTH0_ID`         | ✅ 保持不变           |
+| `AUTH_AUTH0_SECRET`              | `AUTH_AUTH0_SECRET`     | ✅ 保持不变           |
+| `AUTH_AUTH0_ISSUER`              | `AUTH_AUTH0_ISSUER`     | ✅ 保持不变           |
+| `AUTH_AUTHENTIK_ID`              | `AUTH_AUTHENTIK_ID`     | ✅ 保持不变           |
+| `AUTH_AUTHENTIK_SECRET`          | `AUTH_AUTHENTIK_SECRET` | ✅ 保持不变           |
+| `AUTH_AUTHENTIK_ISSUER`          | `AUTH_AUTHENTIK_ISSUER` | ✅ 保持不变           |
+| `microsoft-entra-id`             | `microsoft`             | ⚠️ provider 名称变更 |
+| `AUTH_MICROSOFT_ENTRA_ID_ID`     | `AUTH_MICROSOFT_ID`     | ⚠️ 变量名变更         |
+| `AUTH_MICROSOFT_ENTRA_ID_SECRET` | `AUTH_MICROSOFT_SECRET` | ⚠️ 变量名变更         |
+
+<Callout type={'warning'}>
+  **注意**：Microsoft Entra ID 的 provider 名称从 `microsoft-entra-id` 改为 `microsoft`，相应的环境变量前缀也从 `AUTH_MICROSOFT_ENTRA_ID_` 改为 `AUTH_MICROSOFT_`。
+</Callout>
+
+### 新增功能变量
+
+Better Auth 支持更多功能，以下是新增的环境变量：
+
+| 环境变量                      | 说明                               |
+| ------------------------- | -------------------------------- |
+| `AUTH_ALLOWED_EMAILS`     | 邮箱白名单（限制注册）                      |
+| `AUTH_EMAIL_VERIFICATION` | 启用邮箱验证（设为 `1`）                   |
+| `ENABLE_MAGIC_LINK`       | 启用魔法链接登录（设为 `1`）                 |
+| `EMAIL_SERVICE_PROVIDER`  | 邮件服务提供商（`nodemailer` 或 `resend`） |
+
+## 简单迁移
+
+对于小型自托管部署，最简单的方法是让用户使用 SSO 账户重新登录。
+
+<Callout type={'warning'}>
+  **限制**：此方法会丢失 SSO 连接数据。如需保留 SSO 连接，请使用 [完整迁移](#完整迁移)。
+
+  虽然 SSO 连接会丢失，但用户可以在登录后通过个人资料页手动重新绑定社交账号。
+
+  **示例场景**：假设你之前的账户绑定了两个 SSO 账户：
+
+  - 主邮箱（Google）：`mail1@google.com`
+  - 副邮箱（Microsoft）：`mail2@outlook.com`
+
+  迁移后使用 `mail2@outlook.com` 登录将会**创建新用户**，而非关联到原有账户。
+</Callout>
+
+### 步骤
+
+1. **更新环境变量**
+
+   移除 NextAuth 变量并添加 Better Auth 变量：
+
+   ```bash
+   # 移除这些
+   # NEXT_AUTH_SECRET=xxx
+   # AUTH_xxx 相关的 NextAuth 提供商配置
+
+   # 添加这些
+   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/advanced/auth) 了解完整的环境变量和 SSO 提供商配置。
+   </Callout>
+
+2. **重新部署 LobeChat**
+
+   部署启用 Better Auth 的新版本。
+
+3. **通知用户**
+
+   告知用户使用之前的 SSO 账户重新登录。由于用户 ID 保持不变，聊天记录和设置将被保留。
+
+<Callout type={'tip'}>
+  这种方法快速且配置简单。用户只需使用现有的 SSO 提供商重新登录即可。
+</Callout>
+
+## 完整迁移
+
+对于大型部署或需要保留 SSO 连接的情况，请使用迁移脚本。这会将数据从 `nextauth_accounts` 表迁移到 Better Auth 的 `accounts` 表。
+
+<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 LobeChat 仓库并安装依赖：
+
+   ```bash
+   git clone https://github.com/lobehub/lobe-chat.git
+   cd lobe-chat
+   pnpm install
+   ```
+
+2. 准备数据库连接字符串
+
+3. 确保数据库 schema 为最新版本
+
+<Callout type={'info'}>
+  如果你长期停留在旧版本，数据库 schema 可能不是最新的。请在 clone 的仓库中运行：
+
+  ```bash
+  DATABASE_URL=your-database-url pnpm db:migrate
+  ```
+</Callout>
+
+### 步骤 1：配置迁移脚本环境变量
+
+在项目根目录创建 `.env` 文件（脚本会自动加载），配置所有环境变量：
+
+```bash
+# ============================================
+# 迁移模式：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
+```
+
+### 步骤 2：Dry-Run 验证（测试环境）
+
+```bash
+# 运行迁移（NEXTAUTH_TO_BETTERAUTH_DRY_RUN=1，只打印日志不修改数据库）
+npx tsx scripts/nextauth-to-betterauth/index.ts
+```
+
+检查输出日志，确认无异常后继续下一步。
+
+### 步骤 3：执行迁移并验证（测试环境）
+
+修改 `.env` 将 `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` 改为 `0`，然后执行：
+
+```bash
+# 执行迁移
+npx tsx scripts/nextauth-to-betterauth/index.ts
+
+# 验证迁移结果
+npx tsx scripts/nextauth-to-betterauth/verify.ts
+```
+
+验证测试环境迁移结果无误后，继续下一步。
+
+### 步骤 4：Dry-Run 验证（生产环境）
+
+1. 修改 `.env` 文件：
+   - 将 `NEXTAUTH_TO_BETTERAUTH_MODE` 改为 `prod`
+   - 将 `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` 改回 `1`
+2. 运行脚本：
+
+```bash
+# 运行迁移（dry-run 模式验证）
+npx tsx scripts/nextauth-to-betterauth/index.ts
+```
+
+检查输出日志，确认无异常后继续下一步。
+
+### 步骤 5：执行迁移并验证（生产环境）
+
+修改 `.env` 将 `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` 改为 `0`，然后执行：
+
+```bash
+# 执行迁移
+npx tsx scripts/nextauth-to-betterauth/index.ts
+
+# 验证迁移结果
+npx tsx scripts/nextauth-to-betterauth/verify.ts
+```
+
+### 步骤 6：配置 Better Auth 并重新部署
+
+迁移完成后，参照 [简单迁移 - 步骤 1](#步骤) 配置 Better Auth 环境变量并重新部署。
+
+<Callout type={'tip'}>
+  完整的 Better Auth 配置请参阅 [身份验证服务配置](/zh/docs/self-hosting/advanced/auth)，包括所有支持的 SSO 提供商和邮件服务配置。
+</Callout>
+
+## 迁移内容对比
+
+| 数据                      | 简单迁移      | 完整迁移 |
+| ----------------------- | --------- | ---- |
+| 用户账户                    | ✅（通过重新登录） | ✅    |
+| SSO 连接（Google、GitHub 等） | ❌         | ✅    |
+| 聊天记录                    | ✅         | ✅    |
+| 用户设置                    | ✅         | ✅    |
+
+<Callout type={'info'}>
+  **注意**：Sessions 和 verification tokens 不会被迁移，因为它们是临时数据。迁移后用户需要重新登录。
+</Callout>
+
+## 常见问题
+
+### 迁移后用户无法登录
+
+- 检查 `AUTH_SECRET` 是否正确设置
+- 验证数据库连接是否正常
+- 确保 SSO 提供商已在 `AUTH_SSO_PROVIDERS` 中配置
+
+### SSO 用户无法连接
+
+- 简单迁移：用户需要使用 SSO 账户重新登录
+- 完整迁移：验证 SSO 提供商已在 `AUTH_SSO_PROVIDERS` 中配置，且使用相同的 provider ID
+
+### 迁移脚本失败
+
+- 检查数据库连接字符串
+- 查看脚本日志了解具体错误
+- 确保数据库中存在 `nextauth_accounts` 表
+
+### column "xxx" of relation "users" does not exist
+
+这是因为数据库 schema 未更新。请先运行 `pnpm db:migrate` 更新数据库结构，然后再执行迁移脚本。
+
+## 相关阅读
+
+<Cards>
+  <Card href={'/zh/docs/self-hosting/advanced/auth'} title={'身份验证服务配置'} />
+
+  <Card href={'/zh/docs/self-hosting/environment-variables/auth'} title={'认证相关环境变量'} />
+
+  <Card href={'/zh/docs/self-hosting/advanced/auth/legacy'} title={'旧版身份验证（NextAuth 和 Clerk）'} />
+</Cards>