跳到主要内容

用户迁移

Logto 支持将现有用户从其他平台手动迁移，本文将向你展示如何通过 Management API 导入现有用户，并介绍迁移前你需要考虑的事项。

用户 schema​

在开始之前，让我们先看一下 Logto 中的 用户 schema。你需要关注用户 schema 的三个部分：

  1. 基础数据：来自用户资料的基本信息，你可以将现有用户资料中的数据映射到这里。
  2. 自定义数据：用于存储额外的用户信息，你可以用它来存储无法匹配基础数据的字段。
  3. 社交身份：存储通过社交登录获取的用户信息。

你可以创建一个映射，将现有用户资料中的信息对应到 基础数据 和 自定义数据。对于社交登录，你需要额外的步骤来导入社交身份，请参考 关联社交身份到用户 的 API。

密码哈希​

Logto 使用 Argon2 对用户密码进行哈希，同时也支持 MD5、SHA1、SHA256 和 Bcrypt 等其他算法，方便迁移。这些算法被认为是不安全的，相应的密码哈希将在用户首次成功登录时迁移到 Argon2。

如果你使用了其他哈希算法或加盐方式，可以将 passwordAlgorithm 设置为 Legacy，这样你就可以使用 Node.js 支持的任意哈希算法。你可以在 Node.js crypto 文档 中找到支持的算法列表。在这种情况下，passwordDigest 应为包含哈希算法及其他算法参数的 JSON 字符串。

JSON 字符串的格式如下：

["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"]

你可以在参数中用 @ 作为实际密码值的占位符。

例如，如果你使用 SHA256 并加盐，可以按如下格式存储密码：

["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"]

这等价于如下代码：

const hash = crypto.createHash('sha256');
hash.update('salt123' + 'password123');
const expectedHashedValue = hash.digest('hex');

迁移步骤​

  1. 准备用户数据
    你应先从现有平台导出用户数据，然后将用户信息映射到 Logto 用户 schema。我们建议你将映射后的数据整理为 JSON 格式。以下是用户数据的示例：

    [
      {
        "username": "user1",
        "passwordDigest": "password-encrypted",
        "passwordAlgorithm": "SHA256"
      },
      {
        "username": "user2",
        "passwordDigest": "password-encrypted",
        "passwordAlgorithm": "SHA256"
      }
    ]

  2. 创建 Logto 租户
    你需要在 Logto 中设置一个租户。你可以选择 Logto Cloud 或 Logto OSS。如果还未完成此步骤，请参考 设置 Logto cloud 指南。

  3. 配置 Management API 连接
    我们将使用 Management API 导入用户数据，你可以参考 Management API 了解如何在开发环境中配置连接。

  4. 导入用户数据
    建议你编写脚本逐个导入用户数据，我们将调用 create user API 导入用户数据。以下是脚本示例：

    const users = require('./users.json');

    const importUsers = async () => {
      for (const user of users) {
        try {
          await fetch('https://[tenant_id].logto.app/api/users', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              Authorization: 'Bearer [your-access-token]',
            },
            body: JSON.stringify(user),
          });
          // 为避免触发限流，适当休眠
          await new Promise((resolve) => setTimeout(resolve, 200));
        } catch (error) {
          console.error(`Failed to import user ${user.username}: ${error.message}`);
        }
      }
    };

    importUsers();

请注意该 API 接口有速率限制，你应在每次请求之间添加休眠以避免触发限流。详情请查看我们的 速率限制 页面。

如果你有大量用户数据（10 万以上），可以联系我们以提升速率限制。

将现有用户数据库迁移到 Logto 的通用指南