@lobehub/lobehub 2.0.0-next.15 → 2.0.0-next.150

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

@@ -1,8 +1,9 @@
 ---
 title: LobeChat 身份验证服务配置
-description: 了解如何使用 Clerk 或 Next Auth 配置外部身份验证服务，以统一管理用户授权。支持的身份验证服务包括 Auth0、 Azure ID 等。
+description: 了解如何使用 Better Auth、Clerk 或 Next Auth 配置外部身份验证服务，以统一管理用户授权。支持的身份验证服务包括 Auth0、 Azure ID 等。
 tags:
   - 身份验证服务
+  - Better Auth
   - LobeChat
   - SSO
   - Clerk
@@ -10,7 +11,7 @@ tags:
 
 # 身份验证服务
 
-LobeChat 支持使用 Clerk 或者 Next Auth 配置外部身份验证服务，供企业 / 组织内部使用，统一管理用户授权。
+LobeChat 支持使用 Better Auth、Clerk 或者 Next Auth 配置外部身份验证服务，供企业 / 组织内部使用，统一管理用户授权。
 
 ## Clerk
 
@@ -20,6 +21,102 @@ LobeChat 与 Clerk 做了深度集成，能够为用户提供一个更加安全
 
 在 LobeChat 的环境变量中设置 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY`，即可开启和使用 Clerk。
 
+## Better Auth
+
+[Better Auth](https://www.better-auth.com) 是一个现代化、框架无关的身份验证库，旨在提供全面、安全、灵活的身份验证解决方案。它支持多种认证方式，包括邮箱 / 密码登录、魔法链接登录以及多种 OAuth/SSO 提供商。
+
+### 主要特性
+
+- **邮箱 / 密码认证**：内置支持传统的邮箱和密码登录，采用安全的密码哈希算法
+- **邮箱验证**：可选的邮箱验证流程，支持自定义邮件模板
+- **魔法链接登录**：通过邮件魔法链接实现无密码认证
+- **OAuth/SSO 支持**：集成 Google、GitHub、Microsoft、AWS Cognito 等主流身份提供商
+- **通用 OIDC/OAuth**：支持任何符合 OpenID Connect 或 OAuth 2.0 标准的提供商
+
+### 快速开始
+
+要在 LobeChat 中启用 Better Auth，请设置以下环境变量：
+
+| 环境变量                             | 类型 | 描述                                                                                                               |
+| -------------------------------- | -- | ---------------------------------------------------------------------------------------------------------------- |
+| `NEXT_PUBLIC_ENABLE_BETTER_AUTH` | 必选 | 设置为 `1` 以启用 Better Auth 服务                                                                                       |
+| `AUTH_SECRET`                    | 必选 | 用于加密会话令牌的密钥。使用以下命令生成：`openssl rand -base64 32`                                                                   |
+| `NEXT_PUBLIC_AUTH_URL`           | 必选 | 浏览器可访问的 Better Auth 基础 URL（例如 `http://localhost:3010`、`https://lobechat.com`）。Vercel 部署时可选（会自动从 `VERCEL_URL` 获取） |
+| `AUTH_SSO_PROVIDERS`             | 可选 | 启用的 SSO 提供商列表，以逗号分隔，例如 `google,github,microsoft`                                                                 |
+
+<Callout type={'error'}>
+  **重要提示**：Better Auth 目前仅适用于**全新部署**的场景。如果你已经使用 NextAuth 或 Clerk 并且数据库中存在用户数据，**请暂时不要切换到 Better Auth**，否则现有用户将无法登录。
+
+  我们正在开发从 NextAuth/Clerk 到 Better Auth 的用户数据迁移工具，迁移方案完成后会更新文档。相关进度请关注 [GitHub Issue #10456](https://github.com/lobehub/lobe-chat/issues/10456)。
+</Callout>
+
+<Callout type={'warning'}>
+  若使用官方 Docker 镜像构建 / 部署，默认是 **开启 NextAuth、关闭 Better Auth**
+  （`NEXT_PUBLIC_ENABLE_NEXT_AUTH=1`、`NEXT_PUBLIC_ENABLE_BETTER_AUTH=0`），以避免意外跳转到新版登录页。
+  如果要切换到 Better Auth，请同时显式设置构建参数和运行时环境变量：
+  `NEXT_PUBLIC_ENABLE_BETTER_AUTH=1`、`NEXT_PUBLIC_ENABLE_NEXT_AUTH=0`，并重新构建镜像。
+</Callout>
+
+### 支持的 SSO 提供商
+
+| 提供商                   | 值                       | 环境变量                                                                                                      |
+| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| Google                | `google`                | `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`                                                                    |
+| GitHub                | `github`                | `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`                                                                    |
+| Microsoft             | `microsoft`             | `AUTH_MICROSOFT_ID`, `AUTH_MICROSOFT_SECRET`                                                              |
+| AWS Cognito           | `cognito`               | `AUTH_COGNITO_ID`, `AUTH_COGNITO_SECRET`, `AUTH_COGNITO_ISSUER`                                           |
+| Auth0                 | `auth0`                 | `AUTH_AUTH0_ID`, `AUTH_AUTH0_SECRET`, `AUTH_AUTH0_ISSUER`                                                 |
+| Authelia              | `authelia`              | `AUTH_AUTHELIA_ID`, `AUTH_AUTHELIA_SECRET`, `AUTH_AUTHELIA_ISSUER`                                        |
+| Authentik             | `authentik`             | `AUTH_AUTHENTIK_ID`, `AUTH_AUTHENTIK_SECRET`, `AUTH_AUTHENTIK_ISSUER`                                     |
+| Casdoor               | `casdoor`               | `AUTH_CASDOOR_ID`, `AUTH_CASDOOR_SECRET`, `AUTH_CASDOOR_ISSUER`                                           |
+| Cloudflare Zero Trust | `cloudflare-zero-trust` | `AUTH_CLOUDFLARE_ZERO_TRUST_ID`, `AUTH_CLOUDFLARE_ZERO_TRUST_SECRET`, `AUTH_CLOUDFLARE_ZERO_TRUST_ISSUER` |
+| Keycloak              | `keycloak`              | `AUTH_KEYCLOAK_ID`, `AUTH_KEYCLOAK_SECRET`, `AUTH_KEYCLOAK_ISSUER`                                        |
+| Logto                 | `logto`                 | `AUTH_LOGTO_ID`, `AUTH_LOGTO_SECRET`, `AUTH_LOGTO_ISSUER`                                                 |
+| Okta                  | `okta`                  | `AUTH_OKTA_ID`, `AUTH_OKTA_SECRET`, `AUTH_OKTA_ISSUER`                                                    |
+| ZITADEL               | `zitadel`               | `AUTH_ZITADEL_ID`, `AUTH_ZITADEL_SECRET`, `AUTH_ZITADEL_ISSUER`                                           |
+| Generic OIDC          | `generic-oidc`          | `AUTH_GENERIC_OIDC_ID`, `AUTH_GENERIC_OIDC_SECRET`, `AUTH_GENERIC_OIDC_ISSUER`                            |
+| 飞书                    | `feishu`                | `AUTH_FEISHU_APP_ID`, `AUTH_FEISHU_APP_SECRET`                                                            |
+| 微信                    | `wechat`                | `AUTH_WECHAT_ID`, `AUTH_WECHAT_SECRET`                                                                    |
+
+### 回调 URL 格式
+
+配置 OAuth 提供商时，请使用以下回调 URL 格式：
+
+- **开发环境**：`http://localhost:3210/api/auth/callback/{provider}`
+- **生产环境**：`https://yourdomain.com/api/auth/callback/{provider}`
+
+### 邮件服务配置
+
+用于邮箱验证、密码重置和魔法链接发送。先选择邮件服务，再填对应变量：
+
+| 环境变量                                  | 类型 | 描述                                                                                        |
+| ------------------------------------- | -- | ----------------------------------------------------------------------------------------- |
+| `NEXT_PUBLIC_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` 时使用        |
+
+### 魔法链接（免密）登录
+
+启用 BetterAuth 魔法链接登录（依赖上方已配置好的邮件服务）：
+
+| 环境变量                            | 类型 | 描述                |
+| ------------------------------- | -- | ----------------- |
+| `NEXT_PUBLIC_ENABLE_MAGIC_LINK` | 可选 | 设置为 `1` 以启用魔法链接登录 |
+
+<Callout type={'tip'}>
+  详细的提供商配置可参考 [Next Auth 提供商文档](/zh/docs/self-hosting/advanced/auth/next-auth)（大部分配置兼容），或访问官方 [Better Auth 文档](https://www.better-auth.com/docs/introduction)。
+</Callout>
+
+<Callout type={'tip'}>
+  前往 [📘 环境变量](/zh/docs/self-hosting/environment-variables/auth#better-auth) 可查阅所有 Better Auth 相关变量详情。
+</Callout>
+
 ## Next Auth
 
 在使用 NextAuth 之前，请先在 LobeChat 的环境变量中设置以下变量：

package/docs/self-hosting/advanced/feature-flags.mdx

@@ -49,7 +49,6 @@ You can achieve various feature combinations using the above configuration synta
 | `token_counter`           | Reserved for token counter display.                                                                      | Enabled       |
 | `welcome_suggest`         | Displays welcome suggestions.                                                                            | Enabled       |
 | `changelog`               | Controls changelog modal/page display.                                                                   | Enabled       |
-| `clerk_sign_up`           | Enables the Clerk SignUp functionality.                                                                  | Enabled       |
 | `market`                  | Enables the assistant market functionality.                                                              | Enabled       |
 | `knowledge_base`          | Enables the knowledge base functionality.                                                                | Enabled       |
 | `rag_eval`                | Controls RAG evaluation feature (/repos/\[id]/evals).                                                    | Disabled      |

package/docs/self-hosting/advanced/feature-flags.zh-CN.mdx

@@ -46,7 +46,6 @@ tags:
 | `token_counter`           | 保留用于令牌计数器显示。                         | 开启  |
 | `welcome_suggest`         | 显示欢迎建议。                              | 开启  |
 | `changelog`               | 控制更新日志弹窗 / 页面的显示。                    | 开启  |
-| `clerk_sign_up`           | 启用 Clerk 注册功能。                       | 开启  |
 | `market`                  | 启用助手市场功能。                            | 开启  |
 | `knowledge_base`          | 启用知识库功能。                             | 开启  |
 | `rag_eval`                | 控制 RAG 评估功能 (/repos/\[id]/evals)。    | 关闭  |

package/docs/self-hosting/environment-variables/auth.mdx

@@ -1,11 +1,12 @@
 ---
 title: LobeChat Authentication Service Environment Variables
 description: >-
-  Explore the essential environment variables for configuring authentication services in LobeChat, including OAuth SSO, NextAuth settings, and provider-specific details.
+  Explore the essential environment variables for configuring authentication services in LobeChat, including Better Auth, OAuth SSO, NextAuth settings, and provider-specific details.
 
 
 tags:
   - Authentication Service
+  - Better Auth
   - OAuth SSO
   - Clerk
   - NextAuth
@@ -15,6 +16,191 @@ tags:
 
 LobeChat provides a complete authentication service capability when deployed. The following are the relevant environment variables. You can use these environment variables to easily define the identity verification services that need to be enabled in LobeChat.
 
+## Better Auth
+
+### General Settings
+
+#### `NEXT_PUBLIC_ENABLE_BETTER_AUTH`
+
+- Type: Required
+- Description: Set to `1` to enable Better Auth service. When enabled, Better Auth will be used for authentication instead of Next Auth or Clerk.
+- Default: `-`
+- Example: `1`
+
+#### `AUTH_SECRET`
+
+- Type: Required
+- Description: Key used to encrypt session tokens. Shared between Better Auth and Next Auth. You can generate the key using the command: `openssl rand -base64 32`.
+- Default: `-`
+- Example: `Tfhi2t2pelSMEA8eaV61KaqPNEndFFdMIxDaJnS1CUI=`
+
+#### `NEXT_PUBLIC_AUTH_URL`
+
+- Type: Optional
+- Description: The URL accessible from the browser for Better Auth callbacks. Only set this if the default generated URL is incorrect.
+- Default: `-`
+- Example: `https://example.com`
+
+#### `NEXT_PUBLIC_AUTH_EMAIL_VERIFICATION`
+
+- Type: Optional
+- Description: Set to `1` to require email verification before users can sign in. Users must verify their email address after registration.
+- Default: `0`
+- Example: `1`
+
+#### `AUTH_SSO_PROVIDERS`
+
+- Type: Optional
+- Description: Comma-separated list of enabled SSO providers. The order determines the display order of providers on the login page.
+- Default: `-`
+- Example: `google,github,microsoft,cognito`
+
+### Email Service (SMTP)
+
+These settings are required for email verification and password reset features.
+
+#### `SMTP_HOST`
+
+- Type: Required (for email features)
+- Description: SMTP server hostname.
+- Default: `-`
+- Example: `smtp.gmail.com`
+
+#### `SMTP_PORT`
+
+- Type: Required (for email features)
+- Description: SMTP server port. Usually `587` for TLS or `465` for SSL.
+- Default: `-`
+- Example: `587`
+
+#### `SMTP_SECURE`
+
+- Type: Optional
+- Description: Use secure connection. Set to `true` for port 465 (SSL), `false` for port 587 (TLS).
+- Default: `false`
+- Example: `false`
+
+#### `SMTP_USER`
+
+- Type: Required (for email features)
+- Description: SMTP authentication username, usually your email address.
+- Default: `-`
+- Example: `your-email@example.com`
+
+#### `SMTP_PASS`
+
+- Type: Required (for email features)
+- Description: SMTP authentication password. For Gmail, use an app-specific password.
+- Default: `-`
+- Example: `your-app-specific-password`
+
+### Google
+
+#### `AUTH_GOOGLE_ID`
+
+- Type: Required
+- Description: Client ID of the Google OAuth application. Get it from [Google Cloud Console](https://console.cloud.google.com/apis/credentials).
+- Default: `-`
+- Example: `123456789.apps.googleusercontent.com`
+
+#### `AUTH_GOOGLE_SECRET`
+
+- Type: Required
+- Description: Client Secret of the Google OAuth application.
+- Default: `-`
+- Example: `GOCSPX-xxxxxxxxxxxxxxxxxxxx`
+
+### GitHub
+
+#### `AUTH_GITHUB_ID`
+
+- Type: Required
+- Description: Client ID of the GitHub OAuth application. Get it from [GitHub Developer Settings](https://github.com/settings/developers).
+- Default: `-`
+- Example: `Ov23xxxxxxxxxxxxx`
+
+#### `AUTH_GITHUB_SECRET`
+
+- Type: Required
+- Description: Client Secret of the GitHub OAuth application.
+- Default: `-`
+- Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+### Microsoft
+
+#### `AUTH_MICROSOFT_ID`
+
+- Type: Required
+- Description: Client ID of the Microsoft Entra ID (Azure AD) application. Get it from [Azure Portal](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade).
+- Default: `-`
+- Example: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+
+#### `AUTH_MICROSOFT_SECRET`
+
+- Type: Required
+- Description: Client Secret of the Microsoft Entra ID application.
+- Default: `-`
+- Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+### AWS Cognito
+
+#### `AUTH_COGNITO_ID`
+
+- Type: Required
+- Description: Client ID of the AWS Cognito User Pool App Client. Get it from [AWS Cognito Console](https://console.aws.amazon.com/cognito).
+- Default: `-`
+- Example: `xxxxxxxxxxxxxxxxxxxxx`
+
+#### `AUTH_COGNITO_SECRET`
+
+- Type: Required
+- Description: Client Secret of the AWS Cognito App Client.
+- Default: `-`
+- Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+#### `AUTH_COGNITO_ISSUER`
+
+- Type: Required
+- Description: The Cognito User Pool issuer URL. Format: `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`
+- Default: `-`
+- Example: `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx`
+
+### Feishu
+
+#### `AUTH_FEISHU_APP_ID`
+
+- Type: Required
+- Description: App ID of the Feishu application. Get it from [Feishu Open Platform](https://open.feishu.cn/app).
+- Default: `-`
+- Example: `cli_xxxxxxxxxxxxxxxx`
+
+#### `AUTH_FEISHU_APP_SECRET`
+
+- Type: Required
+- Description: App Secret of the Feishu application.
+- Default: `-`
+- Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+### WeChat
+
+#### `AUTH_WECHAT_ID`
+
+- Type: Required
+- Description: App ID of the WeChat Open Platform application. Get it from [WeChat Open Platform](https://open.weixin.qq.com/).
+- Default: `-`
+- Example: `wxxxxxxxxxxxxxxxxxxx`
+
+#### `AUTH_WECHAT_SECRET`
+
+- Type: Required
+- Description: App Secret of the WeChat application.
+- Default: `-`
+- Example: `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+<Callout type={'info'}>
+  For other OIDC-based providers (Auth0, Authelia, Authentik, Casdoor, Cloudflare Zero Trust, Keycloak, Logto, Okta, ZITADEL, Generic OIDC), the environment variables follow the same pattern as Next Auth. See the [Next Auth section](#next-auth) below for details.
+</Callout>
+
 ## Next Auth
 
 ### General Settings

package/docs/self-hosting/environment-variables/auth.zh-CN.mdx

@@ -1,9 +1,10 @@
 ---
 title: LobeChat 身份验证服务设置
-description: 了解如何配置 LobeChat 的身份验证服务环境变量。
+description: 了解如何配置 LobeChat 的身份验证服务环境变量，包括 Better Auth、OAuth SSO、NextAuth 设置等。
 tags:
   - LobeChat
   - 身份验证服务
+  - Better Auth
   - 单点登录
   - Next Auth
   - Clerk
@@ -13,6 +14,191 @@ tags:
 
 LobeChat 在部署时提供了完善的身份验证服务能力，以下是相关的环境变量，你可以使用这些环境变量轻松定义需要在 LobeChat 中开启的身份验证服务。
 
+## Better Auth
+
+### 通用设置
+
+#### `NEXT_PUBLIC_ENABLE_BETTER_AUTH`
+
+- 类型：必选
+- 描述：设置为 `1` 以启用 Better Auth 服务。启用后，将使用 Better Auth 进行身份验证，而非 Next Auth 或 Clerk。
+- 默认值：`-`
+- 示例：`1`
+
+#### `AUTH_SECRET`
+
+- 类型：必选
+- 描述：用于加密会话令牌的密钥，Better Auth 和 Next Auth 共享。使用以下命令生成：`openssl rand -base64 32`
+- 默认值：`-`
+- 示例：`Tfhi2t2pelSMEA8eaV61KaqPNEndFFdMIxDaJnS1CUI=`
+
+#### `NEXT_PUBLIC_AUTH_URL`
+
+- 类型：可选
+- 描述：浏览器可访问的 Better Auth 回调 URL。仅在默认生成的 URL 不正确时设置。
+- 默认值：`-`
+- 示例：`https://example.com`
+
+#### `NEXT_PUBLIC_AUTH_EMAIL_VERIFICATION`
+
+- 类型：可选
+- 描述：设置为 `1` 以要求用户在登录前验证邮箱。用户注册后必须验证邮箱地址。
+- 默认值：`0`
+- 示例：`1`
+
+#### `AUTH_SSO_PROVIDERS`
+
+- 类型：可选
+- 描述：启用的 SSO 提供商列表，以逗号分隔。顺序决定了登录页面上提供商的显示顺序。
+- 默认值：`-`
+- 示例：`google,github,microsoft,cognito`
+
+### 邮件服务（SMTP）
+
+启用邮箱验证和密码重置功能需要配置以下设置。
+
+#### `SMTP_HOST`
+
+- 类型：必选（用于邮件功能）
+- 描述：SMTP 服务器主机名。
+- 默认值：`-`
+- 示例：`smtp.gmail.com`
+
+#### `SMTP_PORT`
+
+- 类型：必选（用于邮件功能）
+- 描述：SMTP 服务器端口。TLS 通常为 `587`，SSL 为 `465`。
+- 默认值：`-`
+- 示例：`587`
+
+#### `SMTP_SECURE`
+
+- 类型：可选
+- 描述：是否使用安全连接。端口 465（SSL）设置为 `true`，端口 587（TLS）设置为 `false`。
+- 默认值：`false`
+- 示例：`false`
+
+#### `SMTP_USER`
+
+- 类型：必选（用于邮件功能）
+- 描述：SMTP 认证用户名，通常是您的邮箱地址。
+- 默认值：`-`
+- 示例：`your-email@example.com`
+
+#### `SMTP_PASS`
+
+- 类型：必选（用于邮件功能）
+- 描述：SMTP 认证密码。Gmail 需使用应用专用密码。
+- 默认值：`-`
+- 示例：`your-app-specific-password`
+
+### Google
+
+#### `AUTH_GOOGLE_ID`
+
+- 类型：必选
+- 描述：Google OAuth 应用的 Client ID。在 [Google Cloud Console](https://console.cloud.google.com/apis/credentials) 获取。
+- 默认值：`-`
+- 示例：`123456789.apps.googleusercontent.com`
+
+#### `AUTH_GOOGLE_SECRET`
+
+- 类型：必选
+- 描述：Google OAuth 应用的 Client Secret。
+- 默认值：`-`
+- 示例：`GOCSPX-xxxxxxxxxxxxxxxxxxxx`
+
+### GitHub
+
+#### `AUTH_GITHUB_ID`
+
+- 类型：必选
+- 描述：GitHub OAuth 应用的 Client ID。在 [GitHub Developer Settings](https://github.com/settings/developers) 获取。
+- 默认值：`-`
+- 示例：`Ov23xxxxxxxxxxxxx`
+
+#### `AUTH_GITHUB_SECRET`
+
+- 类型：必选
+- 描述：GitHub OAuth 应用的 Client Secret。
+- 默认值：`-`
+- 示例：`xxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+### Microsoft
+
+#### `AUTH_MICROSOFT_ID`
+
+- 类型：必选
+- 描述：Microsoft Entra ID（Azure AD）应用的 Client ID。在 [Azure 门户](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) 获取。
+- 默认值：`-`
+- 示例：`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+
+#### `AUTH_MICROSOFT_SECRET`
+
+- 类型：必选
+- 描述：Microsoft Entra ID 应用的 Client Secret。
+- 默认值：`-`
+- 示例：`xxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+### AWS Cognito
+
+#### `AUTH_COGNITO_ID`
+
+- 类型：必选
+- 描述：AWS Cognito 用户池应用客户端的 Client ID。在 [AWS Cognito 控制台](https://console.aws.amazon.com/cognito) 获取。
+- 默认值：`-`
+- 示例：`xxxxxxxxxxxxxxxxxxxxx`
+
+#### `AUTH_COGNITO_SECRET`
+
+- 类型：必选
+- 描述：AWS Cognito 应用客户端的 Client Secret。
+- 默认值：`-`
+- 示例：`xxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+#### `AUTH_COGNITO_ISSUER`
+
+- 类型：必选
+- 描述：Cognito 用户池的颁发者 URL。格式：`https://cognito-idp.{region}.amazonaws.com/{userPoolId}`
+- 默认值：`-`
+- 示例：`https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx`
+
+### 飞书
+
+#### `AUTH_FEISHU_APP_ID`
+
+- 类型：必选
+- 描述：飞书应用的 App ID。在 [飞书开放平台](https://open.feishu.cn/app) 获取。
+- 默认值：`-`
+- 示例：`cli_xxxxxxxxxxxxxxxx`
+
+#### `AUTH_FEISHU_APP_SECRET`
+
+- 类型：必选
+- 描述：飞书应用的 App Secret。
+- 默认值：`-`
+- 示例：`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+### 微信
+
+#### `AUTH_WECHAT_ID`
+
+- 类型：必选
+- 描述：微信开放平台应用的 App ID。在 [微信开放平台](https://open.weixin.qq.com/) 获取。
+- 默认值：`-`
+- 示例：`wxxxxxxxxxxxxxxxxxxx`
+
+#### `AUTH_WECHAT_SECRET`
+
+- 类型：必选
+- 描述：微信应用的 App Secret。
+- 默认值：`-`
+- 示例：`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+<Callout type={'info'}>
+  其他基于 OIDC 的提供商（Auth0、Authelia、Authentik、Casdoor、Cloudflare Zero Trust、Keycloak、Logto、Okta、ZITADEL、Generic OIDC）的环境变量配置与 Next Auth 相同。详情请参阅下方的 [Next Auth 章节](#next-auth)。
+</Callout>
+
 ## Next Auth
 
 ### 通用设置

package/docs/self-hosting/environment-variables/basic.mdx

@@ -127,16 +127,62 @@ For specific content, please refer to the [Feature Flags](/docs/self-hosting/adv
 ### `SSRF_ALLOW_PRIVATE_IP_ADDRESS`
 
 - Type: Optional
-- Description: Allow to connect private IP address. In a trusted environment, it can be set to true to turn off SSRF protection.
+- Description: Controls whether to allow connections to private IP addresses. Set to `1` to disable SSRF protection and allow all private IP addresses. In a trusted environment (e.g., internal network), this can be enabled to allow access to internal resources.
 - Default: `0`
 - Example: `1` or `0`
 
+<Callout type="warning">
+  **Security Notice**: Enabling this option will disable SSRF protection and allow connections to private
+  IP addresses (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.). Only enable this in
+  trusted environments where you need to access internal network resources.
+</Callout>
+
+**Use Cases**:
+
+LobeChat performs SSRF security checks in the following scenarios:
+
+1. **Image/Video URL to Base64 Conversion**: When processing media messages (e.g., vision models, multimodal models), LobeChat converts image and video URLs to base64 format. This check prevents malicious users from accessing internal network resources.
+
+   Examples:
+
+   - Image: A user sends an image message with URL `http://192.168.1.100/admin/secrets.png`
+   - Video: A user sends a video message with URL `http://10.0.0.50/internal/meeting.mp4`
+
+   Without SSRF protection, these requests could expose internal network resources.
+
+2. **Web Crawler**: When using web crawling features to fetch external content.
+
+3. **Proxy Requests**: When proxying external API requests.
+
+**Configuration Examples**:
+
+```bash
+# Scenario 1: Public deployment (recommended)
+# Block all private IP addresses for security
+SSRF_ALLOW_PRIVATE_IP_ADDRESS=0
+
+# Scenario 2: Internal deployment
+# Allow all private IP addresses to access internal image servers
+SSRF_ALLOW_PRIVATE_IP_ADDRESS=1
+
+# Scenario 3: Hybrid deployment (most common)
+# Block private IPs by default, but allow specific trusted internal servers
+SSRF_ALLOW_PRIVATE_IP_ADDRESS=0
+SSRF_ALLOW_IP_ADDRESS_LIST=192.168.1.100,10.0.0.50
+```
+
 ### `SSRF_ALLOW_IP_ADDRESS_LIST`
 
 - Type: Optional
-- Description: Allow private IP address list, multiple IP addresses are separated by commas. Only when `SSRF_ALLOW_PRIVATE_IP_ADDRESS` is `0`, it takes effect.
+- Description: Whitelist of allowed IP addresses, separated by commas. Only takes effect when `SSRF_ALLOW_PRIVATE_IP_ADDRESS` is `0`. Use this to allow specific internal IP addresses while keeping SSRF protection enabled for other private IPs.
 - Default: -
-- Example: `198.18.1.62,224.0.0.3`
+- Example: `192.168.1.100,10.0.0.50,172.16.0.10`
+
+**Common Use Cases**:
+
+- Allow access to internal image storage server: `192.168.1.100`
+- Allow access to internal API gateway: `10.0.0.50`
+- Allow access to internal documentation server: `172.16.0.10`
 
 ### `ENABLE_AUTH_PROTECTION`
 

package/docs/self-hosting/environment-variables/basic.zh-CN.mdx

@@ -123,16 +123,61 @@ LobeChat 在部署时提供了一些额外的配置项，你可以使用环境
 ### `SSRF_ALLOW_PRIVATE_IP_ADDRESS`
 
 - 类型：可选
-- 描述：是否允许连接私有 IP 地址。在可信环境中可以设置为 true 来关闭 SSRF 防护。
+- 描述：控制是否允许连接私有 IP 地址。设置为 `1` 时将关闭 SSRF 防护并允许所有私有 IP 地址。在可信环境（如内网部署）中，可以启用此选项以访问内部资源。
 - 默认值：`0`
-- 示例：`1` or `0`
+- 示例：`1` 或 `0`
+
+<Callout type="warning">
+  **安全提示**：启用此选项将关闭 SSRF 防护，允许连接私有 IP 地址段（127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16
+  等）。仅在需要访问内网资源的可信环境中启用。
+</Callout>
+
+**应用场景**：
+
+LobeChat 会在以下场景执行 SSRF 安全检查：
+
+1. **图片 / 视频 URL 转 Base64**：在处理媒体消息时（例如视觉模型、多模态模型），LobeChat 会将图片和视频 URL 转换为 base64 格式。此检查可防止恶意用户通过媒体 URL 访问内网资源。
+
+   举例：
+
+   - 图片：用户发送图片消息，URL 为 `http://192.168.1.100/admin/secrets.png`
+   - 视频：用户发送视频消息，URL 为 `http://10.0.0.50/internal/meeting.mp4`
+
+   若无 SSRF 防护，这些请求可能导致内网资源泄露。
+
+2. **网页爬取**：使用网页爬取功能获取外部内容时。
+
+3. **代理请求**：代理外部 API 请求时。
+
+**配置示例**：
+
+```bash
+# 场景 1：公网部署（推荐）
+# 阻止所有私有 IP 访问，保证安全
+SSRF_ALLOW_PRIVATE_IP_ADDRESS=0
+
+# 场景 2：内网部署
+# 允许所有私有 IP，可访问内网图片服务器等资源
+SSRF_ALLOW_PRIVATE_IP_ADDRESS=1
+
+# 场景 3：混合部署（最常见）
+# 默认阻止私有 IP，但允许特定可信的内网服务器
+SSRF_ALLOW_PRIVATE_IP_ADDRESS=0
+SSRF_ALLOW_IP_ADDRESS_LIST=192.168.1.100,10.0.0.50
+```
 
 ### `SSRF_ALLOW_IP_ADDRESS_LIST`
 
 - 类型：可选
-- 说明：允许的私有 IP 地址列表，多个 IP 地址用逗号分隔。仅在 `SSRF_ALLOW_PRIVATE_IP_ADDRESS` 为 `0` 时生效。
+- 描述：允许访问的 IP 地址白名单，多个 IP 地址用逗号分隔。仅在 `SSRF_ALLOW_PRIVATE_IP_ADDRESS` 为 `0` 时生效。使用此选项可以在保持 SSRF 防护的同时，允许访问特定的内网 IP 地址。
 - 默认值：-
-- 示例：`198.18.1.62,224.0.0.3`
+- 示例：`192.168.1.100,10.0.0.50,172.16.0.10`
+
+**常见使用场景**：
+
+- 允许访问内网图片存储服务器：`192.168.1.100`
+- 允许访问内网 API 网关：`10.0.0.50`
+- 允许访问内网文档服务器：`172.16.0.10`
 
 ### `ENABLE_AUTH_PROTECTION`