@lobehub/lobehub 2.0.0-next.364 → 2.0.0-next.367

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

@@ -0,0 +1,200 @@
+---
+title: 认证迁移原理 - 技术深入解析
+description: >-
+  LobeChat 认证迁移的技术原理解析，包括数据库 Schema、迁移原理和问题排查指南。
+tags:
+  - 认证
+  - 迁移
+  - 数据库
+  - 问题排查
+---
+
+# 认证迁移原理
+
+本文档解释 LobeChat 认证迁移的技术原理，适合有数据库和开发经验的用户，帮助理解迁移的底层逻辑。
+
+<Callout type={'info'}>
+  如需分步迁移指南，请参阅 [NextAuth 迁移](/docs/self-hosting/advanced/auth/nextauth-to-betterauth) 或 [Clerk 迁移](/docs/self-hosting/advanced/auth/clerk-to-betterauth)。
+</Callout>
+
+## 核心数据库 Schema
+
+理解数据库 Schema 是排查迁移问题的关键。
+
+### Users 表
+
+`users` 表是**认证框架无关**的通用用户表，适用于任何认证系统。每条记录代表一个唯一的用户身份及其关联的个人信息。
+
+关键字段：
+
+| 字段                                | 说明         |
+| --------------------------------- | ---------- |
+| `id`                              | 用户唯一标识（主键） |
+| `email`                           | 用户邮箱地址（唯一） |
+| `avatar`, `firstName`, `lastName` | 个人资料信息     |
+
+### Accounts 表
+
+`accounts` 表存储认证提供商连接。不同的 SSO 提供商和邮箱密码认证都被视为独立的「账号」，关联到同一个用户。
+
+账号示例：
+
+- Google SSO 登录
+- GitHub SSO 登录
+- 邮箱密码凭证
+- Auth0（即使通过 Auth0 使用 Google 登录，也与直接使用 Google SSO 是不同的账号）
+
+**关系**：一个用户可以有多个账号（1:N 关系）。
+
+```
+┌─────────────────┐         ┌─────────────────┐
+│     users       │         │    accounts     │
+├─────────────────┤         ├─────────────────┤
+│ id (PK)         │◄───────┤│ user_id (FK)    │
+│ email (unique)  │         │ provider        │
+│ avatar          │         │ provider_id     │
+│ ...             │         │ ...             │
+└─────────────────┘         └─────────────────┘
+                                    │
+                            ┌───────┴───────┐
+                            │               │
+                    ┌───────▼──┐     ┌──────▼───┐
+                    │ Google   │     │ GitHub   │
+                    │ Account  │     │ Account  │
+                    └──────────┘     └──────────┘
+```
+
+## 迁移原理
+
+<Callout type={'warning'}>
+  迁移不会保留登录会话。用户在迁移后必须重新登录。
+</Callout>
+
+### 简单迁移
+
+简单迁移**只**迁移 `users` 表，忽略 `accounts` 表。
+
+**工作原理：**
+
+1. 迁移后用户使用邮箱密码或 SSO 登录
+2. Better Auth 检查该邮箱是否存在于 `users` 表中
+3. 如果找到，用户将关联到其现有数据
+4. 在 `accounts` 表中创建新的账号记录
+
+**为什么有效：**
+
+当你重置密码或使用 SSO 登录时，如果提供商返回的邮箱与 `users` 表中的现有邮箱匹配，系统会将你关联到该现有用户。
+
+**局限性：**
+
+由于没有迁移 `accounts` 表，系统不知道之前关联的账号信息。
+
+**示例场景：**
+
+- 迁移前：用户将 Google（`a@gmail.com`）和 Microsoft（`b@outlook.com`）关联到同一个用户
+- `users` 表存储主邮箱：`a@gmail.com`
+- 简单迁移后：
+  - 使用 `a@gmail.com` 登录 → ✅ 关联到现有用户
+  - 使用 `b@outlook.com` 登录 → ❌ 创建**新用户**（没有账号记录将 `b@outlook.com` 关联到原用户）
+
+### 完整迁移
+
+完整迁移将账号数据从之前的认证系统迁移到 Better Auth 的 `accounts` 表。
+
+**迁移的数据：**
+
+- NextAuth：`nextauth_accounts` 表 → Better Auth `accounts` 表
+- Clerk：Clerk API 中的 externalAccounts → Better Auth `accounts` 表
+
+**结果：**
+
+所有之前关联的账号继续有效。使用 `b@outlook.com` 登录将正确关联到现有用户。
+
+## 问题排查
+
+### 问题：登录创建了新用户而不是关联到现有数据
+
+这通常发生在简单迁移后使用副邮箱登录时。
+
+**诊断步骤：**
+
+1. **找到你的原始用户记录**
+
+   通过主邮箱查询 `users` 表：
+
+   ```sql
+   SELECT id, email FROM users WHERE email = 'your-primary-email@example.com';
+   ```
+
+   记下 `id` 值。
+
+2. **检查关联到该用户的账号**
+
+   使用用户 ID 查询 `accounts` 表：
+
+   ```sql
+   SELECT * FROM accounts WHERE user_id = 'your-user-id';
+   ```
+
+3. **找到错误创建的账号**
+
+   如果你使用副邮箱登录并创建了新用户，找到该账号：
+
+   ```sql
+   SELECT * FROM accounts WHERE provider_account_id = 'secondary-email@example.com';
+   -- 或者对于 SSO 提供商，按提供商的用户 ID 搜索
+   ```
+
+**修复方法：**
+
+1. 删除错误创建的账号记录：
+
+   ```sql
+   DELETE FROM accounts WHERE id = 'incorrect-account-id';
+   ```
+
+2. 如果创建了新用户，可能还需要删除它：
+
+   ```sql
+   DELETE FROM users WHERE id = 'new-user-id';
+   ```
+
+3. 使用你的**主邮箱**（存储在 `users` 表中的邮箱）登录
+
+4. 登录后，进入 **设置 → 个人资料 → 关联账号** 重新关联你的副账号
+
+![个人资料页面 - 关联账号](https://hub-apac-1.lobeobjects.space/docs/d9b41a1607d49319fd670e88529199cf.png)
+
+### 问题：迁移后 SSO 登录不工作
+
+**检查：**
+
+1. 确保 SSO 提供商已在 `AUTH_SSO_PROVIDERS` 中配置
+2. 验证提供商凭证（`AUTH_<PROVIDER>_ID`、`AUTH_<PROVIDER>_SECRET`）
+3. 对于完整迁移，验证账号记录是否正确创建：
+
+   ```sql
+   SELECT * FROM accounts WHERE provider = 'google';  -- 或你的提供商
+   ```
+
+### 问题：找不到原始用户数据
+
+**检查：**
+
+1. 验证你使用的邮箱与 `users` 表中的邮箱匹配
+2. 检查你最初是否使用了不同的邮箱或 SSO 提供商
+3. 直接查询数据库查找符合条件的用户：
+
+   ```sql
+   SELECT * FROM users WHERE email LIKE '%your-domain.com';
+   ```
+
+## 相关阅读
+
+<Cards>
+  <Card href={'/docs/self-hosting/advanced/auth/nextauth-to-betterauth'} title={'NextAuth 迁移指南'} />
+
+  <Card href={'/docs/self-hosting/advanced/auth/clerk-to-betterauth'} title={'Clerk 迁移指南'} />
+
+  <Card href={'/docs/self-hosting/advanced/auth'} title={'认证服务配置'} />
+</Cards>

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

@@ -54,21 +54,23 @@ This guide helps you migrate your existing NextAuth-based LobeChat deployment to
 
 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 |
+| 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 |
+| `AUTH_MICROSOFT_ENTRA_ID_TENANT_ID` | -                       | ❌ No longer needed  |
+| `AUTH_MICROSOFT_ENTRA_ID_BASE_URL`  | -                       | ❌ No longer needed  |
 
 <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_`.
@@ -82,7 +84,7 @@ Better Auth supports additional features with these new environment variables:
 | ------------------------- | ----------------------------------------- |
 | `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`)      |
+| `AUTH_ENABLE_MAGIC_LINK`  | Enable magic link login (set to `1`)      |
 | `EMAIL_SERVICE_PROVIDER`  | Email provider (`nodemailer` or `resend`) |
 
 ## Simple Migration
@@ -96,10 +98,10 @@ For small self-hosted deployments, the simplest approach is to let users re-logi
 
   **Example scenario**: If your previous account had two SSO accounts linked:
 
-  - Primary email (Google): `mail1@google.com`
-  - Secondary email (Microsoft): `mail2@outlook.com`
+  - Primary email (Google): `a@google.com`
+  - Secondary email (Microsoft): `b@outlook.com`
 
-  After migrating, logging in with `mail2@outlook.com` will create a **new user** instead of linking to your existing account.
+  After migrating, logging in with `b@outlook.com` will create a **new user** instead of linking to your existing account.
 </Callout>
 
 ### Steps
@@ -294,6 +296,16 @@ After migration is complete, follow [Simple Migration - Step 1](#steps) to confi
 
 ## Troubleshooting
 
+### Clear browser data before accessing
+
+After migration, if you encounter login issues, try clearing your browser's site data first:
+
+1. Open browser DevTools (F12 or right-click → Inspect)
+2. Go to Application tab → Storage → Clear site data
+3. Refresh the page and try again
+
+![Clear Browser Site Data](https://hub-apac-1.lobeobjects.space/docs/733c50ee2302e5daa3d99dc0739238c8.png)
+
 ### Users can't log in after migration
 
 - Check that `AUTH_SECRET` is set correctly
@@ -315,9 +327,37 @@ After migration is complete, follow [Simple Migration - Step 1](#steps) to confi
 
 This error occurs because the database schema is outdated. Run `pnpm db:migrate` to update the database structure before running the migration script.
 
+### email\_not\_found error
+
+If you see a redirect to `signin?callbackUrl=...&error=email_not_found`, it means LobeChat cannot get the user's email.
+
+<Callout type={'warning'}>
+  **Important**: Better Auth currently **requires user email** for authentication. All SSO providers must be configured to return email information, otherwise users cannot log in.
+</Callout>
+
+Common causes:
+
+**Cause 1: SSO connection not requesting email permission**
+
+When configuring SSO connections (e.g., GitHub in Auth0), make sure to enable **Email Address** permission in the Attributes section. LobeChat requires user email for authentication.
+
+**Cause 2: User email not configured in identity provider**
+
+For identity providers like Casdoor or Logto, users may not have an email configured.
+
+Solution:
+
+1. First configure the Webhook in LobeChat to sync user data from the identity provider:
+   - [Casdoor Webhook Configuration](/docs/self-hosting/advanced/auth/providers/casdoor)
+   - [Logto Webhook Configuration](/docs/self-hosting/advanced/auth/providers/logto)
+2. Then configure the user's email in the identity provider's admin console
+3. The user data will be synced to LobeChat via Webhook, and the user can then log in
+
 ## Related Reading
 
 <Cards>
+  <Card href={'/docs/self-hosting/advanced/auth/migration-internals'} title={'Migration Technical Deep Dive'} />
+
   <Card href={'/docs/self-hosting/advanced/auth'} title={'Authentication Service Configuration'} />
 
   <Card href={'/docs/self-hosting/environment-variables/auth'} title={'Auth Environment Variables'} />

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

@@ -80,7 +80,7 @@ Better Auth 支持更多功能，以下是新增的环境变量：
 | ------------------------- | -------------------------------- |
 | `AUTH_ALLOWED_EMAILS`     | 邮箱白名单（限制注册）                      |
 | `AUTH_EMAIL_VERIFICATION` | 启用邮箱验证（设为 `1`）                   |
-| `ENABLE_MAGIC_LINK`       | 启用魔法链接登录（设为 `1`）                 |
+| `AUTH_ENABLE_MAGIC_LINK`  | 启用魔法链接登录（设为 `1`）                 |
 | `EMAIL_SERVICE_PROVIDER`  | 邮件服务提供商（`nodemailer` 或 `resend`） |
 
 ## 简单迁移
@@ -94,10 +94,10 @@ Better Auth 支持更多功能，以下是新增的环境变量：
 
   **示例场景**：假设你之前的账户绑定了两个 SSO 账户：
 
-  - 主邮箱（Google）：`mail1@google.com`
-  - 副邮箱（Microsoft）：`mail2@outlook.com`
+  - 主邮箱（Google）：`a@google.com`
+  - 副邮箱（Microsoft）：`b@outlook.com`
 
-  迁移后使用 `mail2@outlook.com` 登录将会**创建新用户**，而非关联到原有账户。
+  迁移后使用 `b@outlook.com` 登录将会**创建新用户**，而非关联到原有账户。
 </Callout>
 
 ### 步骤
@@ -291,6 +291,16 @@ npx tsx scripts/nextauth-to-betterauth/verify.ts
 
 ## 常见问题
 
+### 访问前清除浏览器数据
+
+迁移完成后，如果遇到登录问题，请先尝试清除浏览器的站点数据：
+
+1. 打开浏览器开发者工具（F12 或右键 → 检查）
+2. 进入 Application 标签页 → Storage → Clear site data
+3. 刷新页面后重试
+
+![清除浏览器站点数据](https://hub-apac-1.lobeobjects.space/docs/733c50ee2302e5daa3d99dc0739238c8.png)
+
 ### 迁移后用户无法登录
 
 - 检查 `AUTH_SECRET` 是否正确设置
@@ -312,9 +322,37 @@ npx tsx scripts/nextauth-to-betterauth/verify.ts
 
 这是因为数据库 schema 未更新。请先运行 `pnpm db:migrate` 更新数据库结构，然后再执行迁移脚本。
 
+### email\_not\_found 错误
+
+如果登录时跳转到 `signin?callbackUrl=...&error=email_not_found`，说明 LobeChat 无法获取用户邮箱。
+
+<Callout type={'warning'}>
+  **重要提示**：Better Auth 目前**强依赖用户邮箱**进行身份认证。所有 SSO 提供商必须配置为返回邮箱信息，否则用户无法登录。
+</Callout>
+
+常见原因：
+
+**原因 1：SSO 连接未请求邮箱权限**
+
+配置 SSO 连接时（如 Auth0 中的 GitHub 连接），务必在 **Attributes** 部分勾选 **Email Address** 权限。LobeChat 需要用户邮箱进行身份认证。
+
+**原因 2：用户在身份提供商中未配置邮箱**
+
+对于 Casdoor、Logto 等身份提供商，用户可能没有配置邮箱。
+
+解决方案：
+
+1. 先在 LobeChat 中配置身份提供商的 Webhook 以同步用户数据：
+   - [Casdoor Webhook 配置](/zh/docs/self-hosting/advanced/auth/providers/casdoor)
+   - [Logto Webhook 配置](/zh/docs/self-hosting/advanced/auth/providers/logto)
+2. 然后在身份提供商的管理后台为用户配置邮箱
+3. 用户数据通过 Webhook 同步到 LobeChat 后即可正常登录
+
 ## 相关阅读
 
 <Cards>
+  <Card href={'/zh/docs/self-hosting/advanced/auth/migration-internals'} title={'迁移技术原理'} />
+
   <Card href={'/zh/docs/self-hosting/advanced/auth'} title={'身份验证服务配置'} />
 
   <Card href={'/zh/docs/self-hosting/environment-variables/auth'} title={'认证相关环境变量'} />

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

@@ -39,17 +39,34 @@ tags:
 
   When deploying LobeChat, you need to configure the following environment variables:
 
-  | Environment Variable             | Type     | Description                                                                   |
-  | -------------------------------- | -------- | ----------------------------------------------------------------------------- |
-  | `AUTH_SECRET`                    | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32` |
-  | `AUTH_SSO_PROVIDERS`             | Required | SSO provider for LobeChat. Use `casdoor` for Casdoor                          |
-  | `AUTH_CASDOOR_ID`                | Required | Client ID from Casdoor application                                            |
-  | `AUTH_CASDOOR_SECRET`            | Required | Client Secret from Casdoor application                                        |
-  | `AUTH_CASDOOR_ISSUER`            | Required | Casdoor server URL (e.g., `https://your-casdoor-domain`)                      |
+  | Environment Variable     | Type     | Description                                                                   |
+  | ------------------------ | -------- | ----------------------------------------------------------------------------- |
+  | `AUTH_SECRET`            | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32` |
+  | `AUTH_SSO_PROVIDERS`     | Required | SSO provider for LobeChat. Use `casdoor` for Casdoor                          |
+  | `AUTH_CASDOOR_ID`        | Required | Client ID from Casdoor application                                            |
+  | `AUTH_CASDOOR_SECRET`    | Required | Client Secret from Casdoor application                                        |
+  | `AUTH_CASDOOR_ISSUER`    | Required | Casdoor server URL (e.g., `https://your-casdoor-domain`)                      |
+  | `CASDOOR_WEBHOOK_SECRET` | Optional | Secret key for validating Webhook requests from Casdoor                       |
 
   <Callout type={'tip'}>
     Go to [📘 Environment Variables](/docs/self-hosting/environment-variables/auth#casdoor) for detailed information on these variables.
   </Callout>
+
+  ### Configure Webhook (Optional)
+
+  > Available in Casdoor `>=1.843.0`.
+
+  Configure Casdoor Webhook to sync user data updates to LobeChat.
+
+  1. Go to **Admin Tools** -> **Webhooks** and create a Webhook
+  2. Fill in the following fields:
+     - URL: `https://your-domain.com/api/webhooks/casdoor`
+     - Method: `POST`
+     - Content Type: `application/json`
+     - Headers: `casdoor-secret`: `your-webhook-secret`
+     - Events: `update-user`
+  3. Generate a secret at [generate-secret.vercel.app/10](https://generate-secret.vercel.app/10)
+  4. Set the secret in the `CASDOOR_WEBHOOK_SECRET` environment variable
 </Steps>
 
 <Callout type={'info'}>

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

@@ -37,17 +37,34 @@ tags:
 
   在部署 LobeChat 时，你需要配置以下环境变量：
 
-  | 环境变量                             | 类型 | 描述                                                |
-  | -------------------------------- | -- | ------------------------------------------------- |
-  | `AUTH_SECRET`                    | 必选 | 用于加密会话令牌的密钥。使用以下命令生成：`openssl rand -base64 32`    |
-  | `AUTH_SSO_PROVIDERS`             | 必选 | SSO 提供商。使用 Casdoor 请填写 `casdoor`                  |
-  | `AUTH_CASDOOR_ID`                | 必选 | Casdoor 应用的 Client ID                             |
-  | `AUTH_CASDOOR_SECRET`            | 必选 | Casdoor 应用的 Client Secret                         |
-  | `AUTH_CASDOOR_ISSUER`            | 必选 | Casdoor 服务器 URL（例如 `https://your-casdoor-domain`） |
+  | 环境变量                     | 类型 | 描述                                                |
+  | ------------------------ | -- | ------------------------------------------------- |
+  | `AUTH_SECRET`            | 必选 | 用于加密会话令牌的密钥。使用以下命令生成：`openssl rand -base64 32`    |
+  | `AUTH_SSO_PROVIDERS`     | 必选 | SSO 提供商。使用 Casdoor 请填写 `casdoor`                  |
+  | `AUTH_CASDOOR_ID`        | 必选 | Casdoor 应用的 Client ID                             |
+  | `AUTH_CASDOOR_SECRET`    | 必选 | Casdoor 应用的 Client Secret                         |
+  | `AUTH_CASDOOR_ISSUER`    | 必选 | Casdoor 服务器 URL（例如 `https://your-casdoor-domain`） |
+  | `CASDOOR_WEBHOOK_SECRET` | 可选 | 用于验证 Casdoor 发送的 Webhook 请求是否合法的密钥                |
 
   <Callout type={'tip'}>
     前往 [📘 环境变量](/zh/docs/self-hosting/environment-variables/auth#casdoor) 可查阅相关变量详情。
   </Callout>
+
+  ### 配置 Webhook（可选）
+
+  > 在 Casdoor `>=1.843.0` 上可用。
+
+  配置 Casdoor 的 Webhook 以便在用户信息更新时同步到 LobeChat。
+
+  1. 前往 `管理工具` -> `Webhooks`，创建一个 Webhook
+  2. 填写以下字段：
+     - 链接：`https://your-domain.com/api/webhooks/casdoor`
+     - 方法：`POST`
+     - 内容类型：`application/json`
+     - 协议头：`casdoor-secret`: `你的Webhook密钥`
+     - 事件：`update-user`
+  3. 密钥可前往 [generate-secret.vercel.app/10](https://generate-secret.vercel.app/10) 生成
+  4. 将密钥填写到环境变量 `CASDOOR_WEBHOOK_SECRET`
 </Steps>
 
 <Callout type={'info'}>部署成功后，用户将可以通过 Casdoor 身份认证并使用 LobeChat。</Callout>

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

@@ -41,17 +41,30 @@ tags:
 
   When deploying LobeChat, you need to configure the following environment variables:
 
-  | Environment Variable             | Type     | Description                                                                   |
-  | -------------------------------- | -------- | ----------------------------------------------------------------------------- |
-  | `AUTH_SECRET`                    | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32` |
-  | `AUTH_SSO_PROVIDERS`             | Required | SSO provider for LobeChat. Use `logto` for Logto                              |
-  | `AUTH_LOGTO_ID`                  | Required | App ID from Logto application                                                 |
-  | `AUTH_LOGTO_SECRET`              | Required | App Secret from Logto application                                             |
-  | `AUTH_LOGTO_ISSUER`              | Required | Logto issuer URL (e.g., `https://your-tenant.logto.app/oidc`)                 |
+  | Environment Variable        | Type     | Description                                                                   |
+  | --------------------------- | -------- | ----------------------------------------------------------------------------- |
+  | `AUTH_SECRET`               | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32` |
+  | `AUTH_SSO_PROVIDERS`        | Required | SSO provider for LobeChat. Use `logto` for Logto                              |
+  | `AUTH_LOGTO_ID`             | Required | App ID from Logto application                                                 |
+  | `AUTH_LOGTO_SECRET`         | Required | App Secret from Logto application                                             |
+  | `AUTH_LOGTO_ISSUER`         | Required | Logto issuer URL (e.g., `https://your-tenant.logto.app/oidc`)                 |
+  | `LOGTO_WEBHOOK_SIGNING_KEY` | Optional | Secret key for validating Webhook requests from Logto                         |
 
   <Callout type={'tip'}>
     Go to [📘 Environment Variables](/docs/self-hosting/environment-variables/auth#logto) for detailed information on these variables.
   </Callout>
+
+  ### Configure Webhook (Optional)
+
+  Configure Logto Webhook to sync user data updates to LobeChat.
+
+  1. Go to **Webhooks** in Logto Console and create a Webhook
+  2. Fill in the following fields:
+     - Endpoint URL: `https://your-domain.com/api/webhooks/logto`
+     - Events:
+       - `User.Data.Updated`: Sync user profile updates
+       - `User.SuspensionStatus.Updated`: Sync user suspension status
+  3. After creation, copy the `Signing Key` and set it in the `LOGTO_WEBHOOK_SIGNING_KEY` environment variable
 </Steps>
 
 <Callout type={'info'}>

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

@@ -39,17 +39,30 @@ tags:
 
   在部署 LobeChat 时，你需要配置以下环境变量：
 
-  | 环境变量                             | 类型 | 描述                                                        |
-  | -------------------------------- | -- | --------------------------------------------------------- |
-  | `AUTH_SECRET`                    | 必选 | 用于加密会话令牌的密钥。使用以下命令生成：`openssl rand -base64 32`            |
-  | `AUTH_SSO_PROVIDERS`             | 必选 | SSO 提供商。使用 Logto 请填写 `logto`                              |
-  | `AUTH_LOGTO_ID`                  | 必选 | Logto 应用的 App ID                                          |
-  | `AUTH_LOGTO_SECRET`              | 必选 | Logto 应用的 App Secret                                      |
-  | `AUTH_LOGTO_ISSUER`              | 必选 | Logto Issuer URL（例如 `https://your-tenant.logto.app/oidc`） |
+  | 环境变量                        | 类型 | 描述                                                        |
+  | --------------------------- | -- | --------------------------------------------------------- |
+  | `AUTH_SECRET`               | 必选 | 用于加密会话令牌的密钥。使用以下命令生成：`openssl rand -base64 32`            |
+  | `AUTH_SSO_PROVIDERS`        | 必选 | SSO 提供商。使用 Logto 请填写 `logto`                              |
+  | `AUTH_LOGTO_ID`             | 必选 | Logto 应用的 App ID                                          |
+  | `AUTH_LOGTO_SECRET`         | 必选 | Logto 应用的 App Secret                                      |
+  | `AUTH_LOGTO_ISSUER`         | 必选 | Logto Issuer URL（例如 `https://your-tenant.logto.app/oidc`） |
+  | `LOGTO_WEBHOOK_SIGNING_KEY` | 可选 | 用于验证 Logto 发送的 Webhook 请求是否合法的密钥                          |
 
   <Callout type={'tip'}>
     前往 [📘 环境变量](/zh/docs/self-hosting/environment-variables/auth#logto) 可查阅相关变量详情。
   </Callout>
+
+  ### 配置 Webhook（可选）
+
+  配置 Logto 的 Webhook，以便在用户信息更新时 LobeChat 可以接收到通知并同步数据。
+
+  1. 前往 Logto 控制台的 `Webhooks`，创建一个 Webhook
+  2. 填写以下字段：
+     - 端点 URL：`https://your-domain.com/api/webhooks/logto`
+     - 事件：
+       - `User.Data.Updated`：同步用户资料信息的更新
+       - `User.SuspensionStatus.Updated`：同步用户暂停状态
+  3. 创建后，复制 `签名密钥` 填写到环境变量 `LOGTO_WEBHOOK_SIGNING_KEY`
 </Steps>
 
 <Callout type={'info'}>部署成功后，用户将可以通过 Logto 身份认证并使用 LobeChat。</Callout>

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

@@ -110,15 +110,15 @@ Used by email verification, password reset, and magic-link delivery. Two provide
 
 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`    |
-| `SMTP_FROM`              | Optional | Sender address (required for AWS SES), defaults to `SMTP_USER`    | `noreply@example.com`  |
+| 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`   |
+| `SMTP_FROM`              | Optional | Sender address (required for AWS SES), defaults to `SMTP_USER` | `noreply@example.com` |
 
 <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).
@@ -148,9 +148,9 @@ Send emails via SMTP protocol, suitable for users with existing email services.
 
 Enable magic-link login (depends on a working email provider above, off by default):
 
-| Environment Variable | Type     | Description                                                         |
-| -------------------- | -------- | ------------------------------------------------------------------- |
-| `ENABLE_MAGIC_LINK`  | Optional | Set to `1` to enable passwordless magic-link login (off by default) |
+| Environment Variable     | Type     | Description                                                         |
+| ------------------------ | -------- | ------------------------------------------------------------------- |
+| `AUTH_ENABLE_MAGIC_LINK` | Optional | Set to `1` to enable passwordless magic-link login (off by default) |
 
 <Callout type={'tip'}>
   Go to [Environment Variables](/docs/self-hosting/environment-variables/auth#better-auth) for detailed information on all Better Auth variables.

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

@@ -107,15 +107,15 @@ LobeChat 使用 [Better Auth](https://www.better-auth.com) 作为身份验证解
 
 使用 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`    |
-| `SMTP_FROM`              | 可选 | 发件人地址（AWS SES 必填），默认为 `SMTP_USER`             | `noreply@example.com`  |
+| 环境变量                     | 类型 | 描述                                             | 示例                    |
+| ------------------------ | -- | ---------------------------------------------- | --------------------- |
+| `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`   |
+| `SMTP_FROM`              | 可选 | 发件人地址（AWS SES 必填），默认为 `SMTP_USER`              | `noreply@example.com` |
 
 <Callout type={'warning'}>
   使用 Gmail 时，需使用应用专用密码而非账户密码。前往 [Google 应用专用密码](https://myaccount.google.com/apppasswords) 生成。
@@ -145,9 +145,9 @@ LobeChat 使用 [Better Auth](https://www.better-auth.com) 作为身份验证解
 
 启用魔法链接登录（依赖上方已配置好的邮件服务，默认关闭）：
 
-| 环境变量                | 类型 | 描述                      |
-| ------------------- | -- | ----------------------- |
-| `ENABLE_MAGIC_LINK` | 可选 | 设置为 `1` 以启用魔法链接登录（默认关闭） |
+| 环境变量                     | 类型 | 描述                      |
+| ------------------------ | -- | ----------------------- |
+| `AUTH_ENABLE_MAGIC_LINK` | 可选 | 设置为 `1` 以启用魔法链接登录（默认关闭） |
 
 <Callout type={'tip'}>
   前往 [环境变量](/zh/docs/self-hosting/environment-variables/auth#better-auth) 可查阅所有 Better Auth 相关变量详情。