@lobehub/lobehub 2.0.0-next.339 → 2.0.0-next.340

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

@@ -0,0 +1,360 @@
+---
+title: 从 Clerk 迁移到 Better Auth
+description: 将 LobeChat 部署从 Clerk 身份验证迁移到 Better Auth 的指南，包括简单迁移和完整迁移选项。
+tags:
+  - 身份验证服务
+  - Better Auth
+  - Clerk
+  - 迁移
+---
+
+# 从 Clerk 迁移到 Better Auth
+
+本指南帮助您将现有的基于 Clerk 的 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) 社区提问
+</Callout>
+
+## 选择迁移方式
+
+| 方式            | 适用场景            | 用户影响    | 数据保留     |
+| ------------- | --------------- | ------- | -------- |
+| [简单迁移](#简单迁移) | 小型部署（\< 100 用户） | 用户需重置密码 | 聊天记录、设置  |
+| [完整迁移](#完整迁移) | 大型部署            | 对用户无感知  | 全部数据包括密码 |
+
+## 简单迁移
+
+对于小型自托管部署，最简单的方法是让用户重置密码。
+
+<Callout type={'warning'}>
+  **限制**：此方法会丢失 SSO 连接数据。如需保留 SSO 连接，请使用 [完整迁移](#完整迁移)。
+
+  **示例场景**：假设你之前的账户绑定了两个 SSO 账户：
+
+  - 主邮箱（Google）：`mail1@google.com`
+  - 副邮箱（Microsoft）：`mail2@outlook.com`
+
+  迁移后使用 `mail1@google.com` 重置密码，之后再用 `mail2@outlook.com` 登录将会**创建新用户**，而非关联到原有账户。
+</Callout>
+
+![个人资料页 - 关联账号信息](https://hub-apac-1.lobeobjects.space/docs/43dfa498b82a58c9f99e805e88ea711a.png)
+
+### 步骤
+
+1. **配置邮件服务**
+
+   设置邮件服务以支持密码重置功能。参阅 [邮件服务配置](/zh/docs/self-hosting/advanced/auth#邮件服务配置)。
+
+2. **更新环境变量**
+
+   移除 Clerk 变量并添加 Better Auth 变量：
+
+   ```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/advanced/auth) 了解完整的环境变量和 SSO 提供商配置。
+   </Callout>
+
+3. **重新部署 LobeChat**
+
+   部署启用 Better Auth 的新版本。
+
+4. **通知用户**
+
+   告知用户按以下步骤登录（聊天记录和设置将被保留）：
+
+   1. 访问登录页（如 `https://your-domain.com/signin`）
+   2. 输入之前使用的邮箱，回车
+
+   如果启用了 Magic Link：系统会自动发送登录链接邮件，用户点击邮件中的链接即可直接登录。
+
+   如果未启用 Magic Link：页面会显示提示信息，用户可以选择：
+
+   - 使用之前关联的社交账号（如 Google、GitHub）登录
+   - 点击「设置密码」链接，通过邮件设置新密码后登录
+
+   ![LobeChat 登录页面 - 社交账号登录提示](https://hub-apac-1.lobeobjects.space/docs/8d0563701fcd17ad7252a72b1746dd42.png)
+
+   3. （可选）登录后可在个人资料页进行以下操作：
+      - 已关联账号：手动关联其他社交账号
+      - 密码：随时设置或更新密码
+
+<Callout type={'tip'}>
+  这种方法快速且配置简单。用户可通过 Magic Link、社交账号或设置新密码登录，所有数据完整保留。
+  登录后可随时在 [个人资料页](/settings/profile) 管理密码和关联账号。
+</Callout>
+
+## 完整迁移
+
+对于大型部署或需要保留用户密码和 SSO 连接的情况，请使用迁移脚本。
+
+<Callout type={'error'}>
+  **重要说明**：
+
+  - 迁移脚本需要 **clone 仓库后在本地运行**，不是在部署环境中执行
+  - 由于迁移涉及用户数据，风险较高，**官方不提供部署时自动迁移功能**
+  - 请务必在测试环境验证后再操作生产数据库
+</Callout>
+
+<Callout type={'warning'}>
+  **迁移前准备**：
+
+  - 使用 [Neon Fork 分支](https://neon.tech/docs/manage/branches#create-a-branch) 创建测试数据库
+  - 使用 Clerk Development 环境的 API 密钥
+  - 先在 test 模式下验证，确认成功后再切换到 prod 模式
+</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. 准备以下信息：
+   - 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 并重新部署
+
+迁移完成后，需要配置 Better Auth 环境变量并重新部署：
+
+1. **移除 Clerk 环境变量**：
+
+   ```bash
+   # 移除这些
+   # NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=xxx
+   # CLERK_SECRET_KEY=xxx
+   ```
+
+2. **添加 Better Auth 环境变量**：
+
+   ```bash
+   # 必需
+   AUTH_SECRET=your-secret-key  # openssl rand -base64 32
+
+   # 可选：配置 SSO 提供商（示例）
+   AUTH_SSO_PROVIDERS=google,github
+   AUTH_GOOGLE_ID=your-google-client-id
+   AUTH_GOOGLE_SECRET=your-google-client-secret
+   AUTH_GITHUB_ID=your-github-client-id
+   AUTH_GITHUB_SECRET=your-github-client-secret
+
+   # 可选：配置邮件服务（用于密码重置、邮箱验证等）
+   # 参阅身份验证服务配置文档了解详情
+   ```
+
+3. **重新部署 LobeChat**
+
+<Callout type={'tip'}>
+  完整的 Better Auth 配置请参阅 [身份验证服务配置](/zh/docs/self-hosting/advanced/auth)，包括所有支持的 SSO 提供商和邮件服务配置。
+</Callout>
+
+## 迁移内容对比
+
+| 数据                      | 简单迁移      | 完整迁移 |
+| ----------------------- | --------- | ---- |
+| 用户账户                    | ✅（通过密码重置） | ✅    |
+| 密码哈希                    | ❌         | ✅    |
+| SSO 连接（Google、GitHub 等） | ❌         | ✅    |
+| 双因素认证                   | ❌         | ✅    |
+| 聊天记录                    | ✅         | ✅    |
+| 用户设置                    | ✅         | ✅    |
+
+## 常见问题
+
+### 迁移后用户无法登录
+
+- 确保邮件服务已配置用于密码重置
+- 检查 `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/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>

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

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

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

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

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

@@ -60,39 +60,39 @@ To enable Better Auth in LobeChat, set the following environment variables:
 Click on a provider below for detailed configuration guides:
 
 <Cards>
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/github'} title={'GitHub'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/github'} title={'GitHub'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/google'} title={'Google'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/google'} title={'Google'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/microsoft'} title={'Microsoft'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/microsoft'} title={'Microsoft'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/apple'} title={'Apple'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/apple'} title={'Apple'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/cognito'} title={'AWS Cognito'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/cognito'} title={'AWS Cognito'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/auth0'} title={'Auth0'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/auth0'} title={'Auth0'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/authelia'} title={'Authelia'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/authelia'} title={'Authelia'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/authentik'} title={'Authentik'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/authentik'} title={'Authentik'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/casdoor'} title={'Casdoor'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/casdoor'} title={'Casdoor'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/keycloak'} title={'Keycloak'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/keycloak'} title={'Keycloak'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/logto'} title={'Logto'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/logto'} title={'Logto'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/okta'} title={'Okta'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/okta'} title={'Okta'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/zitadel'} title={'ZITADEL'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/zitadel'} title={'ZITADEL'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/generic-oidc'} title={'Generic OIDC'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/generic-oidc'} title={'Generic OIDC'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/feishu'} title={'Feishu'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/feishu'} title={'Feishu'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/better-auth/wechat'} title={'WeChat'} />
+  <Card href={'/docs/self-hosting/advanced/auth/providers/wechat'} title={'WeChat'} />
 </Cards>
 
 ## Callback URL Format
@@ -104,19 +104,44 @@ When configuring OAuth providers, use the following callback URL format:
 
 ## Email Service Configuration
 
-Used by email verification, password reset, and magic-link delivery. Choose a provider, then fill the matching variables:
-
-| Environment Variable      | Type        | Description                                                                                                                                       |
-| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AUTH_EMAIL_VERIFICATION` | Optional    | Set to `1` to require email verification before sign in (off by default)                                                                          |
-| `EMAIL_SERVICE_PROVIDER`  | Optional    | Email provider selector: `nodemailer` (default, SMTP) or `resend`                                                                                 |
-| `SMTP_HOST`               | Required    | SMTP server hostname (e.g., `smtp.gmail.com`). Used when `EMAIL_SERVICE_PROVIDER=nodemailer`                                                      |
-| `SMTP_PORT`               | Required    | SMTP server port (usually `587` for TLS, `465` for SSL). Used when `EMAIL_SERVICE_PROVIDER=nodemailer`                                            |
-| `SMTP_SECURE`             | Optional    | `true` for SSL (port 465), `false` for TLS (port 587). Used when `EMAIL_SERVICE_PROVIDER=nodemailer`                                              |
-| `SMTP_USER`               | Required    | SMTP auth username. Used when `EMAIL_SERVICE_PROVIDER=nodemailer`                                                                                 |
-| `SMTP_PASS`               | Required    | SMTP auth password. Used when `EMAIL_SERVICE_PROVIDER=nodemailer`                                                                                 |
-| `RESEND_API_KEY`          | Required    | Resend API key. Required when `EMAIL_SERVICE_PROVIDER=resend`                                                                                     |
-| `RESEND_FROM`             | Recommended | Default sender address (e.g., `noreply@your-verified-domain.com`). Must be a domain verified in Resend. Used when `EMAIL_SERVICE_PROVIDER=resend` |
+Used by email verification, password reset, and magic-link delivery. Two providers are supported:
+
+### Option 1: Nodemailer (SMTP)
+
+Send emails via SMTP protocol, suitable for users with existing email services. See [Nodemailer SMTP docs](https://nodemailer.com/smtp/).
+
+| Environment Variable     | Type     | Description                                             | Example             |
+| ------------------------ | -------- | ------------------------------------------------------- | ------------------- |
+| `EMAIL_SERVICE_PROVIDER` | Optional | Set to `nodemailer` (default)                           | `nodemailer`        |
+| `SMTP_HOST`              | Required | SMTP server hostname                                    | `smtp.gmail.com`    |
+| `SMTP_PORT`              | Required | SMTP server port (`587` for TLS, `465` for SSL)         | `587`               |
+| `SMTP_SECURE`            | Optional | `true` for SSL (port 465), `false` for TLS (port 587)   | `false`             |
+| `SMTP_USER`              | Required | SMTP auth username                                      | `user@gmail.com`    |
+| `SMTP_PASS`              | Required | SMTP auth password                                      | `your-app-password` |
+
+<Callout type={'warning'}>
+  When using Gmail, you must use an App Password instead of your account password. Generate one at [Google App Passwords](https://myaccount.google.com/apppasswords).
+</Callout>
+
+### Option 2: Resend
+
+[Resend](https://resend.com/) is a modern email API service with simple setup, recommended for new users.
+
+| Environment Variable     | Type        | Description                              | Example                     |
+| ------------------------ | ----------- | ---------------------------------------- | --------------------------- |
+| `EMAIL_SERVICE_PROVIDER` | Required    | Set to `resend`                          | `resend`                    |
+| `RESEND_API_KEY`         | Required    | Resend API Key                           | `re_xxxxxxxxxxxxxxxxxxxxxx` |
+| `RESEND_FROM`            | Recommended | Sender address, must be a verified domain| `noreply@your-domain.com`   |
+
+<Callout type={'info'}>
+  Before using Resend, you need to [verify your sending domain](https://resend.com/docs/dashboard/domains/introduction), otherwise emails can only be sent to your own address.
+</Callout>
+
+### Common Configuration
+
+| Environment Variable      | Type     | Description                                              | Example |
+| ------------------------- | -------- | -------------------------------------------------------- | ------- |
+| `AUTH_EMAIL_VERIFICATION` | Optional | Set to `1` to require email verification (off by default)| `1`     |
 
 ## Magic Link (Passwordless) Login
 

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

@@ -57,39 +57,39 @@ LobeChat 使用 [Better Auth](https://www.better-auth.com) 作为身份验证解
 点击下方提供商查看详细配置指南：
 
 <Cards>
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/github'} title={'GitHub'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/github'} title={'GitHub'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/google'} title={'Google'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/google'} title={'Google'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/microsoft'} title={'Microsoft'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/microsoft'} title={'Microsoft'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/apple'} title={'Apple'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/apple'} title={'Apple'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/cognito'} title={'AWS Cognito'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/cognito'} title={'AWS Cognito'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/auth0'} title={'Auth0'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/auth0'} title={'Auth0'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/authelia'} title={'Authelia'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/authelia'} title={'Authelia'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/authentik'} title={'Authentik'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/authentik'} title={'Authentik'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/casdoor'} title={'Casdoor'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/casdoor'} title={'Casdoor'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/keycloak'} title={'Keycloak'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/keycloak'} title={'Keycloak'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/logto'} title={'Logto'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/logto'} title={'Logto'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/okta'} title={'Okta'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/okta'} title={'Okta'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/zitadel'} title={'ZITADEL'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/zitadel'} title={'ZITADEL'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/generic-oidc'} title={'Generic OIDC'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/generic-oidc'} title={'Generic OIDC'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/feishu'} title={'飞书'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/feishu'} title={'飞书'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/wechat'} title={'微信'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/wechat'} title={'微信'} />
 </Cards>
 
 ## 回调 URL 格式
@@ -101,19 +101,44 @@ LobeChat 使用 [Better Auth](https://www.better-auth.com) 作为身份验证解
 
 ## 邮件服务配置
 
-用于邮箱验证、密码重置和魔法链接发送。先选择邮件服务，再填对应变量：
-
-| 环境变量                      | 类型 | 描述                                                                                        |
-| ------------------------- | -- | ----------------------------------------------------------------------------------------- |
-| `AUTH_EMAIL_VERIFICATION` | 可选 | 设置为 `1` 以要求用户在登录前验证邮箱（默认关闭）                                                               |
-| `EMAIL_SERVICE_PROVIDER`  | 可选 | 邮件服务选择：`nodemailer`（默认，SMTP）或 `resend`                                                    |
-| `SMTP_HOST`               | 必选 | SMTP 服务器主机名（如 `smtp.gmail.com`），仅在 `EMAIL_SERVICE_PROVIDER=nodemailer` 时需要                |
-| `SMTP_PORT`               | 必选 | SMTP 服务器端口（TLS 通常为 `587`，SSL 为 `465`），仅在 `EMAIL_SERVICE_PROVIDER=nodemailer` 时需要          |
-| `SMTP_SECURE`             | 可选 | SSL 设置为 `true`（端口 465），TLS 设置为 `false`（端口 587），仅在 `EMAIL_SERVICE_PROVIDER=nodemailer` 时需要 |
-| `SMTP_USER`               | 必选 | SMTP 认证用户名，仅在 `EMAIL_SERVICE_PROVIDER=nodemailer` 时需要                                     |
-| `SMTP_PASS`               | 必选 | SMTP 认证密码，仅在 `EMAIL_SERVICE_PROVIDER=nodemailer` 时需要                                      |
-| `RESEND_API_KEY`          | 必选 | Resend API Key，`EMAIL_SERVICE_PROVIDER=resend` 时必填                                        |
-| `RESEND_FROM`             | 推荐 | 默认发件人地址（如 `noreply@已验证域名`），需为 Resend 已验证域名下的邮箱，`EMAIL_SERVICE_PROVIDER=resend` 时使用        |
+用于邮箱验证、密码重置和魔法链接发送。支持两种邮件服务：
+
+### 方式一：Nodemailer（SMTP）
+
+使用 SMTP 协议发送邮件，适合已有邮箱服务的用户。参考 [Nodemailer SMTP 文档](https://nodemailer.com/smtp/)。
+
+| 环境变量                     | 类型 | 描述                                              | 示例                 |
+| ------------------------- | -- | ----------------------------------------------- | ------------------ |
+| `EMAIL_SERVICE_PROVIDER`  | 可选 | 设置为 `nodemailer`（默认值）                           | `nodemailer`       |
+| `SMTP_HOST`               | 必选 | SMTP 服务器主机名                                     | `smtp.gmail.com`   |
+| `SMTP_PORT`               | 必选 | SMTP 服务器端口（TLS 通常为 `587`，SSL 为 `465`）           | `587`              |
+| `SMTP_SECURE`             | 可选 | SSL 设置为 `true`（端口 465），TLS 设置为 `false`（端口 587） | `false`            |
+| `SMTP_USER`               | 必选 | SMTP 认证用户名                                      | `user@gmail.com`   |
+| `SMTP_PASS`               | 必选 | SMTP 认证密码                                       | `your-app-password`|
+
+<Callout type={'warning'}>
+  使用 Gmail 时，需使用应用专用密码而非账户密码。前往 [Google 应用专用密码](https://myaccount.google.com/apppasswords) 生成。
+</Callout>
+
+### 方式二：Resend
+
+[Resend](https://resend.com/) 是一个现代邮件 API 服务，配置简单，推荐新用户使用。
+
+| 环境变量                     | 类型 | 描述                                 | 示例                          |
+| ------------------------- | -- | ---------------------------------- | --------------------------- |
+| `EMAIL_SERVICE_PROVIDER`  | 必选 | 设置为 `resend`                       | `resend`                    |
+| `RESEND_API_KEY`          | 必选 | Resend API Key                     | `re_xxxxxxxxxxxxxxxxxxxxxx` |
+| `RESEND_FROM`             | 推荐 | 发件人地址，需为 Resend 已验证域名下的邮箱          | `noreply@your-domain.com`   |
+
+<Callout type={'info'}>
+  使用 Resend 前需先 [验证发件域名](https://resend.com/docs/dashboard/domains/introduction)，否则只能发送到自己的邮箱。
+</Callout>
+
+### 通用配置
+
+| 环境变量                      | 类型 | 描述                           | 示例 |
+| ------------------------- | -- | ---------------------------- | -- |
+| `AUTH_EMAIL_VERIFICATION` | 可选 | 设置为 `1` 以要求用户在登录前验证邮箱（默认关闭） | `1`|
 
 ## 魔法链接（免密）登录
 

package/locales/ar/auth.json

@@ -191,7 +191,7 @@
   "profile.usernameRule": "يمكن أن يحتوي اسم المستخدم على أحرف أو أرقام أو شرطة سفلية فقط",
   "profile.usernameUpdateFailed": "فشل في تحديث اسم المستخدم، يرجى المحاولة لاحقًا",
   "signin.subtitle": "سجّل أو قم بتسجيل الدخول إلى حساب {{appName}} الخاص بك",
-  "signin.title": "للتعاون مع الوكلاء",
+  "signin.title": "فرق الوكلاء التي تنمو معك",
   "signout": "تسجيل الخروج",
   "signup": "إنشاء حساب",
   "stats.aiheatmaps": "مؤشر النشاط",

package/locales/ar/desktop-onboarding.json

@@ -73,6 +73,7 @@
   "screen5.badge": "تسجيل الدخول",
   "screen5.description": "سجّل الدخول لمزامنة الوكلاء والمجموعات والإعدادات والسياق عبر جميع الأجهزة.",
   "screen5.errors.desktopOnlyOidc": "تفويض OIDC متاح فقط في تطبيق سطح المكتب.",
+  "screen5.legacyLocalDb.link": "ترحيل قاعدة البيانات المحلية القديمة",
   "screen5.methods.cloud.description": "سجّل الدخول باستخدام حساب LobeHub Cloud الخاص بك لمزامنة كل شيء بسلاسة",
   "screen5.methods.cloud.name": "LobeHub Cloud",
   "screen5.methods.selfhost.description": "اتصل بنسختك الخاصة من خادم LobeHub",