---
title: "主体与权限组"
description: "从身份源同步人员和组织架构，并用目录组、静态组或动态组统一分配权限。"
url: "https://ankole.agentbull.com/zh-Hans-CN/docs/principal-and-groups/"
lang: "zh-Hans-CN"
---

> 面向 AI Agent 的文档索引：https://ankole.agentbull.com/zh-Hans-CN/llms.txt

# 主体与权限组

Ankole 把人员、Agent 和系统服务统一表示为主体（Principal）。权限组把多个主体放在一起管理，授权规则则决定一个主体或权限组可以操作哪些资源。

企业员工和组织架构通常由身份源提供商（IdP）自动同步。你不需要逐个创建员工，也不需要在 Ankole 里重复维护部门成员。

## 身份源如何同步组织架构

在身份源提供商中启用通讯录同步后，Ankole 会把外部目录转换为两类数据：

- 员工会成为“人员”主体；姓名、头像等资料会随目录同步更新；
- 部门、用户组等组织单元会成为目录权限组，成员关系也会一起同步。

如果外部目录包含上下级部门，员工加入子部门后，也会成为其上级部门组的成员。因此，把权限授予一个上级部门，就能覆盖其下属部门中的员工。

保存身份源提供商后，Ankole 会启动首次完整同步。之后默认每六小时进行一次完整同步；支持增量同步的身份源还会接收人员和组织变更，不必等待下一次完整同步。

需要立即刷新时，打开 **Console → 身份源提供商**，选择对应的 Provider，再选择“执行完整同步”。同步完成后，到 **访问控制 → 主体** 和 **访问控制 → 权限组** 检查结果。

目录组的来源仍是外部身份系统。请在企业通讯录中修改部门和成员，不要尝试在 Ankole 中手工维护这些组。

如果同步结果缺少人员或部门，先检查外部应用的通讯录权限和可用范围，再重新执行完整同步。接口权限已经开通，并不代表应用能读取整个组织。

首次连接身份源的方法见 [快速开始](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#2-先设置身份源提供商)。

## 查看主体

打开 **Console → 访问控制 → 主体**。列表会显示主体的名称、UID、类型和状态：

- **人员**来自身份源提供商同步的企业通讯录；
- **Agent**在创建 Agent 时自动出现；
- **系统**由 Ankole 自身创建，用于执行内部服务工作。

选择主体名称或行末的“查看详情”，可以查看它所属的权限组和直接授权。主体的 UID、类型和状态来自身份或运行时所有者，在这个页面中只读。排查权限时，应同时检查权限组和直接授权：主体可能没有直接授权，但通过权限组获得了权限。

## 选择合适的权限组

权限组的来源和成员维护方式不同：

| 权限组 | 适合什么情况 | 谁维护成员 |
| --- | --- | --- |
| **目录组** | 企业通讯录中已经存在的部门或用户组 | 身份源提供商自动同步 |
| **IM 群组** | 权限需要跟随聊天群成员 | 聊天渠道同步 |
| **信号源用户组** | 权限需要覆盖“曾通过某条路由规则对话的所有人” | SignalsGateway 准入 |
| **Provider 全员组** | 权限需要覆盖某个身份提供方导入的所有人（`<provider>:members:all`） | 身份提供方同步 |
| **静态组** | Ankole 内部临时组队，或成员较少且变化不频繁 | 管理员手工维护 |
| **动态组** | 可以根据主体属性稳定判断成员 | Ankole 按 CEL 表达式实时计算 |

目录组和 IM 群组会自动出现在权限组列表中。它们的成员关系由外部系统同步，在 Console 中只读。静态组和动态组由管理员在 Ankole 中创建和维护。

企业组织架构已经能表达目标团队时，优先直接使用目录组。这样，员工转岗或离职后，权限会随下一次增量或完整目录同步自动调整。

## 创建静态组

1. 打开 **Console → 访问控制 → 权限组**，选择“新增组”。
2. 填写稳定的小写英文名称、显示名称和说明。
3. 类型选择“静态”，然后保存。
4. 打开新建的组，在“成员”区域选择“添加成员”。

成员加入后，会立即获得该组的全部授权；移除后，也会失去这些授权。

## 创建动态组

动态组不保存成员名单，也不接受手工添加成员。Ankole 会在需要判断权限时，用一条 CEL 表达式检查主体是否属于该组。

创建权限组时选择“动态”，然后在“成员条件”中填写 CEL 表达式。表达式必须返回 `true` 或 `false`，并通过 `principal` 读取当前主体。

动态组目前可以使用这些字段：

| 字段 | 含义 | 常见值 |
| --- | --- | --- |
| `principal.uid` | 主体的稳定 UID | `research-agent` |
| `principal.type` | 主体类型 | `human`、`agent`、`system` |
| `principal.status` | 主体状态 | `active`、`disabled` |
| `principal.displayName` | 显示名称，可能为空 | `张三` |
| `principal.avatarURL` | 头像地址，可能为空 | Provider 返回的 URL |

例如，匹配所有已启用的人员：

```text
principal.type == "human" && principal.status == "active"
```

匹配 UID 以 `research-` 开头的 Agent：

```text
principal.type == "agent" && principal.uid.startsWith("research-")
```

输入表达式时，Console 会自动预览所有匹配的已启用主体。确认人数和名单符合预期后再保存，避免把权限授予过多主体。

保存后，组名称和类型不能修改。普通动态组可以编辑成员条件；保存前应再次检查实时预览。内置动态组的成员条件由系统维护，在 Console 中只读。

CEL 当前不能读取员工的邮箱、职位或所属部门。按部门授权时，应直接使用身份源同步的目录组，不要用显示名称猜测组织关系。

## 添加授权

打开一个权限组或主体，在“权限授权”区域选择“新增授权”，然后填写：

- **资源模式**：权限作用于哪些资源；
- **动作**：允许执行的操作，例如 `read` 或 `update`；
- **条件**：可选的高级限制；留空表示不增加额外条件；
- **描述**：说明为什么需要这项权限。

优先把授权授予权限组。只有某个主体需要例外权限时，才使用直接授权。修改或删除授权会立即影响它的所有者及相关组成员。

授权的所有者在创建后只读。需要把授权移给另一主体或权限组时，请在新所有者下创建授权，确认访问结果后再删除旧授权。

## 按组织架构授权

假设研究部门中的所有员工都需要查看某个 Agent：

1. 确认身份源已经同步出研究部门及其成员。
2. 打开对应的目录权限组。
3. 在该组中新增一条针对目标 Agent 的 `read` 授权。
4. 用该部门的一位员工登录，确认他能打开目标 Agent，但不能访问未授权的资源。

以后在企业通讯录中调整研究部门成员即可。Ankole 完成下一次同步后，会更新组成员；挂在组上的授权不需要重复修改。

不要只看 Console 中是否保存成功。用实际成员账号验证一次，才能确认资源范围、动作和成员来源都符合预期。

## 停用离职人员

人员离职时，停用其账户，不要删除。在**主体和权限组**中打开该人员，在**账户访问**区域填写原因，然后选择**停用账户**。主体、其工作结果和审计历史都会保留；此人不能再登录，其 Console 会话、OAuth 会话和 token 在所有设备上的下一次使用都会被拒绝。

身份源提供商也可以停用账户。飞书的离职、冻结或经审核后移出同步目录范围，以及钉钉的离职，都会通过目录同步停用同一个账户。仅凭提供商事件永远不会恢复访问，网络故障也永远不会被当作离职。

停用会阻止此人的后续工作：以其权限运行的消息、计划任务、后台 Agent 任务、Workflow 和自动化会在下一次启动时被取消或拒绝。已经获准执行的尝试可以完成，并按此显示；这不算停止失败。早于这项检查的旧工作可能没有可证明的所有者，这类工作会以 `work_authorization_review_required` 停下，直到管理员在**审核归属不明的工作**中对其分类；该决定会留痕，且只能作出一次。

人员详情页显示访问状态、身份来源、停用原因和时间、操作者或来源、每个受影响工作项的清理结果，以及每个 OIDC Client 的注销通知结果。清理和通知失败会显示受影响对象和重试操作。

**恢复账户**需要管理员、原因和经核验的身份。Console 会先要求你清除全部限制，显示将会生效的组成员关系和授权，并要求你批准这些权限规则。提供商限制只有在近期一次成功的目录核对确认已恢复后才能清除。恢复后此人重新登录，飞书用户还需要重新授权个人连接。旧会话、旧凭证和已取消的工作仍然失效。

当最后一位在职管理员已经离开时，拥有控制面 shell 访问权限的操作者可以用一条留痕命令把管理员权限授予一位经核验的在职人员：

```sh
mix ankole.admin.recover HUMAN_UID OPERATOR REASON --identity-verified
```

只要还存在在职管理员，该命令就拒绝运行；目标已停用时也会拒绝。

权限概念和授权规则的完整说明见 [主体与 AuthZ](https://ankole.agentbull.com/zh-Hans-CN/docs/principal-authz/index.md)。