---
id: logto
title: Logto 认证集成
---

# Logto 认证集成

:::info
UPage 默认仅支持单一匿名用户访问，但您可以通过集成 Logto 实现用户认证，支持多用户登录
:::

UPage 支持与 [Logto](https://logto.io/) 集成，提供完整的用户认证体系。本文档将指导您如何配置 UPage 与 Logto 的集成。

## 什么是 Logto？

Logto 是一个开源的身份验证和授权解决方案，提供了完整的用户管理、身份验证和授权功能。通过与 Logto 集成，UPage 可以支持用户注册、登录、密码重置等功能，同时提供基于角色的访问控制。

## Logto 接入方式

Logto 支持两种接入方式，您可以根据自己的需求选择合适的方式。

1. 使用 Logto 官方提供的托管服务 - Logto Cloud。
2. 本地部署开源版 Logto 服务。

:::info
两种方式仅在接入方式上有所区别，在配置上完全一致。
:::

### 使用官方托管服务

访问 [Logto 官方网站](https://logto.io/)，注册一个账号即可进行下一步操作。

### 本地部署 Logto

UPage 提供了一个简化的 Logto 部署配置。在 UPage 项目目录下，您可以找到 `logto/docker-compose.yaml` 文件以及 `.env` 文件。

如果是开发环境，执行以下命令：

```bash
cd ./logto
docker-compose up -d
```

如果是生产环境，执行以下命令：

```bash
curl -L https://raw.githubusercontent.com/halo-dev/upage/refs/heads/main/logto/docker-compose.yaml -o ~/upage/logto/docker-compose.yaml
curl -L https://raw.githubusercontent.com/halo-dev/upage/refs/heads/main/logto/.env -o ~/upage/logto/.env
cd ~/upage/logto
docker-compose up -d
```

这将启动 Logto 服务，默认情况下可以通过 `http://localhost:3002` 访问 Logto 管理控制台。

:::caution
在生产环境部署时，请务必修改 `.env` 文件中的 `LOGTO_ENDPOINT` 、 `LOGTO_ADMIN_ENDPOINT` 以及 `LOGTO_POSTGRES_PASSWORD` 配置。
:::

## 配置 Logto

1. 访问 Logto 管理控制台，
2. 创建一个新的应用程序：
   - 应用类型：传统网页应用
   - 应用名称：UPage
   - 重定向 URIs：`http://${UPAGE_URL}/api/auth/callback`
   - 退出登录后重定向 URIs：`http://${UPAGE_URL}`
   - CORS 允许的来源：`http://${UPAGE_URL}`
   - 其他配置根据实际情况填写
3. 记录应用程序的 ID 和密钥，这些将用于配置 UPage

## 配置 UPage 与 Logto 集成

### 环境变量配置

在 UPage 的环境变量中配置 Logto 相关参数：

```bash
# 启用 Logto 认证
LOGTO_ENABLE=true
# Logto LOGTO_ENDPOINT 地址
LOGTO_ENDPOINT=http://localhost:3001
# Logto 应用程序 ID
LOGTO_APP_ID=your-app-id
# Logto 应用程序密钥
LOGTO_APP_SECRET=your-app-secret
# Logto 用于加密 cookie 的密钥，随机生成一个 32 位密钥即可
LOGTO_COOKIE_SECRET=your-cookie-secret
# 填写 UPage 地址，根据实际部署地址修改
LOGTO_BASE_URL=http://localhost:3000
```

如果使用 Docker compose 部署 UPage，在 `docker-compose.yml` 文件中添加这些环境变量：

```yaml
services:
  upage:
    # ... 其他配置
    environment:
      # ... 其他环境变量
      - LOGTO_ENABLE=true
      - LOGTO_ENDPOINT=http://logto:3001
      - LOGTO_APP_ID=your-app-id
      - LOGTO_APP_SECRET=your-app-secret
      - LOGTO_COOKIE_SECRET=your-cookie-secret
      - LOGTO_BASE_URL=http://localhost:3000
```

### 配置说明

| 环境变量 | 描述 | 示例 |
| --- | --- | --- |
| `LOGTO_ENABLE` | 是否启用 Logto 认证 | `true` |
| `LOGTO_ENDPOINT` | Logto 服务的 URL | `http://localhost:3001` |
| `LOGTO_APP_ID` | Logto 应用程序 ID | `your-app-id` |
| `LOGTO_APP_SECRET` | Logto 应用程序密钥 | `your-app-secret` |
| `LOGTO_COOKIE_SECRET` | 用于加密 cookie 的密钥 | `00bf44b6ceaa648eca6ad172f0cd8c8c` |
| `LOGTO_BASE_URL` | UPage 地址 | `http://localhost:3000` |

## Logto 使用技巧

:::tip
UPage 集成 Logto 步骤已完成，以下内容是 Logto 的特殊使用技巧，供扩展阅读，如无定制化需求可忽略。
:::

### 自定义登录界面

Logto 提供了自定义登录界面的功能：

1. 在 Logto 管理控制台中，导航到"外观"
2. 自定义登录页面的样式、颜色和品牌元素
3. 预览并保存更改

### 配置社交登录

Logto 支持多种社交登录方式：

1. 在 Logto 管理控制台中，导航到"连接器"
2. 添加社交登录连接器（如 Google、GitHub、微信等）
3. 按照向导完成配置

### 配置多因素认证

启用多因素认证以提高安全性：

1. 在 Logto 管理控制台中，导航到"安全"
2. 启用多因素认证
3. 配置多因素认证方式（如 TOTP、短信等）

## 下一步

- 阅读[用户指南](../user-guide/basics)学习如何使用 UPage 创建网页
- 探索[配置参考](../configuration)了解所有可用的配置选项