连接器 (Connector) 数据结构
简介
什么是连接器 (Connector)?
连接器 (Connectors) 在 Logto 中扮演着关键角色。借助它们，Logto 能够让终端用户使用无密码注册或登录，以及使用社交账号登录的能力。随着网站和应用程序的日益普及，无密码和社交登录让用户无需管理大量账号和密码。
如果你想配置现有连接器，请参考我们的 连接器指南。如果你找不到想要配置的连接器，可以按照 开发你的连接器 中的指南自行开发。
组成部分
连接器数据中包含许多属性。
为了让数据加载和更新更高效，我们将连接器数据中经常变动的部分存储到数据库 (DB)，其余部分本地存储。
- 本地存储，也称为 ConnectorMetadata，是一个包含固定属性（如 logo、连接器类型等）的对象。(:face_with_monocle: 不理解这些属性？别担心，后面会有详细解释！)
- 远程存储 存储在数据库中，因为这些数据变动相对频繁。
连接器的本地存储：ConnectorMetadata
id
id 是一个 唯一 的字符串类型键，用于在 Logto 中标识一个连接器。
它由每个连接器的开发者分配，并会上传到数据库。
target（身份提供商名称）
target 是一个小写字符串，用于区分社交连接器的社交身份来源。
Logto 用户可以将此变量理解为“身份提供商名称 (Identity provider name)”。
例如，如果你用 google 账号登录 Logto，你的 target 应该是 google。target 的值可以是任意非空字符串，但我们建议你保持简洁，因为它无法更改。我们不允许存在多个具有相同 target 和平台的连接器。另一方面，你可以为不同平台配置相同 target 的社交连接器。例如，如果用户想在手机上通过 WeChat 登录，根据 WeChat 的 TOU 需要一个原生 WeChat 应用；同时，为了支持网页应用登录，还需要一个 web WeChat 应用。这两个 WeChat 应用共享同一个身份提供商，应该有相同的 target。
由于 target 是一个复杂的概念，我们总结了不同用例和建议：
| 示例 | 场景 | 结果 | 推荐？ | |
|---|---|---|---|---|
| 不同 IdP 和不同 target | 1. GitHub 连接器 (target: github) 2. Google 连接器 (target: google) | 一个支持 GitHub 和 Google 账号登录的应用。 | 最常见的用例。 | ✅ |
| 不同 IdP 但相同 target | 1. GitHub 连接器 (target: github) 2. Google 连接器 (target: github) | N/A | 用户可能会用另一个用户的 GitHub 账号登录到 Logto 账号。 | ❌ |
| 相同 IdP 但不同 target | 1. GitHub 连接器 (target: github) 2. OAuth GitHub 连接器 (target: github_oauth) | GitHub 连接器用于应用 A，OAuth GitHub 连接器专为应用 B 创建。 | 使用这两个不同连接器登录 Logto 会始终创建不同的 Logto 账号——即使用户用的是同一个 GitHub 账号。 | 只有在你需要拆分用户池时才需要用到这种方式。但通常建议为此场景创建两个独立租户。 |
| 相同 IdP 和相同 target | 1. GitHub 连接器 (target: github) 2. OAuth GitHub 连接器 (target: github) | N/A | 使用这两个连接器中的任意一个都能得到完全相同的结果。 | 创建两个本质上做同一件事的连接器会让终端用户感到困惑，也没有太大意义。最好只用一个适合你具体场景的连接器。 |
type
type 属性记录连接器的类型。
我们根据功能将连接器分为三种类型：
- Social：可在终端用户授权下从任意第三方社交媒体获取用户信息的连接器。
- SMS：让终端用户能在手机上接收短信的连接器。
- Email：可帮助向终端用户发送邮件的连接器。
platform
platform 用于标识连接器是为哪个平台构建的。
platform 应为 null 或以下字符串值之一：
- Native：仅适用于原生移动应用的连接器。
- Web：仅适用于桌面网页应用的连接器。
- Universal：可同时用于移动网页和桌面网页应用的连接器。
email 连接器 和 SMS 连接器 的 platform 应始终为 null。
只有 社交连接器 可以有非 NULL 的 platform 值。
name
name 是一个对象，其键为 i18n 国家代码，值为连接器的显示名称。
description
description 也是一个对象，其键为 i18n 国家代码，值为连接器的简要描述。
为了支持客户端的 i18n 显示，我们将 name（以及 description）属性存储为一个映射，使用国家代码作为键，本地字符的名称（或描述）作为值。
logo
logo 是连接器 logo 的 URL 或相对路径。
logoDark
logoDark 是连接器暗色模式 logo 的 可为空 URL 或相对路径。
logo 是必需的，logoDark 是可选的。
我们在浅色模式下显示 logo，在暗色模式下显示 logoDark（如果存在）。否则暗色模式下也会回退显示 logo。
isStandard
isStandard 是一个可选的布尔属性，用于标识社交连接器是否为“标准”连接器。你可以通过其为真 (isStandard) 的属性来识别“标准”连接器。
Logto 只支持“标准”社交连接器。也就是说，Logto 的所有 Email 或 SMS 连接器都不是“标准”连接器。
Logto 将基于开放和标准协议（如 OAuth、OIDC、SAML 等）构建的连接器称为“标准”连接器。Logto 用户可以基于此上下文在每个标准连接器上构建多个实例。例如，假设 Logto 已经提供了一个 OAuth 标准连接器，用户可以基于 Logto OAuth 标准连接器构建 “OAuth GitHub 连接器”、“OAuth Google 连接器” 和 “OAuth Facebook 连接器” 实例。
如果你熟悉 Logto 的连接器设计，最多只能同时存在一个 Email 或 SMS 连接器，这意味着目前阶段 Logto 不需要“标准” Email 或 SMS 连接器。
readme
readme 是连接器 README markdown 文件的相对路径，其内容会在连接器配置过程中显示在“管理控制台”中。
configTemplate
configTemplate 是连接器配置示例的相对路径。
连接器的远程存储：Connector DB {#connectors-remote-storage-connector-db}
id
id 作为连接器数据库的主键，是一个随机生成的字符串类型键，用于在数据库中标识连接器。
connectorId
connectorId 是一个字符串类型键，是 Connector DB 和 ConnectorMetadata 对齐的唯一桥梁。对于每一对匹配的连接器数据库数据和连接器代码模块，connectorId 总等于代码模块的 metadata.id。
metadata
metadata 是 ConnectorMetadata 的子集，包含可配置属性，如 logo、logoDark、target 和 name。
syncProfile
syncProfile 是一个布尔值，用于决定用户资料的更新方案，默认为 FALSE。
如果 syncProfile 为 FALSE，Logto 用户的基本信息（包括姓名和头像）只会在用户首次通过该连接器注册 Logto 时更新。否则，每次用户通过该连接器登录 Logto 时，Logto 账号资料都会被更新。
config
config 可以是任意非空对象。
它是连接器存储其配置信息的地方。每个连接器在 config 中有不同的属性，并且在保存到数据库前必须是有效的（不同连接器对“有效”有不同标准）。只有通过有效性检查的 config 才能更新到数据库，否则会抛出错误。
开发者在开发自定义连接器时需要实现 config 校验，详见 开发你的连接器。
想看看 config 示例？请前往 连接器 或各连接器的设置页面。
在当前 Logto 版本中，同一时间只能存在一个 Email/SMS 连接器，所有其他同类型连接器会被自动删除。
唯一可用的 Email 或 SMS 连接器的规则不适用于 社交连接器。
换句话说，你可以添加多个 社交连接器。
createdAt
createdAt 是一个自动生成的时间戳字符串，用于记录连接器在数据库中创建的时间。