跳到主要内容
版本：Dev

成员

在 AISIX Enterprise 或 AISIX Cloud 中，成员属于一个组织，代表负责控制面管理、API Key、用量和限制的人员或服务所有者。

共享控制面支持两种成员加入方式，适用产品有所不同：

  • 当成员需要登录控制台时，邀请该成员。
  • 当你需要一个不登录控制台的 API Key 所有者时，直接创建成员。这种方式仅在 AISIX Enterprise 中可用。

两种方式都会创建组织成员。区别在于该成员是否会收到邀请，并是否可以使用控制台。管理员之后可以为直接创建的成员启用登录。

在 AISIX Cloud 上，成员通过邀请、单点登录或 SCIM 目录同步加入组织，不能直接创建成员。

AISIX Enterprise 控制面不开放自行注册：除非组织的单点登录会在登录时自动添加新成员，否则邀请是新用户创建账号的唯一途径。

配置单点登录后，成员也可以通过身份提供方登录，而不必使用密码；受邀者也可以通过 SSO 登录来接受邀请。

邀请成员​

当某个人需要控制台访问权限来管理资源、查看用量或管理组织时，请使用邀请方式。

  1. 打开 成员，选择 邀请成员。
  2. 输入成员邮箱并选择角色。
  3. 选择 发送邀请。

邮件投递方式因产品而异。AISIX Cloud 使用由 API7 运营的邮件中继。AISIX Enterprise 需要由运维人员配置 SMTP 中继；未配置时，控制台会生成邀请链接，供管理员自行分发。

邮件投递可用时，控制面会把邀请链接发送给受邀人。邀请卡片会确认中继已接受邮件。若投递失败，卡片会显示连接、TLS、身份认证或中继拒绝等原因；邀请本身仍然有效。

两种情况下，卡片都只显示一次邀请链接，你可以复制它并通过可信渠道转交。任何持有该链接的人都能打开这份邀请，因此请像对待凭据一样对待它。控制面只存储链接的哈希值，离开页面后无法再次显示；如需新链接，请重新发送邀请。

打开链接后，受邀人会看到是谁邀请的、将要加入哪个组织、以及获得什么角色。尚未拥有账号的受邀人可以直接从该页面注册——邮箱已自动填入且不可修改——注册完成后会回到邀请页面。在邀请流程中，账号只能通过邀请链接创建：注册请求会携带邀请 Token，当邀请已不处于待接受状态、已过期或发给了其他地址时，控制面会拒绝该请求。不经邀请直接打开该邀请的注册页面时，页面会提示注册已关闭。加入组织始终需要显式点击 接受邀请：仅打开链接不会改变成员关系，因此已登录其他组织的用户点开链接也不会被切换过去。

邀请与你填写的邮箱绑定。只有使用该邮箱的账号才能接受邀请；其他账号打开链接时，会看到该邀请是发给哪个邮箱的，并可以切换到该账号登录。在受邀人接受前，该邀请会停留在 待处理邀请 标签页。

已经是组织成员的邮箱无法再被邀请。接受邀请不会修改已有成员的角色，这样的邀请不会产生任何效果——请直接在成员列表中修改角色。邀请也无法恢复已被 SCIM 目录同步停用的成员：兑换邀请会返回 403 和错误码 MEMBER_DEACTIVATED。

邀请有效期​

邀请在发出 7 天后过期。在此之前，它会停留在 待处理邀请 标签页，你可以在这里吊销它，使链接立即失效。

该标签页默认只列出仍然有效的邀请。勾选 显示历史邀请（已接受、已吊销、已过期） 后，还会显示已接受、已吊销和已过期的邀请。如果需要清理记录，已过期的邀请也可以在这里吊销。

已过期的邀请不会继续占用该邮箱：再次邀请同一个人会签发新的链接，并作废那条已过期的邀请，后者仍会显示在 显示历史邀请（已接受、已吊销、已过期） 中。只有仍然处于待接受且未过期的邀请，才会阻止对同一邮箱再次发起邀请。

重新发送邀请​

在待接受的邀请上，或在 显示历史邀请（已接受、已吊销、已过期） 中列出的已过期邀请上，选择 重新发送 即可重新签发该邀请。重新发送会生成新链接，之前签发的链接随即失效，邀请的有效期从重新发送时起重新计算 7 天。已配置邮件时，新链接会再次通过邮件发给受邀人；无论是否配置邮件，卡片都会显示新链接。

你只能重新发送你本可以用同一角色创建的邀请。如果该邮箱在此期间已通过其他方式加入组织，则无法重新发送；cp-api 会返回 409 和错误码 ALREADY_MEMBER。

邀请邮件数量限制​

已配置邮件时，每个账号在每个滚动小时内可发送的邀请邮件数量有限，默认为 50 封。该限制统计账号所属的所有组织，创建邀请和重新发送邀请都会计数。超出限制时，邀请会被拒绝并返回 429，不会创建或重新签发任何邀请。AISIX Enterprise 运维人员可以通过 api.smtp.invitationLimitPerHour 设置该限制，参见邀请邮件数量限制。

在 AISIX Cloud 上注册​

在 AISIX Cloud 上，任何人都可以在注册页面创建账号，但必须先确认邮箱地址，账号才能使用：

  1. 填写名称、邮箱地址和密码完成注册。页面随后提示查收邮件，此时还不会建立会话。
  2. 打开邮件中的验证链接。它会打开登录页面，并预先填好邮箱地址。
  3. 使用注册时设置的密码登录。这会完成邮箱验证并登录。

验证链接 24 小时内有效，只能使用一次。它需要用账号当前的密码登录才能完成，因此即使链接落到别人手里，没有密码也无法使用。仅打开链接不会改变任何状态。

在邮箱地址验证之前，使用密码登录会被拒绝，返回 403，错误码为 EMAIL_NOT_VERIFIED，登录页面会提供重新发送验证邮件的入口。无效、已过期、已使用或已被更新的链接取代的链接会被拒绝，错误码为 EMAIL_VERIFICATION_LINK_INVALID。密码错误时，无论邮箱是否已验证，都只返回 INVALID_EMAIL_OR_PASSWORD，因此登录尝试不会暴露某个地址是否已验证。

需要新链接时，在查收邮件页面或登录页面选择 重新发送验证邮件。每个新链接都会使之前的链接失效；但如果距离上一个链接不足一分钟，新请求会被忽略，之前的链接仍然有效。无论该地址是否有待验证的账号，页面显示的提示都相同，因此无法借此探测哪些邮箱已注册。

用一个账号仍未验证的地址再次注册，会替换之前的注册：新的名称和密码生效，该账号的会话全部结束，并发送新的验证链接。账号已验证的地址，或属于没有密码的账号（例如由 SSO 或 SCIM 创建的账号）的地址，不能再次注册。

重置忘记的密码同样会验证邮箱地址，因为重置链接是从该邮箱中打开的。

AISIX Enterprise 不验证邮箱地址，那里的账号都来自邀请。

重置忘记的密码​

有密码但忘记密码的成员可以在登录页重置密码。AISIX Cloud 使用由 API7 运营的邮件中继发送邮件；AISIX Enterprise 需要由运维人员配置 SMTP 中继：

  1. 在登录页选择 忘记密码？。
  2. 输入账号的邮箱地址，选择 发送重置链接。
  3. 打开邮件中的链接并设置新密码。新密码适用与注册时相同的密码规则。

无论该邮箱是否属于某个账号，页面显示的提示都相同，因此无法借此探测哪些邮箱已注册。重置链接：

  • 有效期为一小时；
  • 只能使用一次；
  • 会替换该账号之前的所有重置链接；但如果距离上一次请求不足一分钟，新请求会被忽略，之前的链接仍然有效。

重置密码后，该账号在所有设备上的所有会话都会退出登录。请使用新密码重新登录。在 AISIX Cloud 上，重置密码还会把邮箱地址标记为已验证。

未配置邮件时，忘记密码页面会提示用户联系管理员，不提供表单。

没有密码的账号不会收到重置邮件，包括直接创建的成员、通过 SCIM 创建的成员、从脱敏备份恢复的账号，以及在 Google 和 GitHub 登录被移除之前只使用这两种方式登录的用户。管理员可以改为为他们启用登录。

启用登录或重置密码​

在 AISIX Enterprise 控制面上，管理员可以向成员提供一个一次性链接，由成员在该链接上自行设置密码。管理员既看不到也无法指定这个密码。

成员 列表会结合组织的单点登录连接，显示每个成员的登录方式：

  • 可登录，括号中列出成员的登录方式：密码、SSO 或两者兼有。SSO 表示该成员已关联到组织已启用的 SSO 连接上的某个身份，这一关联在成员首次单点登录时建立。
  • 通过 SSO 登录：组织的 SSO 连接已启用，而成员既没有密码、也尚未建立 SSO 关联。身份提供方会在成员首次单点登录时按其邮箱地址放行。
  • 密码 · 需要 SSO：连接强制单点登录时，只有密码的非所有者成员。仅凭密码无法进入组织，必须通过 SSO 登录。只有能读取 SSO 设置的组织所有者和管理员能看到这个标记，其他查看者看到的是 可登录（密码）。
  • 不可登录：组织没有启用 SSO 连接，而成员既没有密码、也没有 SSO 关联。

在 AISIX Enterprise 和 AISIX Cloud 中，每一行还会显示 已开启双因素认证 或 未开启双因素认证，表示该成员的账号是否开启了双因素认证。

已停用的成员只显示 已停用，不显示登录标记，也没有登录相关操作。对于其他成员，行操作取决于成员是否有密码：

  • 重置密码：用于已有密码的成员。在成员设置新密码之前，当前密码仍然有效。
  • 设置密码：用于没有密码、但可以通过 SSO 登录的成员。设置密码后成员多了一种登录方式，但在强制单点登录时，仅凭密码无法进入组织。
  • 开通登录：用于无法以任何方式登录的成员，例如直接创建的成员、通过 SCIM 创建的成员，或从脱敏备份恢复的成员。

选择其中任一操作后，页面会显示一张包含该链接的卡片，你可以复制链接。配置了邮件时，控制面还会以组织的语言（组织未设置时为部署默认语言）把链接发送到成员邮箱，卡片会显示发送到了哪里，或邮件未送达的原因。未配置邮件时不会发送任何内容，请通过可信渠道自行把链接转交给成员。卡片只显示一次链接。

该链接：

  • 有效期为 72 小时；
  • 只能使用一次；
  • 在你为同一成员签发更新的链接、该成员通过 忘记密码？ 申请重置、你修改该成员的角色或移除该成员，或 SCIM 目录同步停用或删除该成员时失效；
  • 只有当持有人仍是签发组织的有效成员时才能使用，否则会被当作无效链接拒绝。

无法为已停用的成员签发链接：请求返回 400 和错误码 INVALID_REQUEST，也不会发送邮件。

成员设置密码后，该账号的所有会话都会结束，成员使用新密码登录。未使用而过期的链接不会产生任何变化。无论哪种情况，成员的团队、角色和 API Key 都不受影响。

对成员拥有写权限的人（默认为 admin 和 owner）都可以为 member 角色的成员签发链接。由于持有链接的人可以接管该账号，为其他角色签发链接需要具备可以邀请该角色的身份：只有所有者可以为所有者签发，为管理员或自定义角色成员签发则需要内置的 admin 或 owner。

如需通过自动化签发链接，请使用具有 write 权限范围的 Admin Token 调用 POST /members/{user_id}/set_password_link，其中 user_id 取自成员列表，AISIX_CP 和 AISIX_TOKEN 的取值见使用 API。响应中包含 link、其 expires_at、action（enable_sign_in 或 reset_password）以及 email_delivery：

export USER_ID="MEMBER_USER_ID"

curl -X POST "${AISIX_CP}/members/${USER_ID}/set_password_link" \
  -H "Authorization: Bearer ${AISIX_TOKEN}"

直接创建成员​

在 AISIX Enterprise 控制面上，当服务、应用或开发者需要拥有 API Key 但不需要控制台访问权限时，可以直接创建成员。

AISIX Cloud 不提供直接创建成员：成员 页面没有 创建用户 按钮，POST /members 返回 404。AISIX Cloud 上的账号由所有组织共用，直接创建的成员会持有一个其主人从未确认过的地址的账号，还会阻止此人自行注册。请改为邀请此人，或通过 SCIM 目录同步预配。

直接创建的成员：

  • 会立即激活，不需要邀请链接或确认步骤。
  • 可以加入团队并分配 API Key。
  • 可以受限流和预算治理。
  • 没有密码，因此在管理员启用登录之前无法登录控制台。

该成员仍然有名称和邮箱。请使用能够识别责任人、服务或应用所有者的值，以便正确归因用量和限制。

在控制台中操作​

  1. 打开 成员，选择 创建用户。
  2. 输入能够识别责任归属的 名称 和 邮箱。
  3. 选择 创建用户。

成员会立即出现在列表中。随后你可以将该成员加入团队，并从承载其流量的环境中签发 API Key。

使用 API​

当需要通过自动化供应成员时，请使用 API。

使用具有 write 权限范围的组织 Admin Token认证。Admin Token 的作用域绑定到一个组织，因此请求不需要额外的组织请求头。

# AISIX_CP 包含 /api，且不含尾部斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

创建成员：

curl -X POST "${AISIX_CP}/members" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Responsible Person",
    "email": "svc-payments@example.com"
  }'

成功调用会返回 201 Created 和新成员：

{
  "member": {
    "id": "8f3b2a1c-9d4e-4f6a-b7c8-1e2d3f4a5b6c",
    "user_id": "2c7d6e5f-4a3b-4c2d-8e1f-9a0b1c2d3e4f",
    "email": "svc-payments@example.com",
    "display_name": "Responsible Person",
    "role": "member",
    "sign_in_methods": []
  }
}

邮箱地址必须有效，并且在部署内唯一。对于应用所有者，可以使用类似 svc-payments@example.com 的合成地址。复用已有邮箱会返回 409 Conflict。直接创建的成员始终使用 member 角色。

将调用方 API Key 归属到该成员时，请把成员关系的 id 填入密钥的 user_id。成员响应中还包含账号的 user_id，它是供成员路由和团队成员关系使用的另一个标识符。不要用账号 ID 代替调用方密钥归属所需的成员关系 ID。

等待加入的成员​

在 AISIX Cloud 上，SCIM 目录同步把地址位于组织已验证域名以外的预配用户记录为等待加入的成员，并向该地址发送邀请。成员 页面在成员列表下方的 待加入 区块中列出这些人，显示其邮箱地址、角色、目录 ID 以及是否处于激活状态，邀请则出现在 待处理邀请 标签页中。没有人等待加入时，该区块不显示。

本人接受邀请，或以目录中对应的身份关联组织的单点登录后，等待加入的成员即成为正式成员。请在身份提供方中管理这些成员。参见等待加入的成员。

浏览和搜索成员​

成员 列表支持搜索和分页，便于管理大型组织。

  • 使用搜索框按名称或邮箱过滤。搜索在服务端执行，因此会匹配所有页面，而不只匹配当前页面中的行。
  • 使用列表下方控件调整页面大小或在页面之间切换。

使用 API 列出成员​

复用上面导出的 AISIX_CP 和 AISIX_TOKEN。此请求使用具有 read 权限范围的 Token 即可。

curl "${AISIX_CP}/members?page=1&page_size=20&q=payments" \
  -H "Authorization: Bearer ${AISIX_TOKEN}"

查询参数都是可选的：

  • q：对成员名称和邮箱执行不区分大小写的匹配。
  • team_id：只返回该团队的成员。不属于本组织的团队没有成员，结果为空。
  • exclude_team_id：只返回不在该团队的成员。不属于本组织的团队不排除任何人。
  • status：只返回该状态的成员，取值为 active 或 deactivated。
  • page：从 1 开始的页码。需要同时设置 page_size；单独设置 page 会返回 400。
  • page_size：页面大小，最大为 200。如果同时省略 page 和 page_size，则禁用分页，并在单个响应中返回所有成员。

这些筛选条件可以相互组合，也可以和分页组合。不带任何参数的请求仍返回所有成员。

响应会在分页结构中包装成员列表：

{
  "data": [],
  "total": 128,
  "page": 1,
  "page_size": 20,
  "owner_count": 2
}

total 是所有页面中匹配过滤条件的成员数量，owner_count 是组织中的所有者数量。在 AISIX Enterprise 控制面上，每个成员还带有 sign_in_methods，列出该成员可以使用的登录方式：成员有控制台密码时包含 password，成员已关联到组织已启用的单点登录连接上的身份时包含 sso。两者都没有时为空，直到设置密码链接为其设置了密码，或成员通过单点登录登录。在两种产品中，每个成员都带有 two_factor_enabled，成员的账号开启了双因素认证时为 true。

按 ID 查询成员​

POST /members/lookup 按成员资格 id、user_id 或两者查询成员，这样显示成员名称的页面无需获取完整列表：

curl -sS -X POST "${AISIX_CP}/members/lookup" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["51ce4a7e-b5c5-4b18-8936-9f235765357f"], "user_ids": []}'

一次请求的两个列表合计最多 500 个 ID，超过返回 400。响应的 data 数组中每个成员只出现一次，形状与列表项相同，已停用的成员也会返回并带状态。响应中没有的 ID 表示该成员不在本组织：已被移除，或从未属于本组织。此请求只读取数据，因此虽然是 POST，使用具有 read 权限范围的 Token 即可。

获取自己的成员信息​

GET /members/me 以 {"member": {}} 的形式返回调用方在组织中的成员信息，其中的对象与列表项形状相同。Admin Token 返回创建它的成员。此请求的权限与 GET /members 相同。

为成员设置标签​

在成员行中选择 标签，即可设置该成员的成本归属标签。通过该成员拥有的调用方 API Key 发出的请求，凡 Key 和其团队都没有设置、JWT Claim 也没有提供的标签，都取成员的值。admin 可以通过 PATCH /members/{user_id} 的 tags 修改成员标签，直接创建成员时 POST /members 也接受 tags。由 SCIM 目录同步管理的成员，其标签仍然可以编辑，因为目录同步不同步标签。

移除成员​

在成员行上选择移除操作。移除成员会一并撤销其组织成员资格、环境级角色绑定，以及在所有团队中的位置。

同时会禁用该成员拥有的所有 API Key，并且该变更会传播到网关，因此这些凭证会在网关本身停止工作，而不只是无法在控制台中使用。这与身份提供方通过 SCIM 触发的预配撤销是同一套行为——从控制台移除和从目录移除，现在会让组织处于相同的状态。

这些 Key 是被禁用而不是被删除，因此其用量历史仍可用于报表。运维此前手工禁用的 Key 会保留原有的禁用来源。如果这个人离开后其凭证仍需继续承载流量（例如以其账号创建的应用 Key），请在移除成员之前重新绑定或重建它们。

如果该成员的账号没有密码，且不属于其他任何组织，移除成员时也会删除该账号，使其邮箱地址可以再次使用。这包括直接创建的成员、通过 SCIM 预配的成员，以及首次登录时由单点登录创建的成员。有密码的账号，或仍是其他组织成员的账号，会保留。删除组织时，每个成员的账号都按同样的规则处理。

下一步​

继续阅读团队，了解如何按团队归因并实施共享控制；或继续阅读角色与自定义角色，了解如何控制成员权限。如果成员应由身份提供方管理，请使用 SCIM 目录同步；如果成员应通过身份提供方登录，请使用单点登录（SAML）。如需设置密码策略或要求开启双因素认证，请参见密码策略与双因素认证。