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

---
title: LobeHub 身份验证服务配置
description: >-
  了解如何使用 Better Auth、Clerk 或 Next Auth 配置外部身份验证服务，以统一管理用户授权。支持的身份验证服务包括 Auth0、
  Azure ID 等。
tags:
  - 身份验证服务
  - Better Auth
  - LobeHub
  - SSO
---

# 身份验证服务

LobeHub 支持使用 Better Auth、Clerk 或者 Next Auth 配置外部身份验证服务，供企业 / 组织内部使用，统一管理用户授权。

<Callout type={'info'}>
  需要使用旧版身份验证方案？请参阅 [旧版身份验证](/zh/docs/self-hosting/advanced/auth/legacy) 了解 NextAuth 和 Clerk 的文档。
</Callout>

Clerk 是一个近期流行起来的全面的身份验证解决方案，它提供了简单而强大的 API 和服务来处理用户认证和会话管理。Clerk 的设计哲学是提供一套简洁、现代的认证解决方案，使得开发者可以轻松集成和使用。

LobeHub 与 Clerk 做了深度集成，能够为用户提供一个更加安全、便捷的登录和注册体验，同时也为开发者减轻了管理身份验证逻辑的负担。Clerk 的简洁和现代的设计理念与 LobeHub 的目标非常契合，使得整个平台的用户管理更加高效和可靠。

在 LobeHub 的环境变量中设置 `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 标准的提供商

## 快速开始

要在 LobeHub 中启用 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://LobeHub.com`）。Vercel 部署时可选（会自动从 `VERCEL_URL` 获取） |
| `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/providers/github'} title={'GitHub'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/google'} title={'Google'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/microsoft'} title={'Microsoft'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/apple'} title={'Apple'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/cognito'} title={'AWS Cognito'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/auth0'} title={'Auth0'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/authelia'} title={'Authelia'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/authentik'} title={'Authentik'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/casdoor'} title={'Casdoor'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/cloudflare-zero-trust'} title={'Cloudflare Zero Trust'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/keycloak'} title={'Keycloak'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/logto'} title={'Logto'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/okta'} title={'Okta'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/zitadel'} title={'ZITADEL'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/generic-oidc'} title={'Generic OIDC'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/feishu'} title={'飞书'} />

  <Card href={'/zh/docs/self-hosting/advanced/auth/providers/wechat'} title={'微信'} />
</Cards>

## 回调 URL 格式

配置 OAuth 提供商时，请使用以下回调 URL 格式：

- **开发环境**：`http://localhost:3210/api/auth/callback/{provider}`
- **生产环境**：`https://yourdomain.com/api/auth/callback/{provider}`

## 邮件服务配置

用于邮箱验证、密码重置和魔法链接发送。支持两种邮件服务：

### 方式一：Nodemailer（SMTP）

使用 SMTP 协议发送邮件，适合已有邮箱服务的用户。参考 [Nodemailer SMTP 文档](https://nodemailer.com/smtp/)。

| 环境变量                     | 类型 | 描述                                             | 示例                    |
| ------------------------ | -- | ---------------------------------------------- | --------------------- |
| `EMAIL_SERVICE_PROVIDER` | 可选 | 设置为 `nodemailer`（默认值）                          | `nodemailer`          |
| `SMTP_HOST`              | 必选 | SMTP 服务器主机名                                    | `smtp.gmail.com`      |
| `SMTP_PORT`              | 必选 | SMTP 服务器端口（TLS 通常为 `587`，SSL 为 `465`）          | `587`                 |
| `SMTP_SECURE`            | 可选 | SSL 设置为 `true`（端口 465），TLS 设置为 `false`（端口 587） | `false`               |
| `SMTP_USER`              | 必选 | SMTP 认证用户名                                     | `user@gmail.com`      |
| `SMTP_PASS`              | 必选 | SMTP 认证密码                                      | `your-app-password`   |
| `SMTP_FROM`              | 可选 | 发件人地址（AWS SES 必填），默认为 `SMTP_USER`              | `noreply@example.com` |

<Callout type={'warning'}>
  使用 Gmail 时，需使用应用专用密码而非账户密码。前往 [Google 应用专用密码](https://myaccount.google.com/apppasswords) 生成。
</Callout>

### 方式二：Resend

[Resend](https://resend.com/) 是一个现代邮件 API 服务，配置简单，推荐新用户使用。

| 环境变量                     | 类型 | 描述                        | 示例                          |
| ------------------------ | -- | ------------------------- | --------------------------- |
| `EMAIL_SERVICE_PROVIDER` | 必选 | 设置为 `resend`              | `resend`                    |
| `RESEND_API_KEY`         | 必选 | Resend API Key            | `re_xxxxxxxxxxxxxxxxxxxxxx` |
| `RESEND_FROM`            | 推荐 | 发件人地址，需为 Resend 已验证域名下的邮箱 | `noreply@your-domain.com`   |

<Callout type={'info'}>
  使用 Resend 前需先 [验证发件域名](https://resend.com/docs/dashboard/domains/introduction)，否则只能发送到自己的邮箱。
</Callout>

### 通用配置

在使用 NextAuth 之前，请先在 LobeHub 的环境变量中设置以下变量：

## 魔法链接（免密）登录

启用魔法链接登录（依赖上方已配置好的邮件服务，默认关闭）：

| 环境变量                     | 类型 | 描述                      |
| ------------------------ | -- | ----------------------- |
| `AUTH_ENABLE_MAGIC_LINK` | 可选 | 设置为 `1` 以启用魔法链接登录（默认关闭） |

<Callout type={'tip'}>
  前往 [环境变量](/zh/docs/self-hosting/environment-variables/auth#better-auth) 可查阅所有 Better Auth 相关变量详情。
</Callout>

## 会话存储配置（可选）

默认情况下，Better Auth 使用数据库存储会话数据。你可以配置 Redis 作为二级存储，以获得更好的性能和跨实例会话共享能力。

| 环境变量           | 类型 | 描述                              |
| -------------- | -- | ------------------------------- |
| `REDIS_URL`    | 可选 | Redis 连接 URL，配置后自动启用 Redis 会话存储 |
| `REDIS_PREFIX` | 可选 | Redis 键前缀，默认为 `lobechat`        |

<Callout type={'info'}>
  配置 Redis 后，认证会话数据将存储在 Redis 中，可以实现跨多个服务实例的会话共享，并提升会话验证速度。详细配置请参阅 [Redis 缓存服务](/zh/docs/self-hosting/advanced/redis)。
</Callout>

## 常见问题

### Better Auth 支持哪些 SSO 提供商？

Better Auth 支持内置提供商（Google、GitHub、Microsoft、Apple、AWS Cognito）和通用 OIDC 提供商（Auth0、Authelia、Authentik、Casdoor、Cloudflare Zero Trust、Keycloak、Logto、Okta、ZITADEL、Generic OIDC、飞书、微信）。

### 如何启用多个 SSO 提供商？

设置 `AUTH_SSO_PROVIDERS` 环境变量，使用逗号分隔多个提供商，例如 `google,github,microsoft`。顺序决定登录页面上的显示顺序。

### Casdoor 用户只有 username 没有 email 怎么办？

当前身份验证方案强依赖 email。请在 Casdoor 中为用户配置有效的 email 地址。
强烈建议使用真实有效的邮箱，否则密码重置、魔法链接登录等功能将无法使用。

### 如何限制只允许特定邮箱或域名注册？

设置 `AUTH_ALLOWED_EMAILS` 环境变量，支持完整邮箱地址或域名，以逗号分隔。例如：

- 只允许 `example.com` 域名：`AUTH_ALLOWED_EMAILS=example.com`
- 允许多个域名和特定邮箱：`AUTH_ALLOWED_EMAILS=example.com,company.org,admin@other.com`

### Webhook 支持

允许 LobeHub 在身份提供商中用户信息更新时接收通知。支持的提供商包括 Casdoor 和 Logto。请参考具体提供商文档进行配置。

### 数据库会话

允许会话存储在数据库中，详情请参阅 [Auth.js 会话文档](https://authjs.dev/concepts/session-strategies#database-session)。

## 其他 SSO 提供商

请参考 [NextAuth.js](https://next-auth.js.org/providers) 文档，欢迎提交 Pull Request。