跳到正文
Ankole

主体与权限组

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/principal-and-groups/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

Ankole 将人员、Agent 与系统服务统一建模为主体(Principal):权限组负责将多个主体归集管理,授权规则则决定某个主体或权限组能够操作哪些资源。

配置身份源提供商(IdP)后,系统会自动同步企业员工与组织架构,省去在 Ankole 中手动维护部门成员的繁琐工作。此外,人员还可以通过无密码邮箱验证码(SiteCredential)、Pod 邀请链接(/join/:token)或管理员预创建的方式加入实例。

身份源如何同步组织架构

在身份源提供商中开启通讯录同步后,Ankole 会将外部目录映射为两类数据:

  • 人员主体:对应企业员工,姓名、头像等个人资料会随外部目录自动更新;
  • 目录权限组:对应部门、用户组等组织单元,成员归属关系也会一并同步。

若外部目录存在上下级部门层级,加入子部门的员工会自动成为所有上级部门组的成员。因此,只需向某个上级部门授予权限,即可覆盖其下辖各子部门的全部员工。

保存已启用的身份源配置时,若已开启目录同步且适配器支持全量同步,Ankole 会将首次同步任务加入队列。周期性全量同步的入队尝试间隔默认为 15 分钟,实际执行时间取决于 Oban 队列。支持增量同步的身份源还可在全量同步之间推送人员与组织变动。

如需立即刷新组织数据,可打开 Console → 身份源提供商,进入目标提供商页面并选择“执行完整同步”。同步结束后,前往 访问控制 → 主体 与 访问控制 → 权限组 核对结果。

目录组的唯一数据源仍是外部企业通讯录——调整部门结构或成员归属时请在原身份系统中操作,不要尝试在 Ankole 中手动增删目录组成员。

如果同步结果缺失部分人员或部门,请先检查外部应用在身份源后台的通讯录读取权限与可见范围,修正后重新执行完整同步。注意,即使已开通通讯录接口权限,应用在企业后台的可见范围仍可能被限制在部分部门内。

首次对接身份源的操作步骤见 快速开始。

查看主体

每个主体都归属单个租户,并以 (tenant_id, uid) 作为唯一标识,其中 uid 是租户内唯一、语义清晰的小写标识名(例如 alex.smith 或 research-analyst)。打开 Console → 访问控制 → 主体,列表会展示每个主体的名称、UID、类型、成员身份与当前状态:

  • 人员:可通过身份源登录或目录同步、无密码邮箱验证码(SiteCredential)、Pod 邀请链接(/join/:token)或管理员预创建生成。每个人员主体在租户内都带有 membership 属性,取值为 member(内部成员)或 guest(外部访客)。内部 member 会自动归入内置动态组 all_humans;外部 guest 则必须凭借显式的 Pod 页面共享或 Agent 授权才能访问对应资源,且不可加入内置管理员组(siteadmin 或 pod_admin)、不可使用个人空间(Private space),也不会获得 Brain 的 world 可见范围(外部访客的准入与 Pod 访问受 pod.allow_external_guests 控制)。
  • Agent:分为两类子类型——**个人助理(personal_assistant)**按 1:1 比例为每位启用态内部人类成员首次使用时自动开通(初始 UID 为 <owner_uid>_assistant),在云盘与 Pod 协作资源上直接投射主人的权限;**AI 同事(ai_colleague)**则由管理员为共享专业岗位创建,凭借 Agent 自身的主体权限运行。
  • 系统:来自 Ankole 封闭维护的内部服务主体注册表——包含 system(承载内部运行时操作)与 ankole_brain(承载企业大脑事实抽取、Dreaming、技能教训复审、URL Source 抓取与召回重排)。系统主体不支持交互式登录、不可重命名,也不运行 Worker 实例。

点击主体名称或行末的“查看详情”,即可查看该主体所属的权限组与直接授权。主体的 type 创建后不可更改;管理员则可对人员主体(POST /api/v2/principals/:uid/rename)及已停用且已移除运行中/暂停中 Worker 实例的 Agent 主体(POST /api/v2/agents/:uid/rename)执行留痕的租户内 UID 重命名,在同一事务内原子更新权限授权、组成员关系、Brain 路径与提及引用以及多维表关联记录。排查权限问题时,请同时核查权限组与直接授权——即使某个主体名下没有直接授权,也可能通过所属权限组继承了相应权限。

选择合适的权限组

不同类型权限组的来源与成员维护方式各有侧重:

权限组类型 适用场景 成员维护方
目录组 企业通讯录中已有的部门或用户组 身份源提供商自动同步
IM 群组 权限需跟随聊天群成员动态变化 聊天渠道自动同步
信号源用户组 权限需覆盖“曾通过某条路由规则发起对话的所有人” Signals 准入机制自动维护
Provider 全员组 权限需覆盖由特定身份源导入的全部人员(<provider>:members:all) 身份源提供商同步
静态组 Ankole 内部跨部门临时组队,或成员较少且变动不频繁 管理员手动维护
动态组 可依据主体自身属性自动判定归属 Ankole 按 CEL 表达式实时计算

目录组与 IM 群组会自动出现在权限组列表中,成员关系由外部系统单向同步,在 Console 中为只读状态;静态组与动态组则由管理员在 Ankole 内自主创建和维护。此外,每个租户默认内置两个权限组:静态组 pod_admin(授予该 Pod 内的 tenant_console:** 管理权限)与动态组 all_humans(匹配所有启用态的内部人类成员);特权站点租户还额外内置静态组 siteadmin(同时授予 site_console:** 与 tenant_console:** 权限)。只有状态为 active 且成员身份为 member 的人类主体,才允许加入 siteadmin 或 pod_admin。

只要企业现有的组织架构能够准确表达目标团队,建议优先直接复用目录组。这样当员工转岗或离职时,访问权限便会随下一次增量或全量目录同步自动收回或调整。

创建静态组

  1. 打开 Console → 访问控制 → 权限组,点击“新增组”。
  2. 填写稳定的小写英文标识名、显示名称及用途说明。
  3. 将类型设为“静态”并保存。
  4. 进入新建的权限组,在“成员”区域点击“添加成员”。

成员加入静态组后会立即获得该组名下的全部授权,移出后相关权限也随即失效。

创建动态组

动态组不存储固定成员名单,也不支持手动增删成员;每次检查权限时,Ankole 都会运行配置的 CEL 表达式,实时判定当前主体是否属于该组。

新建权限组时将类型选为“动态”,并在“成员条件”中编写返回布尔值(true 或 false)的 CEL 表达式,通过 principal 对象读取待校验主体的属性。

动态组表达式可引用以下字段:

字段 含义 示例或取值
principal.uid 租户内唯一的主体 UID alex.smith 或 research-analyst
principal.type 主体类型 human、agent、system
principal.membership 人员在租户内的成员身份 human 为 member 或 guest;agent 与 system 为 null
principal.status 主体启用状态 active、disabled
principal.displayName 显示名称(可能为空) 张三
principal.avatarURL 头像链接(可能为空) 身份源返回的 URL

例如,匹配所有已启用的内部成员(与内置 all_humans 组的判定规则一致):

principal.type == "human" && principal.membership == "member" && principal.status == "active"

若省略 principal.membership == "member",表达式还会一并匹配已启用的外部访客(guest)。

再如,匹配所有已启用的 Agent:

principal.type == "agent" && principal.status == "active"

输入表达式时,Console 会实时预览当前匹配到的所有启用态主体。保存前请仔细核对匹配人数与名单,防止因条件过宽而误授权限。

权限组创建保存后,其标识名与组类型即不可更改。自定义动态组后续仍可调整成员条件,每次保存前同样应核对实时预览;内置动态组的成员条件由系统固化维护,在 Console 中只读。

注意,CEL 表达式无法读取员工邮箱、职级或所属部门。如需按部门分配权限,请直接使用身份源同步过来的目录组,切勿尝试用显示名称字符串去猜测组织归属。

添加授权

打开目标权限组或主体详情页,在“权限授权”区域点击“新增授权”,填写以下各项:

  • 资源模式:指定该权限作用的资源范围;
  • 动作:允许执行的具体操作,如 read 或 update;
  • 条件:可选的 CEL 附加限制,留空表示无额外限制;
  • 描述:注明授予该项权限的业务原因,方便后续审计。

日常管理中应优先将权限授予权限组,仅在个别主体确需特殊豁免时才配置直接授权。修改或删除任一授权规则,都会立即对其归属主体或组内全体成员生效。

授权规则创建后,其归属所有者只读不可改。如需将权限迁移给其他主体或权限组,请先在新所有者名下新建相同授权,验证访问无误后再删除旧规则。

按组织架构授权

假设需要让“研究部门”全体员工都能查看某个 Agent:

  1. 确认身份源已成功同步出“研究部门”目录组及其成员。
  2. 在权限组列表中打开该目录组。
  3. 新增一条针对目标 Agent 的 read 授权规则。
  4. 使用该部门某位普通员工的账号登录验证,确认既能正常打开目标 Agent,又无法越权访问其他未授权资源。

后续如有人员调动,只需在企业通讯录中更新研究部门成员即可;Ankole 完成下一轮目录同步后会自动刷新组成员,挂载在该组上的授权规则无需改动。

配置权限后切勿仅凭 Console 提示“保存成功”就结束操作——务必使用真实成员账号实测一遍,确认资源范围、允许动作及成员同步链路均符合预期。

暂停或离职处理人员账户

员工暂时停工或正式离职时,应停用其账户而非尝试删除主体。在主体和权限组页面打开对应人员,在账户访问区域填写原因,并选择相应的处置方式(disposition):

  • 暂停(suspended):在该人员名下任意设备下次发起请求时立即拒绝其 Console 会话、OAuth 会话与访问令牌,并阻止启动新的工作任务;但保留其个人 SiteCredential、邮箱别名以及 Pod 联系邮箱与手机号绑定。日后恢复账户时可无缝沿用同一人员主体,无需重新绑定登录凭证。
  • 离职解绑(offboarded):同样立即吊销各类会话与令牌并阻止后续工作,同时还会释放该租户内未与他人共享的个人 SiteCredential、邮箱别名及 Pod 联系邮箱与手机号绑定,并在审计记录中写入 released_identifiers 水位线,确保未来使用相同邮箱或手机号入职的新员工获得全新的 Human UID。即使账户此前已处于暂停状态,执行离职解绑时仍会释放上述标识符。

无论采取哪种处置方式,主体的 UID、不可变的外部企业身份标识、历史工作产出及审计轨迹都会完整保留。

外部身份源同样可以触发账户停用:员工在飞书中离职、账号冻结或经核准移出同步目录范围,以及在钉钉中办理离职后,目录同步都会自动停用对应的 Ankole 账户。为确保安全,仅凭身份源事件绝不会自动恢复访问权限,网络抖动或同步报错也绝不会被误判为员工离职。

账户一旦停用,该人员名下的后续工作即被全面拦截:以其权限运行的待发消息、计划任务、后台 Agent 任务、Workflow 与 Applet 自动化任务都会在下一次尝试启动时被取消或拒绝;停用前已获准启动的在途执行可正常跑完并如实记录结果,这属于正常收尾而非拦截失败。对于缺少明确归属所有者的历史工作记录,系统会将其挂起为 work_authorization_review_required,直至管理员在审核归属不明的工作页面完成人工裁定(该裁定全程留痕且仅能提交一次)。

人员详情页会汇总展示当前访问状态、处置类型、身份来源、停用原因与时间、操作人或触发源、各项受影响工作的清理结果,以及向各 OIDC 客户端发送单点注销通知的结果;若有清理或通知失败,页面会列出受影响对象并提供重试操作。

恢复账户必须由管理员执行,填明原因并完成身份核验。操作时,Console 会先引导你逐一解除所有限制项,集中预览恢复后将重新生效的权限组成员关系、直接授权及 Pod 页面 Userset 授权,并要求你显式确认批准。其中,来自身份源的外部限制只有在最近一次目录核对成功确认账号已恢复正常后才允许解除。账户恢复后,本人需重新登录(飞书用户还需重新授权个人连接),而此前已吊销的旧会话、已释放的凭证以及已取消的任务不会自动复活。

极端情况下,若 siteadmin 组或某个 Pod 的 pod_admin 组内已无任何在职启用的人类管理员,具备控制面 Shell 权限的运维人员可运行留痕恢复命令(底层调用 Ankole.Release.recover_admin),将管理权限授予一位已完成身份核验的启用态内部成员(member):

# 恢复站点管理权限(特权租户中的 siteadmin)
mix ankole.admin.recover HUMAN_UID OPERATOR REASON --identity-verified

# 恢复指定租户的 Pod 管理权限(该租户中的 pod_admin)
mix ankole.admin.recover HUMAN_UID OPERATOR REASON --identity-verified --tenant SLUG

只要目标管理员组内仍存在哪怕一位启用态管理员,或者目标人员处于停用状态、抑或属于外部访客(guest),该命令都会直接拒绝执行。

关于底层权限模型与运行时求值规则的完整说明,请参阅 主体与 AuthZ。