---
title: LobeHub 2.0 破坏性变更
description: LobeHub 2.0 破坏性变更完整指南，帮助用户从 1.x 版本升级到 2.0 版本。
tags:
  - LobeHub 2.0
  - 迁移指南
  - 破坏性变更
  - 身份验证
---

# LobeHub 2.0 破坏性变更

本文档概述了 LobeHub 2.0 中引入的破坏性变更，并为从 1.x 版本升级的用户提供迁移指南。

## 移除的环境变量

以下环境变量在 LobeHub 2.0 中已被移除：

| 环境变量                                | 移除原因                                         |
| ----------------------------------- | -------------------------------------------- |
| `ACCESS_CODE`                       | 不再支持，请使用 Better Auth 认证系统                    |
| `NEXT_PUBLIC_SERVICE_MODE`          | 2.0 仅支持 Server DB 模式，不再支持 Client DB (PGlite) |
| `NEXT_PUBLIC_ENABLE_BETTER_AUTH`    | 通过 `AUTH_SECRET` 是否存在自动检测                    |
| `NEXT_PUBLIC_AUTH_URL` / `AUTH_URL` | 从请求头中自动检测                                    |
| `NEXT_PUBLIC_ENABLE_NEXT_AUTH`      | NextAuth 已移除                                 |
| `NEXT_AUTH_SECRET`                  | NextAuth 已移除                                 |
| `NEXT_AUTH_SSO_PROVIDERS`           | NextAuth 已移除                                 |
| `NEXTAUTH_URL`                      | NextAuth 已移除                                 |
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk 已移除                                    |
| `CLERK_SECRET_KEY`                  | Clerk 已移除                                    |

## 新增的必需环境变量

LobeHub 2.0 仅支持 Better Auth 认证系统。以下环境变量现在是必需的：

- `AUTH_SECRET`：用于加密会话令牌
- `JWKS_KEY`：用于签名和验证 JWT，包括 OIDC JWT token 和内部服务调用认证 token

## 新增的可选环境变量

| 环境变量                      | 说明                      |
| ------------------------- | ----------------------- |
| `AUTH_SSO_PROVIDERS`      | 启用的 SSO 提供商列表，以逗号分隔     |
| `INTERNAL_JWT_EXPIRATION` | 内部 JWT 令牌过期时间（默认：`30s`） |
| `AUTH_EMAIL_VERIFICATION` | 设置为 `1` 以要求邮箱验证         |
| `SMTP_HOST`               | 邮件功能的 SMTP 服务器主机名       |
| `SMTP_PORT`               | SMTP 服务器端口              |
| `SMTP_USER`               | SMTP 认证用户名              |
| `SMTP_PASS`               | SMTP 认证密码               |

详细配置请参阅[身份验证环境变量](/docs/self-hosting/environment-variables/auth)。

## 认证系统变更

LobeHub 2.0 仅支持 Better Auth 认证系统，不再支持 NextAuth 和 Clerk。

## 迁移指南

### 从 NextAuth 迁移

请参阅 [NextAuth 迁移指南](/zh/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth)。

### 从 Clerk 迁移

请参阅 [Clerk 迁移指南](/zh/docs/self-hosting/migration/v2/auth/clerk-to-betterauth)。

## 数据库模式变更

LobeHub 2.0 仅支持 Server DB 模式，不再支持 Client DB (PGlite)。如果您之前使用 `NEXT_PUBLIC_SERVICE_MODE=client`，需要迁移到 Server DB 部署方式。

详细部署指南请参阅[服务端数据库部署](/docs/self-hosting/server-database)。

## PostgreSQL 版本要求

LobeHub 2.0 推荐使用 **PostgreSQL 17** 及以上版本。

这是因为 LobeHub 2.0 使用了 [pg\_search](https://github.com/paradedb/paradedb/tree/main/pg_search) 插件来提供全文搜索能力。如果您使用 Neon 等 Serverless Postgres 服务，pg\_search 插件仅在 PostgreSQL 17 上可用。

如果您使用 Docker 自建数据库，推荐使用 `paradedb/paradedb:latest-pg17` 镜像。
