# logto

**Repository Path**: panxu11/logto

## Basic Information

- **Project Name**: logto
- **Description**: Logto
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Logto Server

这是一个基于 Docker Compose 的 Logto OSS 自托管部署项目，当前包含两个核心服务和两个一次性初始化辅助服务：

- `postgres`：PostgreSQL 16，用于保存 Logto 数据。
- `logto`：Logto 服务本体，对外提供核心服务和管理后台。
- `logto-init`：首次启动时初始化 Logto 数据库，运行完成后自动退出。
- `logto-disable-pwned-password-check`：关闭本地环境下的泄露密码检查，运行完成后自动退出。

当前配置适合本地开发、联调和初次体验。上线前请务必修改数据库密码、访问域名、端口暴露方式和镜像版本。

## 目录结构

```text
.
├── docker-compose.yml
└── README.md
```

## 本地启动

确保本机已安装 Docker 和 Docker Compose，然后在项目根目录执行：

```bash
docker compose up -d
```

查看服务状态：

```bash
docker compose ps
```

查看 Logto 日志：

```bash
docker compose logs -f logto
```

默认访问地址：

- Logto 核心服务：`http://localhost:3001`
- Logto 管理后台：`http://localhost:3002`
- PostgreSQL：`localhost:5432`

停止服务：

```bash
docker compose down
```

停止服务并删除数据库卷：

```bash
docker compose down -v
```

注意：`docker compose down -v` 会删除 `postgres_data`，数据库数据会丢失。

如果报错：Internal server error直接设置完整的值：
```bash
docker exec logto-postgres psql -U logto -d logto -c "UPDATE sign_in_experiences SET password_policy = '{\"length\":{\"min\":8,\"max\":256},\"rejects\":{\"pwned\":false,\"repetitionAndSequence\":false,\"personalInfo\":false,\"words\":[]}}'::jsonb;"
```
然后重启：
```bash
docker restart logto-server
```
再试注册。

## 当前配置说明

核心配置都在 `docker-compose.yml` 中。

| 配置项 | 当前值 | 说明 |
| --- | --- | --- |
| `POSTGRES_USER` | `logto` | PostgreSQL 用户名。 |
| `POSTGRES_PASSWORD` | `logto123` | PostgreSQL 密码，本地可用，上线必须修改。 |
| `POSTGRES_DB` | `logto` | PostgreSQL 数据库名。 |
| `DB_URL` | `postgresql://logto:logto123@postgres:5432/logto` | Logto 连接 PostgreSQL 的 DSN。修改数据库账号密码时要同步修改这里。 |
| `ENDPOINT` | `http://localhost:3001` | Logto 核心服务外部访问地址，上线后应改为 HTTPS 域名。 |
| `ADMIN_ENDPOINT` | `http://localhost:3002` | Logto 管理后台外部访问地址，上线后应改为 HTTPS 域名。 |
| `TRUST_PROXY_HEADER` | `1` | 使用 Nginx、Caddy、网关等 HTTPS 反向代理时需要开启。 |
| `3001:3001` | 本机 3001 到容器 3001 | Logto 核心服务端口映射。 |
| `3002:3002` | 本机 3002 到容器 3002 | Logto 管理后台端口映射。 |
| `5432:5432` | 本机 5432 到容器 5432 | PostgreSQL 端口映射。生产环境通常不建议公网暴露。 |

## 常见配置调整

### 1. 修改数据库密码

同时修改两处：

```yaml
postgres:
  environment:
    POSTGRES_PASSWORD: your-strong-password

logto:
  environment:
    - DB_URL=postgresql://logto:your-strong-password@postgres:5432/logto
```

如果数据库已经初始化过，单纯修改 `POSTGRES_PASSWORD` 不一定会自动修改已有数据库用户密码。生产环境建议在首次启动前就确定密码；如果已经运行过，请先备份数据，再进入数据库执行改密或重建环境。

### 2. 修改线上域名

假设线上域名为：

- 核心服务：`https://logto.example.com`
- 管理后台：`https://logto-admin.example.com`

修改为：

```yaml
logto:
  environment:
    - TRUST_PROXY_HEADER=1
    - DB_URL=postgresql://logto:your-strong-password@postgres:5432/logto
    - ENDPOINT=https://logto.example.com
    - ADMIN_ENDPOINT=https://logto-admin.example.com
```

`ENDPOINT` 会影响 OIDC issuer，`ADMIN_ENDPOINT` 会影响管理后台的回调地址。上线后不要随意反复切换域名，否则接入的应用可能需要同步更新配置。

### 3. 限制端口暴露

生产环境建议让 Logto 只监听服务器本机，由 Nginx、Caddy 或云厂商负载均衡统一暴露 HTTPS。

推荐将 Logto 端口改为只绑定本机：

```yaml
ports:
  - "127.0.0.1:3001:3001"
  - "127.0.0.1:3002:3002"
```

PostgreSQL 如果只给容器内部访问，可以移除这段：

```yaml
ports:
  - "5432:5432"
```

容器之间会继续通过 Docker 网络访问 `postgres:5432`，不需要把数据库端口暴露到公网。

### 4. 固定镜像版本

当前使用：

```yaml
image: svhd/logto:latest
```

生产环境建议改成明确版本，例如：

```yaml
image: svhd/logto:<version>
```

不要长期使用 `latest` 直接上线，避免镜像自动升级后出现不可预期的行为变化。升级时先备份数据库，再修改版本号并重新部署。

### 5. 启用 Secret Vault

如果需要使用 Logto 的 Secret Vault，需要设置 `SECRET_VAULT_KEK`。它应是 base64 编码的 32 字节密钥。

生成示例：

```bash
openssl rand -base64 32
```

添加到 `logto.environment`：

```yaml
- SECRET_VAULT_KEK=your-base64-key
```

这个值属于核心密钥，上线后要妥善保存。丢失或修改可能导致已加密的数据无法解密。

## 上线部署流程

### 1. 准备服务器

建议准备一台 Linux 服务器，并安装：

- Docker
- Docker Compose
- Nginx、Caddy 或其他 HTTPS 反向代理

官方自托管建议配置可按小型生产环境起步，例如 2 vCPU、8 GiB 内存、256 GiB 磁盘。实际规格应根据用户量、登录频率和数据库增长调整。

### 2. 准备域名和 HTTPS

准备两个域名并解析到服务器：

- `logto.example.com`：给应用接入、登录、OIDC/OAuth 使用。
- `logto-admin.example.com`：给管理员使用。

建议两个域名都启用 HTTPS。可以使用云厂商证书、Let's Encrypt、Nginx、Caddy 或网关产品完成 TLS 终止。

### 3. 调整 `docker-compose.yml`

上线前至少修改：

- `POSTGRES_PASSWORD`
- `DB_URL`
- `ENDPOINT`
- `ADMIN_ENDPOINT`
- `ports`
- `image` 版本

推荐生产配置方向：

```yaml
services:
  postgres:
    image: postgres:16-alpine
    container_name: logto-postgres
    environment:
      POSTGRES_USER: logto
      POSTGRES_PASSWORD: your-strong-password
      POSTGRES_DB: logto
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U logto"]
      interval: 5s
      timeout: 5s
      retries: 5

  logto:
    image: svhd/logto:<version>
    container_name: logto-server
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - TRUST_PROXY_HEADER=1
      - DB_URL=postgresql://logto:your-strong-password@postgres:5432/logto
      - ENDPOINT=https://logto.example.com
      - ADMIN_ENDPOINT=https://logto-admin.example.com
    ports:
      - "127.0.0.1:3001:3001"
      - "127.0.0.1:3002:3002"
    entrypoint: ["sh", "-c", "npm run cli db seed -- --swe && npm start"]

volumes:
  postgres_data:
```

### 4. 启动服务

```bash
docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f logto
```

确认 `logto` 和 `postgres` 都正常运行后，再配置反向代理。

### 5. 配置反向代理

Nginx 示例：

```nginx
server {
    listen 443 ssl;
    server_name logto.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 443 ssl;
    server_name logto-admin.example.com;

    location / {
        proxy_pass http://127.0.0.1:3002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

证书配置可以由 Certbot、Caddy 或云厂商自动生成。Nginx 方式需要补充 `ssl_certificate` 和 `ssl_certificate_key`。

### 6. 初始化和检查

部署完成后访问：

- `https://logto-admin.example.com`

进入管理后台后建议检查：

- 管理员账号和权限。
- 应用的 Redirect URI。
- Connector 配置，如邮箱、短信、社交登录。
- 自定义域名和品牌配置。
- 登录、注册、退出流程是否完整。

## 日常运维

查看服务：

```bash
docker compose ps
```

查看日志：

```bash
docker compose logs -f logto
docker compose logs -f postgres
```

重启服务：

```bash
docker compose restart logto
```

备份数据库：

```bash
docker exec logto-postgres pg_dump -U logto logto > logto-backup.sql
```

恢复数据库：

```bash
docker exec -i logto-postgres psql -U logto -d logto < logto-backup.sql
```

升级流程：

```bash
docker exec logto-postgres pg_dump -U logto logto > logto-backup-before-upgrade.sql
docker compose pull
docker compose up -d
docker compose logs -f logto
```

升级前建议先固定目标镜像版本，并阅读对应版本的发布说明。

## 上线前检查清单

- 已修改默认数据库密码。
- `DB_URL` 与数据库账号密码一致。
- `ENDPOINT` 已改为正式 HTTPS 核心服务域名。
- `ADMIN_ENDPOINT` 已改为正式 HTTPS 管理后台域名。
- 已开启 `TRUST_PROXY_HEADER=1`。
- PostgreSQL 未暴露到公网。
- Logto 端口优先只绑定 `127.0.0.1`。
- 已配置 HTTPS 证书和反向代理。
- 已准备数据库备份方案。
- 已固定 Logto 镜像版本。
- 已测试登录、注册、退出和应用回调流程。

## 参考文档

- Logto OSS 部署与配置：https://docs.logto.io/logto-oss/deployment-and-configuration
- Logto 核心服务配置：https://docs.logto.io/concepts/core-service/configuration