> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asktable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置渠道用户访问数据的权限

> 通过白名单和角色,控制飞书群里不同用户能问到哪些数据 —— 涵盖人员建档、角色分配、行级过滤的完整流程。

接通飞书后([如何连接智能体到飞书群组](/how-to/connect-feishu)),默认情况下群里任何人都可以问数。如果你需要按部门、按身份控制谁能看到哪些数据,就要用到 AskTable 的「白名单 + 角色」机制。

## 权限模型概述

AskTable 把飞书用户和数据权限的关系拆成三层:

```text theme={null}
飞书 user_id  ──绑定──>  人员 (Person)  ──授权──>  数据智能体 + 角色 (Role)
                                                          │
                                                          └──> 策略 (Policy)  ──> 字段/行级规则
```

* **人员(Person)** —— AskTable 内部的用户档案,可以一人对应多个外部渠道身份(飞书、未来的钉钉等)
* **渠道绑定(Channel Binding)** —— 把飞书的 `user_id` 关联到一个 Person
* **角色(Role)** —— 一组策略的打包,决定能看哪些数据范围
* **策略(Policy)** —— 实际的访问规则,包括允许/拒绝、字段级、行级过滤

每个数据智能体上有一个 **白名单** 开关:

* **关闭** —— 任何能进群的飞书用户都能问数(适合内部共享数据)
* **开启** —— 必须先在白名单里,否则消息会被拒绝,同时自动进入「待审批」列表

## 1. 在飞书开放平台补开通讯录权限

要识别飞书用户身份(拿到 `user_id`、姓名、邮箱),必须先在飞书后台的 **权限管理** → **API 权限** 加开下面 3 个权限。这是在 [连接飞书](/how-to/connect-feishu) 那两个基础权限之上额外要补的:

| 权限                                  | 作用                           |
| ----------------------------------- | ---------------------------- |
| `contact:contact.base:readonly`     | 获取通讯录基本信息                    |
| `contact:user.base:readonly`        | 获取用户基本信息(姓名、邮箱、手机)           |
| `contact:user.employee_id:readonly` | 获取用户 `user_id` —— 白名单匹配的核心字段 |

<Warning>
  `contact:*` 权限属于「申请类」,需要企业管理员单独审批。审批通过前,飞书用户问数会一直被挡在白名单外,AskTable 也拿不到他们的姓名邮箱来建档。
</Warning>

开通后记得回到 **版本管理与发布**,**重新提交一个新版本** 并等管理员审批 —— 飞书的权限变更必须随版本发布才会生效。

## 2. 开启数据智能体的白名单

进入数据智能体详情页,在权限相关区域找到 **白名单** 开关。开关下方的提示文案会同步切换:

| 状态     | 含义               |
| ------ | ---------------- |
| **关闭** | 任何能进群的飞书用户都可问数   |
| **开启** | 仅在白名单内的人可以访问此智能体 |

打开开关后,新的飞书用户首次问数会被拒绝,并在 AskTable 这边自动生成一条「待审批」记录。

## 3. 处理待审批申请

进入 **数据访问控制** → **人员**,顶部有两个 Tab:

* **已建档** —— 已经在 AskTable 中有档案的人员
* **待审批** —— 飞书用户首次问数自动出现在这里

每条待审批记录展示:

| 字段                | 说明                       |
| ----------------- | ------------------------ |
| **姓名 / 头像**       | 从飞书拉取                    |
| **邮箱 / 手机**       | 从飞书拉取,可能为空               |
| **申请访问**          | 这个用户想问哪个数据智能体            |
| **最近申请 / 首次申请时间** | 同一个人多次申请会合并              |
| **状态**            | 未建档 / 已建档待授权 / 已通过 / 已拒绝 |

操作有三个:

* **建档/关联** —— 走下一步,把飞书身份和 AskTable 人员档案绑起来
* **分配权限** —— 已建档但还没分配角色时用
* **拒绝** —— 永久拒绝这个申请,该用户后续问数会一直被挡

## 4. 建档:新建人员或关联到已有人员

点 **建档/关联** 弹出对话框,先看顶部 **飞书账号信息**(姓名、`user_id`、邮箱、手机),然后选两种模式之一:

* **新建人员档案** —— 创建一个全新的 Person,姓名/邮箱/手机会从飞书自动填好,可以再加备注
* **关联到已有人员** —— 按姓名/邮箱/手机搜索已有 Person,选中后会自动加上飞书绑定

<Note>
  飞书的 `user_id` 是自动绑定的,不需要你手填。一个 Person 可以同时绑多个飞书 `user_id`(比如同一个人在多个企业里)。
</Note>

点 **建档** 完成。这一步只是把「这个飞书用户」和「这个 AskTable 人员」对上号,还没有赋予任何数据权限。

## 5. 分配角色

建档完成后会接着弹出 **为「xxx」分配「yyy 智能体」的权限** 对话框,关键字段是 **角色**:

| 选择             | 行为                                |
| -------------- | --------------------------------- |
| **不选任何角色**     | 全权 —— 用户能看到该智能体配置的全部数据范围,不做任何额外过滤 |
| **选择一个已建好的角色** | 应用该角色绑定的所有策略(allow/deny、字段级、行级)   |

如果选中的角色定义了 **必填变量**(比如 `dept_id`、`user_id`),对话框会展开 **角色变量** 字段,你需要给这个人填上对应值。这些值会在用户问数时拼到 SQL 的 WHERE 里,实现行级过滤(RLS)。

举个例子:角色 **部门数据** 绑定了一条策略「`orders` 表只能看 `dept_id = {{dept_id}}` 的行」,那么:

* 给「张三」分配此角色时,**dept\_id** 填 `D001`
* 张三在飞书里问「上月销售额」,生成的 SQL 会自动带上 `WHERE dept_id = 'D001'`
* 李四的 `dept_id` 是 `D002`,问同一个问题看到的是完全不同的子集

点 **授权** 完成。这个人之后在飞书里问数就会按这个角色的规则放行。

## 6. 创建可复用的角色

如果是第一次配,需要先去 **数据访问控制 → 角色 → 新建角色**:

1. **取名**,比如「部门数据」「销售经理」「外部访客」
2. 在 **应用策略** 区域 **添加策略** —— 没有合适的策略就先去 **数据访问控制 → 策略** 建一个
3. 保存

**策略(Policy)** 才是真正定义「能看哪些库/表/字段、能过滤哪些行」的地方,角色只是把若干策略打包。一个策略包含:

* **权限方向** —— 允许 / 拒绝
* **数据源** —— 适用于哪些数据源
* **字段级规则** —— 按 schema / table / field 三层匹配模式控制可见字段
* **行级过滤** —— 在指定字段上加 WHERE 条件,支持引用变量

完整策略和角色的使用方式不在本文范围,先建好你需要的角色,再回到第 5 步分配。

## 7. 常见场景示例

### 场景 A:全员只读全部数据

最简单的情况,不开白名单,任何人进群都能问。适合企业内部知识共享。

### 场景 B:按部门隔离

* 开启白名单
* 建一个「部门数据」角色,策略带行级过滤 `dept_id = {{dept_id}}`
* 每次审批新人时,在「角色变量」里填好这个人的 `dept_id`

### 场景 C:外部访客只看部分数据

* 开启白名单
* 建一个「访客」角色,绑定一条「仅允许 `public` schema」的 allow 策略
* 外部用户首次问数 → 进入待审批 → 你审批时分配「访客」角色
* 内部员工分配其他更宽松的角色

## 8. 撤销权限

两种方式:

* **保留人员,移除单个智能体的访问** —— 进入人员详情页 → **已授权的数据智能体** 区域 → 找到对应智能体 → 点 **移除**
* **彻底清除** —— 在人员详情页右下角的 **危险操作** 区域 **删除人员**。所有渠道绑定和已授权访问会一并清除,该用户在飞书里再问数会重新走「待审批」流程

## 9. 后续步骤

* 还没接通飞书 → [如何连接智能体到飞书群组](/how-to/connect-feishu)
* 想给字段加业务说明、提高 AI 准确度 → [表、字段备注](/concepts/data/annotations)
* 想隐藏不希望 AI 看到的字段 → [字段隐藏](/concepts/data/hidden-fields)