# 设置数据访问范围

配置人员、角色和策略，控制项目与数据的访问权限。

数据范围不是一处开关决定的：「项目成员」决定谁能进项目；「策略」定义可见的库、表和字段，并可按行过滤；「角色」把若干策略打包；「人员」把飞书身份和 AskTable 档案对上号；智能体上的白名单再把人员和角色绑到具体智能体。给一个部门、一个门店或一类岗位开数据时，这几处要一起配。

## 开始前

- 权限：配置人员、角色和策略需要有效的项目负责人（OWNER）或项目管理员（ADMIN）角色。项目成员（MEMBER）可以查看有权访问的资源和问数，不能修改这些管理配置。
- 入口：左侧主导航 → 「更多」→ 左侧栏「数据访问控制」下的「人员」「角色」「策略」。
- 配置顺序：先建策略，再建角色并绑定策略，最后把人员和角色授权到智能体。反过来做会拿到没有数据源的角色。

## 操作步骤

**先建策略**

左侧栏「数据访问控制」 → 「策略」 → 右上角「新建策略」。弹窗里填名称（最多 25 个字符）并选权限：「允许」或「拒绝」，点「创建」后进入详情页。

详情页从上到下是「基本信息」「数据访问规则」和「数据范围预览」三块：「基本信息」写策略名称与权限方向，「数据访问规则」用来选数据源并配置字段级、行级访问规则。

**给策略加数据源**

「数据源」区块可以加多个数据源，规则对所有列出的数据源生效；点「添加数据源」，在「选择要添加的数据源」弹窗里勾选。没加之前区块提示需要先添加数据源。

**配字段级规则**

「字段级规则」按 Schema / Table / Field 三层匹配模式控制可见范围，下面分「库名匹配规则」「表名匹配规则」「字段名匹配规则」三组。点「添加规则」打开「添加规则」弹窗，选匹配方式——「完全匹配」「前缀是」「后缀是」「包含」——再填匹配值。同一组里多条规则用连接条件组合，可以选「满足任一」或「全部满足」。一组都不配时按默认放行处理，区块会提示当前没有规则、默认匹配所有的库。

**按行过滤**

「行级过滤」按数据源单独配置 WHERE 条件，只有 allow 策略生效。点「添加过滤」，在「添加行级过滤」弹窗里选数据源、库、表、字段和运算符，再填值。权限方向是「拒绝」的策略不显示这一块，硬配会被校验拦下，提示拒绝策略下不能配置行过滤。

**用预览核对**

「数据范围预览」实时展示策略覆盖的可见域，默认全部收起。按数据源展开，能看到库、表、字段三级的可见统计；策略还没指向数据源时，这里显示该策略未指向任何数据源。

**建角色并绑定策略**

左侧栏「数据访问控制」 → 「角色」 → 「新建角色」，填名称后点「创建」。详情页的「应用策略」用来给角色绑定策略、决定它对数据的访问权限，点「添加策略」，在「添加策略」弹窗里勾选；全部加完时提示已添加全部策略，列表为空时显示尚未绑定策略。下方「数据范围预览」给出合并 allow 与 deny 之后的最终可见范围。

**建人员档案**

左侧栏「数据访问控制」 → 「人员」，默认停在「已建档」标签页。点「新建人员」，填姓名（必填）、邮箱、手机和备注，点「建档」。列表列是姓名、邮箱、手机、渠道绑定和创建时间；绑了飞书后渠道绑定列显示飞书和已绑数量，没绑时显示未绑定。飞书用户第一次提问会自动进「待审批」标签页。

**把人员和角色授权到智能体**

这一步在智能体上做：打开目标智能体 → 顶部标签「频道」 → 「人员」区块（需要先启用飞书频道，这个区块才会出现）→ 打开启用白名单开关 → 点「添加人员」，选好人员和角色后点「授权」。角色不选时下拉显示「不选择任何角色」，并提示不选角色时用户默认使用该数据智能体的访问范围、可访问它已配置的全部数据范围；授权完成后，列表的角色列对这种记录会标注不指定角色即全权。

## 关键约束

| 项目       | 值或默认                                                    | 在哪里改                                                                           |
| -------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 策略名称     | 最多 25 个字符                                               | 「策略」 → 「新建策略」，或详情页「基本信息」                                                       |
| 权限       | 「允许」或「拒绝」                                               | 策略详情页「基本信息」                                                                    |
| 字段级规则为空时 | 默认匹配所有的库、表、字段                                           | 策略详情页「字段级规则」                                                                   |
| 「行级过滤」   | 只在权限为「允许」的策略上可配                                         | 策略详情页「行级过滤」                                                                    |
| 「角色」数量   | 上限 5 个（Cloud 部署的项目资源配额；私有部署不执行）                         | 「角色」页；超限时删掉不用的角色                                                               |
| 「策略」数量   | 上限 10 个（同上）                                             | 「策略」页                                                                          |
| 数据源数量    | 上限 50 个（同上）                                             | 「数据源」页                                                                         |
| 单个数据源的表数 | 上限 100 张，元数据初始化时校验（同上）                                  | 数据源侧                                                                           |
| 智能体白名单   | 默认关闭，即不额外过滤                                             | 智能体详情 → 「频道」 → 「人员」                                                            |
| 公开项目     | 当前组织正常的 Owner/Admin/Member 按默认 Admin 或 Member 进入；显式角色优先 | 项目负责人在项目设置中调整类别和默认权限，见[组织与项目](https://docs.asktable.com/organization/overview) |

## 出问题怎么判断

| 现象                           | 判定条件                                                | 处理                                       |
| ---------------------------- | --------------------------------------------------- | ---------------------------------------- |
| 用户说看不到数据                     | 提问被拒绝，提示没有可查询的数据表或字段                                | 检查该智能体「配置」 → 「数据源」是否为空；为空就先挂数据源          |
| 提问被拒绝，提示数据源中找不到表 X（schema Y） | 这张表不在该用户角色合并后的可见域里                                  | 打开对应策略的「数据范围预览」确认；必要时在「字段级规则」加一条「完全匹配」规则 |
| 保存人员、角色或策略被拒绝                | 当前有效项目角色没有管理权限                                      | 由项目负责人或项目管理员操作，或调整该成员的显式项目角色             |
| 点「新建角色」被拒                    | 「角色」列表已经有 5 条，接口返回配额超限错误码 `RESOURCE_QUOTA_EXCEEDED` | 到「角色」页删掉不再使用的角色                          |
| 删角色被拒，提示角色正被多个智能体白名单引用       | 有智能体的白名单还在用这个角色                                     | 先在相关智能体的「人员」区块把这条授权移除，或换成别的角色            |
| 「行级过滤」区块里没有「添加过滤」            | 该策略的权限方向是「拒绝」                                       | 行过滤只对「允许」策略生效；要按行限制就改用「允许」策略             |
| 「数据范围预览」提示该策略未指向任何数据源        | 这条策略还没加数据源                                          | 在「数据源」区块点「添加数据源」                         |
| 角色页「数据范围预览」提示绑定的策略未指向任何数据源   | 角色绑定的策略一条都没加数据源                                     | 回到每条策略补齐「数据源」                            |

## 下一步

- 把人员和角色授权到具体智能体，控制飞书群里的问数范围：/permissions/feishu
- 创建并配置数据智能体：/agent/overview
- 把重复的分析步骤固化成技能：/agent/skill