Logto 身份认证平台搭建教程

Logto 是一款开源的身份认证平台，提供了现代化的用户认证体验。它内置了精美的登录界面、完整的用户管理系统和丰富的 SDK 支持，是 Auth0 的优秀开源替代方案。Logto 使用 TypeScript 和 Node.js 构建，支持 OIDC 标准协议，可以轻松集成到各种 Web 和移动应用中。在搬瓦工 VPS 上通过 Docker 可以快速部署。

一、系统要求

操作系统：Ubuntu 20.04+（推荐 Ubuntu 22.04）。
内存：至少 1GB，建议 2GB。
Docker：需要预先安装 Docker 和 Docker Compose。
域名：建议准备两个子域名，一个用于管理后台，一个用于认证端点。

二、Docker Compose 部署

mkdir -p /opt/logto && cd /opt/logto

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  logto:
    image: svhd/logto:latest
    container_name: logto
    restart: always
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:3001:3001"
      - "127.0.0.1:3002:3002"
    environment:
      - TRUST_PROXY_HEADER=1
      - DB_URL=postgres://logto:LogtoDBPass123@db:5432/logto
      - ENDPOINT=https://auth.your-domain.com
      - ADMIN_ENDPOINT=https://admin-auth.your-domain.com

  db:
    image: postgres:16-alpine
    container_name: logto-db
    restart: always
    environment:
      - POSTGRES_USER=logto
      - POSTGRES_PASSWORD=LogtoDBPass123
      - POSTGRES_DB=logto
    volumes:
      - logto-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U logto -d logto"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  logto-db:
EOF

docker compose up -d

Logto 启动后会监听两个端口：3001 端口用于用户认证端点，3002 端口用于管理后台。

三、Nginx 反向代理

cat > /etc/nginx/sites-available/logto <<'EOF'
# 认证端点
server {
    listen 443 ssl http2;
    server_name auth.your-domain.com;

    ssl_certificate /etc/letsencrypt/live/auth.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        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 http2;
    server_name admin-auth.your-domain.com;

    ssl_certificate /etc/letsencrypt/live/admin-auth.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/admin-auth.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3002;
        proxy_http_version 1.1;
        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;
    }
}
EOF

ln -sf /etc/nginx/sites-available/logto /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

四、首次配置

在浏览器中访问管理后台 https://admin-auth.your-domain.com，首次访问时会引导你创建管理员账号。完成后进入管理界面，可以看到以下功能模块：

应用管理：创建和配置需要认证的应用。
连接器：配置社交登录和第三方身份提供者。
用户管理：查看和管理所有注册用户。
登录体验：自定义登录页面的外观和行为。
角色和权限：配置基于角色的访问控制（RBAC）。

五、创建应用

在管理后台的"Applications"中创建新应用，Logto 支持多种应用类型：

Traditional Web：传统的服务端渲染 Web 应用。
Single Page App：React、Vue、Angular 等 SPA 应用。
Native App：iOS、Android 等原生移动应用。
Machine to Machine：服务端 API 间的认证。

六、SDK 集成示例

6.1 React 应用集成

npm install @logto/react

import { LogtoProvider, LogtoConfig } from '@logto/react';

const config: LogtoConfig = {
  endpoint: 'https://auth.your-domain.com',
  appId: 'YOUR_APP_ID',
};

function App() {
  return (
    <LogtoProvider config={config}>
      <YourApp />
    </LogtoProvider>
  );
}

6.2 Node.js Express 集成

npm install @logto/express cookie-parser express-session

const { handleAuthRoutes, withLogto } = require('@logto/express');

app.use(handleAuthRoutes(config));

app.get('/protected', withLogto(config), (req, res) => {
  if (req.user.isAuthenticated) {
    res.json({ user: req.user.claims });
  } else {
    res.redirect('/logto/sign-in');
  }
});

七、配置社交登录

在管理后台的"Connectors"中添加社交登录连接器。Logto 官方支持的社交登录包括 GitHub、Google、Apple、微信、支付宝等。以 GitHub 为例：

在 GitHub 创建 OAuth App，获取 Client ID 和 Client Secret。
在 Logto 管理后台添加 GitHub 连接器，填入凭据。
在"Sign-in experience"中启用社交登录。

八、自定义登录体验

Logto 提供了丰富的登录页面自定义选项，在管理后台的"Sign-in experience"中可以配置：

品牌颜色和 Logo。
登录方式（用户名、邮箱、手机号、社交登录）。
注册策略和密码强度要求。
多语言支持。
深色/浅色主题。

九、数据备份

# 备份 PostgreSQL 数据
docker exec logto-db pg_dump -U logto logto > /opt/backups/logto_$(date +%Y%m%d).sql

# 定时备份
crontab -e
0 3 * * * docker exec logto-db pg_dump -U logto logto > /opt/backups/logto_$(date +\%Y\%m\%d).sql 2>&1

十、常见问题

登录页面显示错误

确保 ENDPOINT 环境变量与实际访问域名一致，包括协议（https）和端口。

回调地址不匹配

在应用配置中添加正确的 Redirect URI，确保与代码中使用的回调地址完全一致。

总结

Logto 以其精美的界面和完善的功能，成为开源身份认证平台中的优秀选择。在搬瓦工 VPS 上通过 Docker 可以轻松部署，并为你的所有应用提供统一的认证服务。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 折扣。相关平台：Casdoor 教程、Authentik 教程、Zitadel 教程。