---
url: https://qiwuadmin.com/features/permission.md
description: >-
  功能权限与数据范围两层授权：权限点、给角色授权、五种数据范围、多个角色时怎样合并、超出范围返回
  404、防越权授予规则、超级管理员的保护，以及多租户的租户套餐和平台专属页面。
---

# 权限与数据范围

权限分两层：

* **功能权限**：能不能做某件事，比如"新增用户"、"导出图书"。按菜单和按钮授权；
* **数据范围**：能看到、能改哪些数据，比如"只看本部门的用户"。按部门授权。

两层都由**服务端**检查。界面上隐藏按钮只是为了好用，就算有人绕过界面直接调用接口，也会被服务端拦下来。

两层都配置在**角色**上：管理员给角色授权，再把角色分配给用户。

## 功能权限

### 权限点

**权限点**是一项具体操作的编码，格式是 `域.资源.动作`，比如 `iam.user.create` 表示"新增用户"。菜单里的每个按钮对应一个权限点。

常见的动作：

| 动作 | 按钮名称 | 作用 |
| --- | --- | --- |
| `browse` | 浏览 | 打开列表 |
| `view` | 查看 | 看详情，打开编辑弹框也需要它 |
| `create` | 新增 | |
| `modify` | 修改 | 包括启用、停用 |
| `remove` | 删除 | 包括批量删除 |
| `export` | 导出 | 导出 Excel |
| `import` | 导入 | 导入 Excel |

有些模块还有自己的动作，比如用户管理的"重置密码"（`iam.user.reset-password`）、角色管理的"授权"（`iam.role.grant`）。

### 给角色授权

在 **系统管理 → 角色管理** 中，点角色那一行的 **更多 → 菜单权限**：

* 弹框里是所有菜单组成的一棵树，按钮旁边显示它的权限点；
* 停用的菜单也会显示（带"停用"标签），可以勾选，但停用期间它不授予任何权限；
* **父子联动**开启时，勾选下级会带上上级，勾选上级会带上全部下级。需要精确控制时可以关掉；
* 只勾了某个按钮时，它所在的页面和目录也会出现在侧边栏里。目录下只有这一个能看到的页面时，侧边栏默认直接显示这个页面，不显示目录这一层，见[菜单管理 · 主要字段](/features/system#主要字段)里的"总是显示目录"。

![角色的菜单权限弹框](/screenshots/zh-role-perms.webp)

### 把角色分给用户

有三个地方可以分配：

* **系统管理 → 用户管理**：新增或编辑用户时直接选角色；
* **系统管理 → 用户管理** → **更多 → 分配角色**；
* **系统管理 → 角色管理** → **更多 → 分配用户**：一次给多个用户分配，或者取消分配。

### 用户最终有哪些权限

用户的权限 = 他的**已启用角色**所授权的、**已启用菜单**上的权限点合在一起。

* 角色停用后，它的权限立即失效；
* 菜单（或者它的任何一级上级目录）停用后，它下面的按钮都不再授予权限，页面也从侧边栏消失。

没有权限时：

| 地方 | 表现 |
| --- | --- |
| 按钮 | 不显示 |
| 侧边栏 | 没有这个页面 |
| 在地址栏直接输入页面地址 | 显示 404 页面 |
| 直接调用接口 | 返回 403，提示"没有执行此操作的权限" |

### 权限何时生效

修改以下内容后，**对方不需要重新登录**。他的下一次请求会发现权限变了，服务端重新加载他的权限，界面上的菜单和按钮也自动更新：

* 角色的菜单权限、数据权限、启用状态；
* 用户的角色、所在部门；
* 菜单管理中的任何修改；
* 调整部门的上下级。

停用或删除用户时，他的所有登录会立即失效。

::: tip 新模块不会自动授权
用代码生成器新建的页面，只有超级管理员能马上看到。其他人要在角色管理里勾选后才能使用，见[新增业务模块](/guide/new-module)。开启多租户时，还要把它勾进[租户套餐](#租户套餐与平台专属页面)，租户里的人才能用。
:::

## 数据范围

功能权限决定"能不能浏览用户"，数据范围决定"浏览时能看到哪些用户"。

在 **系统管理 → 角色管理** 中，点 **更多 → 数据权限** 设置。有五种：

| 数据范围 | 编码 | 能看到的数据 |
| --- | --- | --- |
| 全部数据 | `all` | 所有数据 |
| 指定部门 | `picked_depts` | 在下面的部门树里勾选的部门 |
| 本部门 | `own_dept` | 用户自己所在部门 |
| 本部门及下级 | `own_dept_tree` | 用户所在部门，以及它下面的所有部门 |
| 仅本人 | `own_rows` | 用户自己创建的数据 |

* 新建的角色，数据范围默认是"本部门"；
* 选"指定部门"时，部门树只显示**你自己能看到**的部门。角色原来选过、但你看不到的部门，弹框会提示有几个，保存时保持不变；
* 用户没有所属部门时，"本部门"和"本部门及下级"都看不到任何数据。

### 哪些地方受数据范围限制

| 页面 | 按什么判断 | "仅本人"时 |
| --- | --- | --- |
| **系统管理 → 用户管理** | 用户所在部门 | 只看到自己 |
| **系统管理 → 部门管理** | 部门本身 | 看不到任何部门 |
| **系统监控 → 在线用户** | 登录用户所在部门 | 只看到自己的登录 |
| **流程审批 → 流程管理** 的实例管理、任务管理、审批数据，以及管理员查看审批详情 | 发起部门（发起申请时发起人所在的部门，之后调动部门也不变） | 只看到自己发起的 |
| **生成示例 → 图书** | 图书的所属部门 | 自己创建的图书 |
| 代码生成器生成的、带部门列的模块 | 记录的所属部门 | 自己创建的记录 |

后台页面里选择用户的弹框、选择部门的下拉树，默认也只列出范围内的用户和部门（审批表单里的"人员选择"、"部门选择"不受限制，见[表单设计器](/features/formkit)）。

项目代码里手写的查询（比如统计报表）也能加上同样的数据范围；既没加范围、也没写明理由的查询，开发时的检查会找出来。写法见[开发指南 · 手写 SQL](/core/permission#手写-sql-datascopesql)。

**角色管理不受数据范围限制**：角色不属于任何部门，谁能管角色只看有没有 `iam.role.*` 权限。由此带来的风险，由下面的[防越权授予](#防越权授予)兜底。

### 用户有多个角色时

**一个角色只有给了你这项权限，它的数据范围才算数。** 符合条件的角色有好几个时，它们的范围合在一起（并集）。不需要权限的地方（选择用户的弹框、选择部门的下拉树）按你所有已启用角色的范围合在一起算。

举个例子，张三有两个角色：

| 角色 | 有"用户管理 → 浏览"吗 | 数据范围 |
| --- | --- | --- |
| 人事专员 | 有 | 本部门 |
| 报表查看 | 没有 | 全部数据 |

张三浏览用户时，只按"人事专员"算，**只能看到本部门的用户**。"报表查看"的"全部数据"不算数，因为这个角色并没有让他浏览用户。

这样，给某人加一个"范围很大、但权限很少"的角色，不会意外扩大他其他操作的范围。

### 超出范围时

* 列表、导出、下拉选项里，**不包含**范围外的数据；
* 打开、修改、删除范围外的某一条数据，返回 **404**，提示"请求的资源不存在"，和数据真的不存在时一模一样；
* 批量操作中只要有一条超出范围，整个请求失败，一条都不会修改；
* 新增或修改后，这条数据必须仍在你的范围内，否则返回 404。比如"本部门"的角色把所属部门改成别的部门，会保存失败。"仅本人"不看所属部门：在图书和代码生成的模块里，自己创建的记录填哪个所属部门都能保存；在用户管理里，"仅本人"只能修改自己，新增用户一定返回 404。没有填所属部门时，只有"全部数据"或"仅本人"的角色能保存（用户管理除外）；
* Excel 导入选"新增并更新已有记录"时，只会匹配范围内的记录。范围外有相同唯一值的记录时（比如图书的 ISBN 相同），这一行按"数据已存在"报错，不会覆盖它。

::: tip 为什么是 404 而不是 403
返回 403 等于告诉对方"这条记录存在，只是你没有权限"。统一返回 404，就不会泄露记录是否存在。
:::

## 防越权授予

能管理角色和用户的人，**不能把超过自己的权限交给别人**，也不能交给自己。否则"我能管角色，就给自己建一个超级角色"就成了可能。

这些规则对超级管理员以外的所有人生效，违反时返回 403，提示"不能授予超出自己权限或数据范围的角色"：

1. **菜单权限**：给角色新勾选的按钮，自己必须也有。另外，这个角色的数据范围不能比你在这项权限上的范围大：不能借一个范围更大的角色，把"同样的权限"送到你管不到的部门。数据范围是"全部数据"的角色，不能从你这里获得任何权限；
2. **数据权限**：不能设为"全部数据"（下拉框里也不会出现这一项）；新增覆盖的部门，必须在你自己的范围内，并且对这个角色的**每一项权限**分别检查。缩小范围不检查；
3. **分配角色**（新增和编辑用户、分配角色、分配用户）：
   * 不能分配超级管理员角色，也不能分配"全部数据"的角色；
   * 角色上的所有权限点（包括停用菜单上的）自己都要有；
   * 角色覆盖的部门要在自己的范围内。"本部门"类的角色按**接收角色的那个用户**的部门计算；
   * 把用户调到别的部门时，他已有的"本部门"类角色会跟着变，所以也要重新检查。
4. **间接授予**也一样检查：
   * 在 **系统管理 → 菜单管理** 中给菜单填写权限点时，只能填自己有的；
   * 修改菜单（改权限点、启用菜单或它的上级目录、把菜单移出停用的目录）让某些角色**新得到**了权限点，按第 1 条检查；
   * 重新启用一个停用的角色，等于把它的全部权限再交出去一次，按第 1、2 条检查（停用不检查）；
   * 移动部门：新上级部门里持有"本部门及下级"角色的人从此能看到被移动的部门，所以这些角色的每项权限都要能覆盖这个部门（连同下级），按第 2 条检查。
5. **重置别人的密码、设置别人的登录手机号**：这样做等于拿到了这个账号，所以按分配角色检查：你必须能把这个用户**当前持有的全部角色**（停用的也算）分配给别人，规则同第 3 条。否则返回 403，提示"该用户持有你不能授予的角色：只有能授予这些角色的管理员才能重置其密码或修改其手机号"。所以只有"重置密码"权限的服务台角色，不能重置权限或数据范围比它大的用户。

只检查**新增**的部分。保留或者取消已有的授权，不会让别人得到更多，所以总是允许。

开启多租户时，租户的内置角色"租户管理员"本来就拥有套餐里的全部权限，所以由租户管理员操作时，只按他持有的权限点和平台专属的权限点检查：角色里停用菜单或套餐外菜单的权限点，不会挡住他。

## 例子：让部门经理查看审批数据

功能权限、数据范围和业务自己的规则是叠加起作用的。以[审批数据](/features/workflow#审批数据)为例：

1. 在 **系统管理 → 角色管理** 里，给"部门经理"角色打开 **更多 → 菜单权限**，在 **流程审批 → 流程管理 → 审批数据** 下勾选"浏览"（`wf.data.browse`），需要导出再勾"导出"（`wf.data.export`）；
2. 他能看到哪些申请，由这个角色的**数据权限**决定，按**发起部门**（发起申请时发起人所在的部门）计算。比如设为"本部门及下级"，他就只看到在这些部门发起的申请；
3. 如果他还有别的角色，那些角色没有 `wf.data.browse` 的话，它们的范围在这里不算数（见[用户有多个角色时](#用户有多个角色时)）；
4. 做这个授权的人如果不是超级管理员，自己也要有这两个权限，并且"部门经理"角色的范围不能超出他自己在这两个权限上的范围（见[防越权授予](#防越权授予)）；
5. 他看不到流程里任何节点设为"隐藏"的字段，页面顶部会提示有几个字段被隐藏。需要看薪资这类敏感字段的人（比如 HR），在 **流程审批 → 流程管理 → 模型管理** 里编辑这个审批，把他加进"流程管理员"，他就能看到并导出全部字段。修改流程管理员需要 **模型管理** 下的"任命流程管理员"权限（`wf.model.managers`），默认只有超级管理员有；没有这个权限的人，"流程管理员"这一项是只读的。超级管理员始终能看到全部字段。详见[工作流 · 审批数据里的字段权限](/features/workflow#审批数据里的字段权限)。

## 超级管理员

内置角色"超级管理员"（编码 `root`）拥有全部权限，不受数据范围限制，也不受防越权授予的限制。初始化时创建的 `admin` 用户就是超级管理员。

一个用户是不是超级管理员，**只看他有没有这个内置角色**。自己新建的角色，勾选的菜单再多，也不是超级管理员。

::: info 演示模式对所有人生效
开启演示模式（环境变量 `APP_DEMO_MODE`，见[环境变量 · 功能](/reference/env#功能)）后，包括超级管理员在内，所有人都只能浏览：修改类的请求一律返回 403，提示"演示模式下不能执行此操作"。只有登录、退出、锁屏解锁、切换界面语言、保存列设置、把公告和消息标为已读、进入和退出租户等少数操作照常可用。
:::

### 受保护的角色和账号

| 对象 | 保护规则 |
| --- | --- |
| 超级管理员角色 | 不能删除、不能停用、不能改编码；它本来就有全部权限，所以不能设置菜单权限和数据权限；只有超级管理员能编辑它 |
| 超级管理员角色的分配 | 别人在选择角色时看不到它，也分配不了；任何人都不能把它从用户身上取消 |
| 有这个角色的用户 | 任何人都不能删除或停用他；不是超级管理员的人不能编辑他、重置他的密码、修改他的角色，也不能强退他 |
| 自己的账号 | 不能删除或停用自己 |

违反时提示"内置角色受保护，不能执行此操作"或"超级管理员账号受保护，不能执行此操作"。

另外，被用户占用的角色不能删除，提示"角色已分配给用户，请先取消分配再删除"。

### 只有超级管理员能做的事

| 事情 | 原因 |
| --- | --- |
| 修改注册相关的参数：`auth.signup.enabled`（是否开放注册）、`auth.signup.default_role_id`（注册默认角色）、`auth.signup.default_dept_id`（注册默认部门） | 决定陌生人注册后得到什么权限 |
| 修改注册默认角色本身、它的菜单权限和数据权限，以及在 **系统管理 → 角色管理** → **更多 → 分配用户** 里为它增减成员（在用户管理里给用户分配或取消这个角色不受此限制，只按[防越权授予](#防越权授予)检查） | 同上 |
| 修改 `auth.wx_mp.enabled`（微信小程序登录开关） | 决定能不能用微信登录 |
| 修改 `mcp.paused`（智能体接入的急停） | 一改就停掉所有租户的智能体调用 |
| 修改 `audit.retention_days`（日志保留天数） | 进入、退出租户这类审计记录谁都不能删除，只能靠保留期清理；改短保留期就等于删除它们 |
| 新增、修改、删除、测试发送编码以 `auth.` 开头的短信模板；修改、删除这些模板使用的短信渠道 | 登录和找回密码的验证码走这条路，改了就可能让验证码经过别人的短信账号发出 |
| 在角色的数据权限里选"全部数据" | 见[防越权授予](#防越权授予) |

其他人做这些事时返回 403。

::: tip 日常管理不要用超级管理员
超级管理员不受任何限制，出了问题影响最大。建议只用它做初始配置，日常的管理工作交给普通角色，按需要授予权限和数据范围。
:::

## 租户套餐与平台专属页面

这一节只在开启[多租户](/features/multi-tenancy)后适用。

* **租户套餐**是平台给一个租户开放的一组菜单。租户里用户的权限 = 角色授权的权限点和套餐里的权限点**都有**的部分。角色管理的授权树只列套餐里的菜单；套餐缩小后，角色原有的授权保留但不生效，套餐再放大时自动恢复；
* 每个租户的内置角色"租户管理员"（`tenant_admin`）拥有套餐的全部权限，数据范围是"全部数据"。租户没有套餐，或者套餐被停用、删除时，这个租户什么都不能用。默认租户（平台）不受套餐限制；
* **平台专属页面**只给默认租户用，不能放进套餐，租户里的人拿不到它们的权限点：系统监控里除"在线用户"以外的页面；系统工具里的代码生成、表单构建、系统接口、Element Plus 文档；系统管理里的菜单管理、字典管理、字典数据、参数设置、App 版本、存储配置、客户端管理、邮件账号、短信渠道、站内信模板、邮件模板、短信模板、API 访问日志、API 错误日志、租户管理、租户套餐；
* API 访问日志、API 错误日志和缓存列表里是所有租户的数据，所以只有平台的超级管理员能打开，角色里勾选了也不行；
* 平台人员**进入租户**要有"进入租户"权限（`iam.tenant.enter`）。进入后按本人的权限操作，去掉平台专属页面的权限点（超级管理员除外，仍有全部权限），不按套餐收窄；数据范围也按本人的角色算，所以要给他一个"全部数据"的角色，否则在租户里看不到数据；
* **受保护的账号**：租户的所有者（开通租户时建的管理员）不能停用、删除，只有平台的超级管理员能修改他的密码、联系方式、部门和角色，或者强退他；持有"租户管理员"角色的其他用户，只有平台的超级管理员和租户管理员能做这些事，也只有他们能停用、删除这些用户。

## 开发指南

* [在代码中使用权限与数据范围](/core/permission)：权限常量、保护接口、给实体加数据范围、按 id 修改的写法
* [权限与翻译](/core/web-perm-i18n)：前端按权限显示按钮
* [种子与菜单](/core/seed#菜单和按钮权限)：在种子里添加菜单和按钮权限
* [服务 · 按 id 修改的标准写法](/core/service#按-id-修改的标准写法)
* [路由与菜单](/core/web-router)：菜单怎么变成前端路由

相关功能：

* [安全基线](/features/security)
* [工作流 · 审批数据](/features/workflow#审批数据)
* [代码生成器](/features/codegen)：带部门列的表会自动接入数据范围
