diff --git a/docker-compose/.env.example b/docker-compose/.env.example index 7c2028c6b367..abca5aaa90c7 100644 --- a/docker-compose/.env.example +++ b/docker-compose/.env.example @@ -12,7 +12,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/postgres # Here we take Logto as an example NEXT_AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg NEXT_AUTH_SSO_PROVIDERS=logto -NEXTAUTH_URL=https://lobe-auth-api.example.com/api/auth +NEXTAUTH_URL=https://lobe.example.com/api/auth LOGTO_CLIENT_ID=buc2lpttyo6evdtrfqsur LOGTO_CLIENT_SECRET=d97eztx8Ej6aUafeToMAL4jugAKGTAH4 LOGTO_ISSUER=https://lobe-auth-api.example.com/oidc diff --git a/docker-compose/.env.zh-CN.example b/docker-compose/.env.zh-CN.example index a01aeade7ff8..bc022de5fae5 100644 --- a/docker-compose/.env.zh-CN.example +++ b/docker-compose/.env.zh-CN.example @@ -12,7 +12,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/postgres # 这里以 Logto 为例 NEXT_AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg NEXT_AUTH_SSO_PROVIDERS=logto -NEXTAUTH_URL=https://lobe-auth-api.example.com/api/auth +NEXTAUTH_URL=https://lobe.example.com/api/auth LOGTO_CLIENT_ID=buc2lpttyo6evdtrfqsur LOGTO_CLIENT_SECRET=d97eztx8Ej6aUafeToMAL4jugAKGTAH4 LOGTO_ISSUER=https://lobe-auth-api.example.com/oidc diff --git a/docs/self-hosting/advanced/auth/next-auth/github.mdx b/docs/self-hosting/advanced/auth/next-auth/github.mdx index 3fbc1ea11c09..8f4b38408e32 100644 --- a/docs/self-hosting/advanced/auth/next-auth/github.mdx +++ b/docs/self-hosting/advanced/auth/next-auth/github.mdx @@ -89,7 +89,7 @@ When deploying LobeChat, you need to configure the following environment variabl | `NEXTAUTH_URL` | Optional | This URL is used to specify the callback address for Auth.js when performing OAuth authentication. Only set it if the default generated redirect address is incorrect. `https://example.com/api/auth` | - Go to [📘 Environment Variables](/docs/self-hosting/environment-variable#Github) for detailed + Go to [📘 Environment Variables](/docs/self-hosting/environment-variables/auth#github) for detailed information on these variables. diff --git a/docs/self-hosting/advanced/auth/next-auth/github.zh-CN.mdx b/docs/self-hosting/advanced/auth/next-auth/github.zh-CN.mdx index 3ec56efa01f8..ea98bdc80ef6 100644 --- a/docs/self-hosting/advanced/auth/next-auth/github.zh-CN.mdx +++ b/docs/self-hosting/advanced/auth/next-auth/github.zh-CN.mdx @@ -1,6 +1,6 @@ --- title: 在 LobeChat 中配置 Github 身份验证服务 -description: 学习如何在 LobeChat 中配置Github身份验证服务，包括创建新的Github App、设置权限和环境变量。 +description: 学习如何在 LobeChat 中配置 Github 身份验证服务，包括创建新的 Github App、设置权限和环境变量。 tags: - Github 身份验证 - Github App @@ -16,9 +16,9 @@ tags: ### 创建 Github 提供应用 -点击[这里](https://github.com/settings/apps/new) 创建一个新的 Github App。 +点击 [这里](https://github.com/settings/apps/new) 创建一个新的 Github App。 -填写Github App name、Homepage URL、Callbak URL +填写 Github App name、Homepage URL、Callbak URL 创建 Github 提供程序 - 前往 [📘 环境变量](/docs/self-hosting/environment-variable#Github) 可查阅相关变量详情。 + 前往 [📘 环境变量](/docs/self-hosting/environment-variables/auth#github) 可查阅相关变量详情。 diff --git a/docs/self-hosting/advanced/auth/next-auth/logto.mdx b/docs/self-hosting/advanced/auth/next-auth/logto.mdx new file mode 100644 index 000000000000..276a5af0b15d --- /dev/null +++ b/docs/self-hosting/advanced/auth/next-auth/logto.mdx @@ -0,0 +1,74 @@ +--- +title: Configuring Logto Authentication Service in LobeChat +description: >- + Learn how to configure Logto authentication service in LobeChat, including + deployment, creation, setting permissions, and environment variables. +tags: + - Logto Authentication + - Environment Variable Configuration + - Single Sign-On + - LobeChat +--- + +# Configuring Logto Authentication Service + +[Logto](https://github.com/logto-io/logto) is an open-source authentication service with a simple and beautiful interface, rich in features and easy to use. You can choose to use the official Logto Cloud or opt for a private deployment of Logto. + + + +If you want to deploy Logto privately, we recommend using Docker Compose to deploy it together with the LobeChat database version. In this case, LobeChat can share the same Postgres instance with it. + + + +## Logto Configuration Process + +The following assumes your LobeChat database version domain is `https://lobe.example.com`. + +If you are using a privately deployed Logto, assume its endpoint domain is `https://lobe-auth-api.example.com`. + +If you are using Logto Cloud, assume its endpoint domain is `https://example.logto.app`. + + + ### Create Logto Application + + Access your privately deployed Logto WebUI or [Logto Cloud](http://cloud.logto.io/) to enter the console, and create a `Next.js (App Router)` application under `Applications` with any name. + + ### Configure Logto + + Set the `Redirect URI` to `https://lobe.example.com/api/auth/callback/logto` and the `Post sign-out redirect URI` to `https://lobe.example.com/`. + + Set `CORS allowed origins` to `https://lobe.example.com`. + + Configure Logto + + After successful creation, save the `Client ID` and `Client Secret`. + + ### Configure Environment Variables + + Configure Environment Variables + + Set the obtained `Client ID` and `Client Secret` as `LOGTO_CLIENT_ID` and `LOGTO_CLIENT_SECRET` in the LobeChat environment variables. + + Configure `LOGTO_ISSUER` in the LobeChat environment variables as follows: + + - `https://lobe-auth-api.example.com/oidc` if you are using a privately deployed Logto + - `https://example.logto.app/oidc` if you are using Logto Cloud + + When deploying LobeChat, you need to configure the following environment variables: + + | Environment Variable | Type | Description | + | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `NEXT_AUTH_SECRET` | Required | The key used to encrypt Auth.js session tokens. You can generate a key using the command: `openssl rand -base64 32` | + | `NEXT_AUTH_SSO_PROVIDERS` | Required | Select the single sign-on provider for LobeChat. For Logto, enter `logto`. | + | `LOGTO_CLIENT_ID` | Required | The Client ID from the Logto App details page | + | `LOGTO_CLIENT_SECRET` | Required | The Client Secret from the Logto App details page | + | `LOGTO_ISSUER` | Required | OpenID Connect issuer of the Logto provider | + | `NEXTAUTH_URL` | Optional | This URL specifies the callback address for Auth.js during OAuth verification, needed only if the default generated redirect address is incorrect. `https://lobe.example.com/api/auth` | + + + Visit [📘 Environment Variables](/docs/self-hosting/environment-variables/auth#logto) for details on related variables. + + + + +After successful deployment, users will be able to authenticate via Logto and use LobeChat. diff --git a/docs/self-hosting/advanced/auth/next-auth/logto.zh-CN.mdx b/docs/self-hosting/advanced/auth/next-auth/logto.zh-CN.mdx new file mode 100644 index 000000000000..4bb229ceb991 --- /dev/null +++ b/docs/self-hosting/advanced/auth/next-auth/logto.zh-CN.mdx @@ -0,0 +1,78 @@ +--- +title: 在 LobeChat 中配置 Logto 身份验证服务 +description: 学习如何在 LobeChat 中配置 Logto 身份验证服务，包括部署、创建、设置权限和环境变量。 +tags: + - Logto 身份验证 + - 环境变量配置 + - 单点登录 + - LobeChat +--- + +# 配置 Logto 身份验证服务 + +[Logto](https://github.com/logto-io/logto) 是一个开源的身份验证服务，界面简洁美观、功能配置丰富且易于上手，你即可以选择使用其官方提供的 Logto Cloud，也可以选择私有部署 Logto。 + + + 若你想要私有部署 Logto，我们建议你将之与 LobeChat 数据库版本一同使用 Docker Compose 部署，此时 LobeChat 可以与之共用同一个 Postgres 实例。 + + +## Logto 配置流程 + +下文假设你的 LobeChat 数据库版本域名为 `https://lobe.example.com`。 + +若你是私有部署的 Logto，假设其 endpoint 域名为 `https://lobe-auth-api.example.com`。 + +若你是使用的 Logto Cloud，假设其 endpoint 域名为 `https://example.logto.app`。 + + + ### 创建 Logto 应用 + +访问你私有部署的 Logto WebUI 或者 [Logto Cloud](http://cloud.logto.io/) 进入控制台，在 `Applications` 里创建一个 `Next.js (App Router)` 应用，名称随意 + +### 配置 Logto + +配置 `Redirect URI` 为 `https://lobe.example.com/api/auth/callback/logto`，`Post sign-out redirect URI` 为 `https://lobe.example.com/` + +配置 `CORS allowed origins` 为 `https://lobe.example.com` + +配置 Logto + +创建成功后， 将 `Client ID` 和 `Client Secret` 保存下来。 + +### 配置环境变量 + +配置环境变量 + +将获取到的 `Client ID` 和 `Client Secret`，设为 LobeChat 环境变量中的 `LOGTO_CLIENT_ID` 和 `LOGTO_CLIENT_SECRETT`。 + +配置 LobeChat 环境变量中 `LOGTO_ISSUER` 为： + +- `https://lobe-auth-api.example.com/oidc`，若你是私有部署的 Logto +- `https://example.logto.app/oidc`，若你是使用的 Logto Cloud + +在部署 LobeChat 时，你需要配置以下环境变量： + +| 环境变量 | 类型 | 描述 | +| --- | --- | --- | +| `NEXT_AUTH_SECRET` | 必选 | 用于加密 Auth.js 会话令牌的密钥。您可以使用以下命令生成秘钥： `openssl rand -base64 32` | +| `NEXT_AUTH_SSO_PROVIDERS` | 必选 | 选择 LoboChat 的单点登录提供商。使用 Logto 请填写 `logto`。 | +| `LOGTO_CLIENT_ID` | 必选 | Logto App 详情页的 Client ID | +| `LOGTO_CLIENT_SECRET` | 必选 | Logto App 详情页的 Client Secret | +| `LOGTO_ISSUER` | 必选 | Logto 提供程序的 OpenID Connect 颁发者 | +| `NEXTAUTH_URL` | 可选 | 该 URL 用于指定 Auth.js 在执行 OAuth 验证时的回调地址，当默认生成的重定向地址发生不正确时才需要设置。`https://lobe.example.com/api/auth` | + + + 前往 [📘 环境变量](/docs/self-hosting/environment-variables/auth#logto) 可查阅相关变量详情。 + + + + +部署成功后，用户将可以通过 Logto 身份认证并使用 LobeChat。 diff --git a/docs/self-hosting/environment-variables/auth.mdx b/docs/self-hosting/environment-variables/auth.mdx index 974a6a065e86..68f32a9f5f78 100644 --- a/docs/self-hosting/environment-variables/auth.mdx +++ b/docs/self-hosting/environment-variables/auth.mdx @@ -194,6 +194,27 @@ LobeChat provides a complete authentication service capability when deployed. Th - Default: `-` - Example: `https://your-instance-abc123.zitadel.cloud` +#### `LOGTO_CLIENT_ID` + +- Type: Required +- Description: The Client ID of the Logto application. You can find it in the Logto console for private deployment or [Logto Cloud](http://cloud.logto.io/) depending on the deployment mode. +- Default value: `-` +- Example: `123456789012345678@your-project` + +#### `LOGTO_CLIENT_SECRET` + +- Type: Required +- Description: The Client Secret of the Logto application. +- Default value: `-` +- Example: `9QF1n5ATzU7Z3mHp2Iw4gKX8kY6oR7uW1DnKcV3LqX2jF6iG3fBmJ1kV7nS5zE6A` + +#### `LOGTO_ISSUER` + +- Type: Required +- Description: The OpenID Connect issuer of the Logto application. You can find it in the Logto console for private deployment or [Logto Cloud](http://cloud.logto.io/) depending on the deployment mode. +- Default value: `-` +- Example: `https://lobe-auth-api.example.com/oidc` + Currently, we only support providers above. If you need to use other identity verification service providers, you can submit a [feature diff --git a/docs/self-hosting/environment-variables/auth.zh-CN.mdx b/docs/self-hosting/environment-variables/auth.zh-CN.mdx index 96bd8eb64eff..53da3f322703 100644 --- a/docs/self-hosting/environment-variables/auth.zh-CN.mdx +++ b/docs/self-hosting/environment-variables/auth.zh-CN.mdx @@ -157,17 +157,17 @@ LobeChat 在部署时提供了完善的身份验证服务能力，以下是相 #### `GITHUB_CLIENT_ID` -- Type: Required -- Description: Github应用的客户端ID。您可以在[这里](https://github.com/settings/apps)访问，并导航到应用程序设置以查看。 -- Default: `-` -- Example: `abd94200333283550508` +- 类型：必选 +- 描述: Github 应用的客户端 ID。您可以在[这里](https://github.com/settings/apps)访问，并导航到应用程序设置以查看。 +- 默认值: `-` +- 示例: `abd94200333283550508` #### `GITHUB_CLIENT_SECRET` -- Type: Required -- Description: Github应用的客户端密钥。 -- Default: `-` -- Example: `dd262976ac0931d947e104891586a053f3d3750b` +- 类型：必选 +- 描述: Github应用的客户端密钥。 +- 默认值: `-` +- 示例: `dd262976ac0931d947e104891586a053f3d3750b` ### ZITADEL @@ -192,6 +192,29 @@ LobeChat 在部署时提供了完善的身份验证服务能力，以下是相 - 默认值：`-` - 示例：`https://your-instance-abc123.zitadel.cloud` +### Logto + +#### `LOGTO_CLIENT_ID` + +- 类型：必选 +- 描述：Logto 应用程序的 Client ID。您可以在根据部署模式，在私有部署的 Logto 控制台或 [Logto Cloud](http://cloud.logto.io/) 中找到。 +- 默认值：`-` +- 示例：`123456789012345678@your-project` + +#### `LOGTO_CLIENT_SECRET` + +- 类型：必选 +- 描述：Logto 应用程序的 Client Secret。 +- 默认值：`-` +- 示例：`9QF1n5ATzU7Z3mHp2Iw4gKX8kY6oR7uW1DnKcV3LqX2jF6iG3fBmJ1kV7nS5zE6A` + +#### `LOGTO_ISSUER` + +- 类型：必选 +- 描述：Logto 应用程序的 OpenID Connect 颁发者（issuer）。根据部署模式，您可以在私有部署的 Logto 控制台或 [Logto Cloud](http://cloud.logto.io/) 中找到。 +- 默认值：`-` +- 示例：`https://lobe-auth-api.example.com/oidc` + 如果您需要使用其他身份验证服务提供商，可以提交 [功能请求](https://github.com/lobehub/lobe-chat/issues/new/choose) 或 Pull Request。 diff --git a/docs/self-hosting/server-database/docker-compose.mdx b/docs/self-hosting/server-database/docker-compose.mdx index afc1d1103e5c..db051acb5ef3 100644 --- a/docs/self-hosting/server-database/docker-compose.mdx +++ b/docs/self-hosting/server-database/docker-compose.mdx @@ -141,7 +141,7 @@ You have successfully deployed the LobeChat database version, and you can access If you encounter issues, please check the Docker logs and console logs, and follow the detailed troubleshooting guide later in the document. ```sh -docker logs -f lobe-chat-database +docker logs -f lobe-database ``` If you see the following logs in the container, it indicates that it has started successfully: @@ -214,7 +214,7 @@ Refer to the example configurations in the appendix of this article. You can check the logs using the following command: ```sh -docker logs -f lobe-chat-database +docker logs -f lobe-database ``` @@ -257,17 +257,26 @@ You need to first access the WebUI for configuration: 4. Set `CORS allowed origins` to `https://lobe.example.com`. - ![image](https://github.com/user-attachments/assets/5b816379-c07b-40ea-bde4-df16e2e4e523) + Configure Logto 5. Obtain `Client ID` and `Client Secret`, and fill them into your `.env` file under `LOGTO_CLIENT_ID` and `LOGTO_CLIENT_SECRET`. 6. Set `LOGTO_ISSUER` in your `.env` file to `https://lobe-auth-api.example.com/oidc`. - ![image](https://github.com/user-attachments/assets/15af6d94-af4f-4aa9-bbab-7a46e9f9e837) + Configure environment variables 7. Optional: In the left panel under `Sign-in experience`, in `Sign-up and sign-in - Advanced Options`, disable `Enable user registration` to prohibit user self-registration. If you disable user self-registration, you can only manually add users in the left panel under `User Management`. - ![image](https://github.com/user-attachments/assets/6b2e6f7b-fec5-41c6-864a-a1add40f74a0) + Disable user registration 8. Restart the LobeChat service: @@ -302,17 +311,29 @@ You need to first access the WebUI for configuration: 2. In the left panel under Administer / Buckets, click `Create Bucket`, enter `lobe` (corresponding to your `S3_BUCKET` environment variable), and then click `Create`. - ![image](https://github.com/user-attachments/assets/79f44a13-00d3-4302-a6bc-5f4c6cdbffab) + Create a bucket 3. Select your bucket, click Summary - Access Policy, edit, choose `Custom`, and input the content from `minio-bucket-config.json` (see appendix) and save (again, assuming your bucket name is `lobe`): - ![image](https://github.com/user-attachments/assets/57032a82-7604-45d3-ba12-884af6fbcb7c) + Select MinIO bucket policy - ![image](https://github.com/user-attachments/assets/d8109f4e-71fc-4ba8-8402-ede92669d5e0) + Configure MinIO bucket policy 4. In the left panel under User / Access Keys, click `Create New Access Key`, make no additional modifications, and fill the generated `Access Key` and `Secret Key` into your `.env` file under `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY`. - ![image](https://github.com/user-attachments/assets/72f02ce5-9991-425b-9864-9113ee1ed6bf) + Create a new access key 5. Restart the LobeChat service: @@ -343,7 +364,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/postgres # Here we take Logto as an example NEXT_AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg NEXT_AUTH_SSO_PROVIDERS=logto -NEXTAUTH_URL=https://lobe-auth-api.example.com/api/auth +NEXTAUTH_URL=https://lobe.example.com/api/auth LOGTO_CLIENT_ID=buc2lpttyo6evdtrfqsur LOGTO_CLIENT_SECRET=d97eztx8Ej6aUafeToMAL4jugAKGTAH4 LOGTO_ISSUER=https://lobe-auth-api.example.com/oidc diff --git a/docs/self-hosting/server-database/docker-compose.zh-CN.mdx b/docs/self-hosting/server-database/docker-compose.zh-CN.mdx index fc0b927ca4c9..700664bcf5d1 100644 --- a/docs/self-hosting/server-database/docker-compose.zh-CN.mdx +++ b/docs/self-hosting/server-database/docker-compose.zh-CN.mdx @@ -64,7 +64,7 @@ docker compose up -d 1. 打开 `http://localhost:3002`，访问 Logto WebUI，注册管理员账号 -2. 创建一个 `Next.js (App Router)` 应用，，添加以下配置： +2. 创建一个 `Next.js (App Router)` 应用，添加以下配置： - `Redirect URI` 为 `http://localhost:3210/api/auth/callback/logto` - `Post sign-out redirect URI` 为 `http://localhost:3210/` @@ -139,7 +139,7 @@ docker compose up -d 如果你遇到问题，请尝试查看 Docker 日志和控制台日志，并根据后文的详细指引进行排查。 ```sh -docker logs -f lobe-chat-database +docker logs -f lobe-database ``` 如果你在容器中看到了以下日志，则说明已经启动成功： @@ -211,7 +211,7 @@ docker logs -f lobe-chat-database 你可以使用下述指令检查日志： ```sh -docker logs -f lobe-chat-database +docker logs -f lobe-database ``` @@ -253,17 +253,26 @@ docker compose up -d # 重新启动 4. 配置 `CORS allowed origins` 为 `https://lobe.example.com` - ![image](https://github.com/user-attachments/assets/5b816379-c07b-40ea-bde4-df16e2e4e523) + 配置 Logto 5. 获取 `Client ID` 和 `Client Secret`，填入你的 `.env` 文件中的 `LOGTO_CLIENT_ID` 和 `LOGTO_CLIENT_SECRETT` 中 6. 配置你的 `.env` 文件中 `LOGTO_ISSUER` 为 `https://lobe-auth-api.example.com/oidc` - ![image](https://github.com/user-attachments/assets/15af6d94-af4f-4aa9-bbab-7a46e9f9e837) + 配置 Logto 环境变量 7. 可选，在左侧 `Sign-in experience` 面板的 `Sign-up and sign-in - Advanced Options` 中关闭 `Enable user registration`，禁止用户自行注册。如果你禁止了用户自行注册，那么你只能在左侧 `User Management` 里手动添加用户。 - ![image](https://github.com/user-attachments/assets/6b2e6f7b-fec5-41c6-864a-a1add40f74a0) + 关闭用户注册 8. 重启 LobeChat 服务： @@ -297,17 +306,29 @@ docker compose up -d # 重新启动 2. 在左侧面板 Administer / Buckets 中点击 `Create Bucket`，输入 `lobe`（对应你的 `S3_BUCKET` 环境变量），然后点击 `Create` - ![image](https://github.com/user-attachments/assets/79f44a13-00d3-4302-a6bc-5f4c6cdbffab) + 创建 MinIO 桶 3. 选中你的桶，点击 Summary - Access Policy，编辑，选择 `Custom`，输入 `minio-bucket-config.json` 中的内容（见附录）并保存（同样默认你的桶名为 `lobe`）： - ![image](https://github.com/user-attachments/assets/57032a82-7604-45d3-ba12-884af6fbcb7c) + 选中 MinIO 桶策略 - ![image](https://github.com/user-attachments/assets/d8109f4e-71fc-4ba8-8402-ede92669d5e0) + 配置 MinIO 桶策略 4. 在左侧面板 User / Access Keys 处，点击 `Create New Access Key`，无需额外修改，将生成的 `Access Key` 和 `Secret Key` 填入你的 `.env` 文件中的 `S3_ACCESS_KEY_ID` 和 `S3_SECRET_ACCESS_KEY` 中 - ![image](https://github.com/user-attachments/assets/72f02ce5-9991-425b-9864-9113ee1ed6bf) + 创建 MinIO 访问密钥 5. 重启 LobeChat 服务： @@ -338,7 +359,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/postgres # 这里以 Logto 为例 NEXT_AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg NEXT_AUTH_SSO_PROVIDERS=logto -NEXTAUTH_URL=https://lobe-auth-api.example.com/api/auth +NEXTAUTH_URL=https://lobe.example.com/api/auth LOGTO_CLIENT_ID=buc2lpttyo6evdtrfqsur LOGTO_CLIENT_SECRET=d97eztx8Ej6aUafeToMAL4jugAKGTAH4 LOGTO_ISSUER=https://lobe-auth-api.example.com/oidc