@lobehub/lobehub 2.0.0-next.332 → 2.0.0-next.334

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

@@ -1,33 +1,24 @@
 ---
 title: LobeChat Authentication Service Configuration
 description: >-
-  Learn how to configure external authentication services using Better Auth, Clerk, or Next Auth for centralized user authorization management. Supported authentication services include Auth0, Azure ID, etc.
-
+  Learn how to configure Better Auth for centralized user authorization
+  management. Supported SSO providers include Google, GitHub, Microsoft, and
+  more.
 tags:
   - Authentication Service
   - Better Auth
-  - Next Auth
   - SSO
-  - Clerk
 ---
 
 # Authentication Service
 
-LobeChat supports the configuration of external authentication services using Better Auth, Clerk, or Next Auth for internal use within enterprises/organizations to centrally manage user authorization.
-
-## Clerk
-
-Clerk is a comprehensive identity verification solution that has recently gained popularity. It provides a simple yet powerful API and services to handle user authentication and session management. Clerk's design philosophy is to offer a concise and modern authentication solution that enables developers to easily integrate and use it.
-
-LobeChat has deeply integrated with Clerk to provide users with a more secure and convenient login and registration experience. It also relieves developers from the burden of managing authentication logic. Clerk's concise and modern design philosophy aligns perfectly with LobeChat's goals, making user management on the entire platform more efficient and reliable.
-
-By setting the environment variables `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` in LobeChat's environment, you can enable and use Clerk.
+LobeChat uses [Better Auth](https://www.better-auth.com) as its authentication solution, providing comprehensive, secure, and flexible identity verification for self-hosted deployments.
 
-## Better Auth
-
-[Better Auth](https://www.better-auth.com) is a modern, framework-agnostic authentication library designed to provide comprehensive, secure, and flexible authentication solutions. It supports various authentication methods including email/password, magic links, and multiple OAuth/SSO providers.
+<Callout type={'info'}>
+  Looking for legacy authentication methods? See [Legacy Authentication](/docs/self-hosting/advanced/auth/legacy) for NextAuth and Clerk documentation.
+</Callout>
 
-### Key Features
+## Key Features
 
 - **Email/Password Authentication**: Built-in support for traditional email and password login with secure password hashing
 - **Email Verification**: Optional email verification flow with customizable email templates
@@ -35,160 +26,116 @@ By setting the environment variables `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CL
 - **OAuth/SSO Support**: Integration with popular identity providers including Google, GitHub, Microsoft, AWS Cognito, and more
 - **Generic OIDC/OAuth**: Support for any OpenID Connect or OAuth 2.0 compliant provider
 
-### Getting Started
+## Getting Started
 
 To enable Better Auth in LobeChat, set the following environment variables:
 
-| Environment Variable             | Type     | Description                                                                   |
-| -------------------------------- | -------- | ----------------------------------------------------------------------------- |
-| `NEXT_PUBLIC_ENABLE_BETTER_AUTH` | Required | Set to `1` to enable Better Auth service                                      |
-| `AUTH_SECRET`                    | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32` |
-| `AUTH_SSO_PROVIDERS`             | Optional | Comma-separated list of enabled SSO providers, e.g., `google,github,microsoft`|
-
-<Callout type={'error'}>
-  **Important**: Better Auth is currently only suitable for **fresh deployments**. If you are already using NextAuth or Clerk and have existing user data in your database, **do not switch to Better Auth yet**, otherwise existing users will not be able to log in.
-
-  We are developing user data migration tools from NextAuth/Clerk to Better Auth. Documentation will be updated once the migration solution is complete. For progress updates, please follow [GitHub Issue #10456](https://github.com/lobehub/lobe-chat/issues/10456).
-</Callout>
-
-<Callout type={'warning'}>
-  If you build/deploy with the official Docker image, the defaults keep **NextAuth enabled** and **Better
-  Auth disabled** (`NEXT_PUBLIC_ENABLE_NEXT_AUTH=1`, `NEXT_PUBLIC_ENABLE_BETTER_AUTH=0`) to avoid unexpected
-  login redirects. To switch to Better Auth, set both build args and runtime envs explicitly:
-  `NEXT_PUBLIC_ENABLE_BETTER_AUTH=1` and `NEXT_PUBLIC_ENABLE_NEXT_AUTH=0`, then rebuild the image.
-</Callout>
-
-### Supported SSO Providers
-
-| Provider              | Value                   | Environment Variables                                                                                     |
-| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
-| 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                | `feishu`                | `AUTH_FEISHU_APP_ID`, `AUTH_FEISHU_APP_SECRET`                                                            |
-| WeChat                | `wechat`                | `AUTH_WECHAT_ID`, `AUTH_WECHAT_SECRET`                                                                    |
-
-### Callback URL Format
-
-When configuring OAuth providers, use the following callback URL format:
-
-- **Development**: `http://localhost:3210/api/auth/callback/{provider}`
-- **Production**: `https://yourdomain.com/api/auth/callback/{provider}`
-
-### 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_SECRET`        | Required | Key used to encrypt session tokens. Generate using: `openssl rand -base64 32`  |
+| `AUTH_SSO_PROVIDERS` | Optional | Comma-separated list of enabled SSO providers, e.g., `google,github,microsoft` |
+
+## Supported SSO Providers
+
+| Provider              | Value                   | Environment Variables                                                                                              |
+| --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Google                | `google`                | `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`                                                                             |
+| GitHub                | `github`                | `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`                                                                             |
+| Microsoft             | `microsoft`             | `AUTH_MICROSOFT_ID`, `AUTH_MICROSOFT_SECRET`                                                                       |
+| Apple                 | `apple`                 | `AUTH_APPLE_CLIENT_ID`, `AUTH_APPLE_CLIENT_SECRET`                                                                 |
+| AWS Cognito           | `cognito`               | `AUTH_COGNITO_ID`, `AUTH_COGNITO_SECRET`, `AUTH_COGNITO_DOMAIN`, `AUTH_COGNITO_REGION`, `AUTH_COGNITO_USERPOOL_ID` |
+| 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                | `feishu`                | `AUTH_FEISHU_APP_ID`, `AUTH_FEISHU_APP_SECRET`                                                                     |
+| WeChat                | `wechat`                | `AUTH_WECHAT_ID`, `AUTH_WECHAT_SECRET`                                                                             |
+
+Click on a provider below for detailed configuration guides:
 
-| Environment Variable                  | Type        | Description                                                                                                                                       |
-| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `NEXT_PUBLIC_AUTH_EMAIL_VERIFICATION` | Optional    | Set to `1` to require email verification before users can sign in                                                                                 |
-| `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` |
+<Cards>
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/github'} title={'GitHub'} />
 
-### Magic Link (Passwordless) Login
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/google'} title={'Google'} />
 
-Enable BetterAuth magic-link login (depends on a working email provider above):
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/microsoft'} title={'Microsoft'} />
 
-| Environment Variable            | Type     | Description                                        |
-| ------------------------------- | -------- | -------------------------------------------------- |
-| `NEXT_PUBLIC_ENABLE_MAGIC_LINK` | Optional | Set to `1` to enable passwordless magic-link login |
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/apple'} title={'Apple'} />
 
-<Callout type={'tip'}>
-  For detailed provider configuration, refer to the [Next Auth provider documentation](/docs/self-hosting/advanced/auth/next-auth) as most configurations are compatible, or visit the official [Better Auth documentation](https://www.better-auth.com/docs/introduction).
-</Callout>
-
-<Callout type={'tip'}>
-  Go to [📘 Environment Variables](/docs/self-hosting/environment-variables/auth#better-auth) for detailed information on all Better Auth variables.
-</Callout>
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/cognito'} title={'AWS Cognito'} />
 
-## Next Auth
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/auth0'} title={'Auth0'} />
 
-Before using NextAuth, please set the following variables in LobeChat's environment variables:
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/authelia'} title={'Authelia'} />
 
-| Environment Variable             | Type     | Description                                                                                                                                                                                                                                |
-| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `NEXT_PUBLIC_ENABLE_NEXT_AUTH`   | Required | This is used to enable the NextAuth service. Set it to `1` to enable it; changing this setting requires recompiling the application. Users deploying with the `lobehub/lobe-chat-database` image have this configuration added by default. |
-| `AUTH_SECRET`                    | Required | The key used to encrypt Auth.js session tokens. You can use the following command: `openssl rand -base64 32`, or visit `https://generate-secret.vercel.app/32` to generate the key.                                                        |
-| `AUTH_URL`                       | Required | This URL specifies the callback address for Auth.js when performing OAuth verification. Set this only if the default generated redirect address is incorrect. `https://example.com/api/auth`                                               |
-| `NEXT_AUTH_SSO_PROVIDERS`        | Optional | This environment variable is used to enable multiple identity verification sources simultaneously, separated by commas, for example, `auth0,microsoft-entra-id,authentik`.                                                                 |
-| `NEXT_AUTH_SSO_SESSION_STRATEGY` | Optional | The session strategy for Auth.js. Options are `jwt` or `database`. Default is `jwt`.                                                                                                                                                       |
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/authentik'} title={'Authentik'} />
 
-Currently supported identity verification services include:
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/casdoor'} title={'Casdoor'} />
 
-<Cards>
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/auth0'} title={'Auth0'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/microsoft-entra-id'} title={'Microsoft Entra ID'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/keycloak'} title={'Keycloak'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/authentik'} title={'Authentik'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/logto'} title={'Logto'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/github'} title={'Github'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/okta'} title={'Okta'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/zitadel'} title={'ZITADEL'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/zitadel'} title={'ZITADEL'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/generic-oidc'} title={'Generic OIDC'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/authelia'} title={'Authelia'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/feishu'} title={'Feishu'} />
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/logto'} title={'Logto'} />
+  <Card href={'/docs/self-hosting/advanced/auth/better-auth/wechat'} title={'WeChat'} />
+</Cards>
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/keycloak'} title={'Keycloak'} />
+## Callback URL Format
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/google'} title={'Google'} />
+When configuring OAuth providers, use the following callback URL format:
 
-  <Card href={'/docs/self-hosting/advanced/auth/next-auth/okta'} title={'Okta'} />
-</Cards>
+- **Development**: `http://localhost:3210/api/auth/callback/{provider}`
+- **Production**: `https://yourdomain.com/api/auth/callback/{provider}`
 
-Click on the links to view the corresponding platform's configuration documentation.
+## Email Service Configuration
 
-## Advanced Configuration
+Used by email verification, password reset, and magic-link delivery. Choose a provider, then fill the matching variables:
 
-To simultaneously enable multiple identity verification sources, please set the `NEXT_AUTH_SSO_PROVIDERS` environment variable, separating them with commas, for example, `auth0,microsoft-entra-id,authentik`.
+| 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` |
 
-The order corresponds to the display order of the SSO providers.
+## Magic Link (Passwordless) Login
 
-| SSO Provider          | Value                   | Additional Features |
-| --------------------- | ----------------------- | ------------------- |
-| Auth0                 | `auth0`                 |                     |
-| Authenlia             | `authenlia`             |                     |
-| Authentik             | `authentik`             |                     |
-| Casdoor               | `casdoor`               | `Webhook`           |
-| Cloudflare Zero Trust | `cloudflare-zero-trust` |                     |
-| Github                | `github`                |                     |
-| Logto                 | `logto`                 | `Webhook`           |
-| Microsoft Entra ID    | `microsoft-entra-id`    |                     |
-| ZITADEL               | `zitadel`               |                     |
-| Keycloak              | `keycloak`              |                     |
-| Google                | `google`                |                     |
-| Okta                  | `okta`                  |                     |
+Enable magic-link login (depends on a working email provider above, off by default):
 
-## Additional Features
+| Environment Variable | Type     | Description                                                         |
+| -------------------- | -------- | ------------------------------------------------------------------- |
+| `ENABLE_MAGIC_LINK`  | Optional | Set to `1` to enable passwordless magic-link login (off by default) |
 
-### Webhook Support
+<Callout type={'tip'}>
+  Go to [Environment Variables](/docs/self-hosting/environment-variables/auth#better-auth) for detailed information on all Better Auth variables.
+</Callout>
 
-Allow LobeChat to receive notifications when user information is updated in the identity provider. Supported providers include Casdoor and Logto. Please refer to the specific provider documentation for configuration details.
+## FAQ
 
-### Database Session
+### What SSO providers does Better Auth support?
 
-Allow the session store in database, see also the [Auth.js Session Documentation](https://authjs.dev/concepts/session-strategies#database-session).
+Better Auth supports built-in providers (Google, GitHub, Microsoft, Apple, AWS Cognito) and Generic OIDC providers (Auth0, Authelia, Authentik, Casdoor, Cloudflare Zero Trust, Keycloak, Logto, Okta, ZITADEL, Generic OIDC, Feishu, WeChat).
 
-## Other SSO Providers
+### How do I enable multiple SSO providers?
 
-Please refer to the [Auth.js](https://authjs.dev/getting-started/authentication/oauth) documentation and feel free to submit a Pull Request.
+Set the `AUTH_SSO_PROVIDERS` environment variable with a comma-separated list, e.g., `google,github,microsoft`. The order determines the display order on the login page.

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

@@ -1,31 +1,21 @@
 ---
 title: LobeChat 身份验证服务配置
-description: 了解如何使用 Better Auth、Clerk 或 Next Auth 配置外部身份验证服务，以统一管理用户授权。支持的身份验证服务包括 Auth0、 Azure ID 等。
+description: 了解如何配置 Better Auth 以统一管理用户授权。支持的 SSO 提供商包括 Google、GitHub、Microsoft 等。
 tags:
   - 身份验证服务
   - Better Auth
-  - LobeChat
   - SSO
-  - Clerk
 ---
 
 # 身份验证服务
 
-LobeChat 支持使用 Better Auth、Clerk 或者 Next Auth 配置外部身份验证服务，供企业 / 组织内部使用，统一管理用户授权。
+LobeChat 使用 [Better Auth](https://www.better-auth.com) 作为身份验证解决方案，为自托管部署提供全面、安全、灵活的身份验证服务。
 
-## Clerk
-
-Clerk 是一个近期流行起来的全面的身份验证解决方案，它提供了简单而强大的 API 和服务来处理用户认证和会话管理。Clerk 的设计哲学是提供一套简洁、现代的认证解决方案，使得开发者可以轻松集成和使用。
-
-LobeChat 与 Clerk 做了深度集成，能够为用户提供一个更加安全、便捷的登录和注册体验，同时也为开发者减轻了管理身份验证逻辑的负担。Clerk 的简洁和现代的设计理念与 LobeChat 的目标非常契合，使得整个平台的用户管理更加高效和可靠。
-
-在 LobeChat 的环境变量中设置 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY`，即可开启和使用 Clerk。
-
-## Better Auth
-
-[Better Auth](https://www.better-auth.com) 是一个现代化、框架无关的身份验证库，旨在提供全面、安全、灵活的身份验证解决方案。它支持多种认证方式，包括邮箱 / 密码登录、魔法链接登录以及多种 OAuth/SSO 提供商。
+<Callout type={'info'}>
+  需要使用旧版身份验证方案？请参阅 [旧版身份验证](/zh/docs/self-hosting/advanced/auth/legacy) 了解 NextAuth 和 Clerk 的文档。
+</Callout>
 
-### 主要特性
+## 主要特性
 
 - **邮箱 / 密码认证**：内置支持传统的邮箱和密码登录，采用安全的密码哈希算法
 - **邮箱验证**：可选的邮箱验证流程，支持自定义邮件模板
@@ -33,157 +23,116 @@ LobeChat 与 Clerk 做了深度集成，能够为用户提供一个更加安全
 - **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`              |
-| `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}`
-
-### 邮件服务配置
+| 环境变量                 | 类型 | 描述                                               |
+| -------------------- | -- | ------------------------------------------------ |
+| `AUTH_SECRET`        | 必选 | 用于加密会话令牌的密钥。使用以下命令生成：`openssl rand -base64 32`   |
+| `AUTH_SSO_PROVIDERS` | 可选 | 启用的 SSO 提供商列表，以逗号分隔，例如 `google,github,microsoft` |
+
+## 支持的 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`                                                                       |
+| Apple                 | `apple`                 | `AUTH_APPLE_CLIENT_ID`, `AUTH_APPLE_CLIENT_SECRET`                                                                 |
+| AWS Cognito           | `cognito`               | `AUTH_COGNITO_ID`, `AUTH_COGNITO_SECRET`, `AUTH_COGNITO_DOMAIN`, `AUTH_COGNITO_REGION`, `AUTH_COGNITO_USERPOOL_ID` |
+| 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`                                                                             |
+
+点击下方提供商查看详细配置指南：
 
-用于邮箱验证、密码重置和魔法链接发送。先选择邮件服务，再填对应变量：
+<Cards>
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/github'} title={'GitHub'} />
 
-| 环境变量                                  | 类型 | 描述                                                                                        |
-| ------------------------------------- | -- | ----------------------------------------------------------------------------------------- |
-| `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` 时使用        |
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/google'} title={'Google'} />
 
-### 魔法链接（免密）登录
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/microsoft'} title={'Microsoft'} />
 
-启用 BetterAuth 魔法链接登录（依赖上方已配置好的邮件服务）：
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/apple'} title={'Apple'} />
 
-| 环境变量                            | 类型 | 描述                |
-| ------------------------------- | -- | ----------------- |
-| `NEXT_PUBLIC_ENABLE_MAGIC_LINK` | 可选 | 设置为 `1` 以启用魔法链接登录 |
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/cognito'} title={'AWS Cognito'} />
 
-<Callout type={'tip'}>
-  详细的提供商配置可参考 [Next Auth 提供商文档](/zh/docs/self-hosting/advanced/auth/next-auth)（大部分配置兼容），或访问官方 [Better Auth 文档](https://www.better-auth.com/docs/introduction)。
-</Callout>
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/auth0'} title={'Auth0'} />
 
-<Callout type={'tip'}>
-  前往 [📘 环境变量](/zh/docs/self-hosting/environment-variables/auth#better-auth) 可查阅所有 Better Auth 相关变量详情。
-</Callout>
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/authelia'} title={'Authelia'} />
 
-## Next Auth
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/authentik'} title={'Authentik'} />
 
-在使用 NextAuth 之前，请先在 LobeChat 的环境变量中设置以下变量：
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/casdoor'} title={'Casdoor'} />
 
-| 环境变量                             | 类型 | 描述                                                                                                           |
-| -------------------------------- | -- | ------------------------------------------------------------------------------------------------------------ |
-| `NEXT_PUBLIC_ENABLE_NEXT_AUTH`   | 必选 | 用于启用 NextAuth 服务，设置为 `1` 以启用，更改此项需要重新编译应用。使用 `lobehub/lobe-chat-database` 镜像部署的用户已经默认添加了该项配置。                |
-| `NEXT_AUTH_SECRET`               | 必选 | 用于加密 Auth.js 会话令牌的密钥。您可以使用以下命令： `openssl rand -base64 32`，或者访问 `https://generate-secret.vercel.app/32` 生成秘钥。 |
-| `AUTH_URL`                       | 必选 | 该 URL 用于指定 Auth.js 在执行 OAuth 验证时的回调地址，当默认生成的重定向地址发生不正确时才需要设置。`https://example.com/api/auth`                  |
-| `NEXT_AUTH_SSO_PROVIDERS`        | 可选 | 该环境变量用于同时启用多个身份验证源，以逗号 `,` 分割，例如 `auth0,microsoft-entra-id,authentik`。                                       |
-| `NEXT_AUTH_SSO_SESSION_STRATEGY` | 可选 | Auth.js 的会话策略。选项为 `jwt` 或 `database`。默认值为 `jwt`。                                                             |
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
 
-目前支持的身份验证服务有：
-
-<Cards>
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/auth0'} title={'Auth0'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/keycloak'} title={'Keycloak'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/microsoft-entra-id'} title={'Microsoft Entra ID'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/logto'} title={'Logto'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/authentik'} title={'Authentik'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/okta'} title={'Okta'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/github'} title={'Github'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/zitadel'} title={'ZITADEL'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/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/next-auth/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/feishu'} title={'飞书'} />
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/authelia'} title={'Authelia'} />
+  <Card href={'/zh/docs/self-hosting/advanced/auth/better-auth/wechat'} title={'微信'} />
+</Cards>
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/logto'} title={'Logto'} />
+## 回调 URL 格式
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/keycloak'} title={'Keycloak'} />
+配置 OAuth 提供商时，请使用以下回调 URL 格式：
 
-  <Card href={'/zh/docs/self-hosting/advanced/auth/next-auth/okta'} title={'Okta'} />
-</Cards>
+- **开发环境**：`http://localhost:3210/api/auth/callback/{provider}`
+- **生产环境**：`https://yourdomain.com/api/auth/callback/{provider}`
 
-点击即可查看对应平台的配置文档。
+## 邮件服务配置
 
-## 进阶配置
+用于邮箱验证、密码重置和魔法链接发送。先选择邮件服务，再填对应变量：
 
-同时启用多个身份验证源请设置 `NEXT_AUTH_SSO_PROVIDERS` 环境变量，以逗号 `,` 分割，例如 `auth0,microsoft-entra-id,authentik`。
+| 环境变量                      | 类型 | 描述                                                                                        |
+| ------------------------- | -- | ----------------------------------------------------------------------------------------- |
+| `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` 时使用        |
 
-顺序为 SSO 提供商的显示顺序。
+## 魔法链接（免密）登录
 
-| SSO 提供商               | 值                       | 额外功能      |
-| --------------------- | ----------------------- | --------- |
-| Auth0                 | `auth0`                 |           |
-| Authenlia             | `authenlia`             |           |
-| Authentik             | `authentik`             |           |
-| Casdoor               | `casdoor`               | `Webhook` |
-| Cloudflare Zero Trust | `cloudflare-zero-trust` |           |
-| Github                | `github`                |           |
-| Logto                 | `logto`                 | `Webhook` |
-| Microsoft Entra ID    | `microsoft-entra-id`    |           |
-| ZITADEL               | `zitadel`               |           |
-| Keycloak              | `keycloak`              |           |
-| Okta                  | `okta`                  |           |
+启用魔法链接登录（依赖上方已配置好的邮件服务，默认关闭）：
 
-## 额外功能
+| 环境变量                | 类型 | 描述                      |
+| ------------------- | -- | ----------------------- |
+| `ENABLE_MAGIC_LINK` | 可选 | 设置为 `1` 以启用魔法链接登录（默认关闭） |
 
-### Webhook 支持
+<Callout type={'tip'}>
+  前往 [环境变量](/zh/docs/self-hosting/environment-variables/auth#better-auth) 可查阅所有 Better Auth 相关变量详情。
+</Callout>
 
-允许 LobeChat 在身份提供商中用户信息更新时接收通知。支持的提供商包括 Casdoor 和 Logto。请参考具体提供商文档进行配置。
+## 常见问题
 
-### 数据库会话
+### Better Auth 支持哪些 SSO 提供商？
 
-允许会话存储在数据库中，详情请参阅 [Auth.js 会话文档](https://authjs.dev/concepts/session-strategies#database-session)。
+Better Auth 支持内置提供商（Google、GitHub、Microsoft、Apple、AWS Cognito）和通用 OIDC 提供商（Auth0、Authelia、Authentik、Casdoor、Cloudflare Zero Trust、Keycloak、Logto、Okta、ZITADEL、Generic OIDC、飞书、微信）。
 
-## 其他 SSO 提供商
+### 如何启用多个 SSO 提供商？
 
-请参考 [NextAuth.js](https://next-auth.js.org/providers) 文档，欢迎提交 Pull Request。
+设置 `AUTH_SSO_PROVIDERS` 环境变量，使用逗号分隔多个提供商，例如 `google,github,microsoft`。顺序决定登录页面上的显示顺序。

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

@@ -44,11 +44,17 @@ Before connecting the desktop to your self-hosted instance, ensure that your sel
 
 #### OIDC Environment Variable Configuration
 
-You need to add the following two environment variables, `ENABLE_OIDC` and `JWKS_KEY`, to your self-hosted instance. You can click the button below to generate them with one click:
+You need to add the following two environment variables, `ENABLE_OIDC` and `JWKS_KEY`, to your self-hosted instance:
 
-<OIDCJWKs />
+```bash
+ENABLE_OIDC=1
+```
+
+Click the button below to generate `JWKS_KEY`:
+
+<GenerateJWKSKey />
 
-Add the generated JWK key to your environment variables.
+Add the generated environment variables to your deployment configuration.
 
 <Callout>If you have already configured `OIDC_JWKS_KEY`, no changes are needed. The system will automatically fall back to `OIDC_JWKS_KEY` for backward compatibility.</Callout>