跳到主要内容
版本：1.6.0

成员

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

AISIX Cloud 控制面支持两种成员加入方式：

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

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

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

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

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

邀请成员​

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

  1. 打开 Members，选择 Invite member。
  2. 输入成员邮箱并选择角色。
  3. 选择 Send invitation。

接下来的行为取决于部署是否配置了邮件：

  • 已配置邮件时，控制面会把邀请链接通过邮件发送给受邀人。邀请卡片会确认中继已接受这封邮件。如果邮件未能送达，卡片会显示原因，例如连接、TLS 或身份认证失败，或中继返回的拒绝信息。无论哪种情况，邀请都仍然有效。
  • 未配置邮件时，不会发送任何邮件。卡片会提示你自行把链接发给受邀人。

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

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

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

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

邀请有效期​

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

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

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

重新发送邀请​

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

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

邀请邮件数量限制​

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

在 SaaS 服务上注册​

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

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

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

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

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

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

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

On-Premises 控制面不验证邮箱地址，那里的账号都来自邀请。

重置忘记的密码​

部署配置了邮件时，有密码但忘记密码的成员可以在登录页重置密码：

  1. 在登录页选择 Forgot?。
  2. 输入账号的邮箱地址，选择 Send reset link。
  3. 打开邮件中的链接并设置新密码。新密码适用与注册时相同的密码规则。

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

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

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

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

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

启用登录或重置密码​

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

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

  • Can sign in（可以登录），后跟成员的登录方式：Password、SSO 或两者兼有。SSO 表示该成员已关联到组织已启用的 SSO 连接上的某个身份，这一关联在成员首次单点登录时建立。
  • Signs in with SSO（通过 SSO 登录）：组织的 SSO 连接已启用，而成员既没有密码、也尚未建立 SSO 关联。身份提供方会在成员首次单点登录时按其邮箱地址放行。
  • Password · SSO required（有密码 · 须使用 SSO）：连接强制单点登录时，只有密码的非 Owner 成员。仅凭密码无法进入组织，必须通过 SSO 登录。只有能读取 SSO 设置的组织 Owner 和 Admin 能看到这个标记，其他查看者看到的是 Can sign in (Password)。
  • Cannot sign in（无法登录）：组织没有启用 SSO 连接，而成员既没有密码、也没有 SSO 关联。

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

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

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

该链接：

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

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

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

对成员拥有写权限的人（默认为 admin 和 owner）都可以为 member 角色的成员签发链接。由于持有链接的人可以接管该账号，为其他角色签发链接需要具备可以邀请该角色的身份：只有 Owner 可以为 Owner 签发，为 Admin 或自定义角色成员签发则需要内置的 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}"

直接创建成员​

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

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

直接创建的成员：

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

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

在控制台中操作​

  1. 打开 Members，选择 Create user。
  2. 输入能够识别责任归属的 Name 和 Email。
  3. 选择 Create user。

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

使用 API​

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

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

# AISIX_CP 包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_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 角色。

等待加入的成员​

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

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

浏览和搜索成员​

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

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

使用 API 列出成员​

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

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

查询参数都是可选的：

  • q：对成员名称和邮箱执行不区分大小写的匹配。
  • 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 是组织中的 Owner 数量。在 On-Premises 控制面上，每个成员还带有 sign_in_methods，列出该成员可以使用的登录方式：成员有控制台密码时包含 password，成员已关联到组织已启用的单点登录连接上的身份时包含 sso。两者都没有时为空，直到设置密码链接为其设置了密码，或成员通过单点登录登录。

移除成员​

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

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

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

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

下一步​

继续阅读团队，了解如何按团队归因并实施共享控制；或继续阅读角色与自定义角色，了解如何控制成员权限。如果成员应由身份提供方管理，请使用 SCIM 目录同步；如果成员应通过身份提供方登录，请使用单点登录（SAML）。