---
url: https://qiwuadmin.com/features/system.md
description: 系统管理各页面的用法：用户、角色、菜单、部门、岗位、字典和参数设置，App 版本发布与更新检查，地区与 IP 归属地查询，OAuth2 客户端和个人中心。
---

# 系统管理

**系统管理**是后台最基础的一组菜单：管理账号、角色、菜单和组织架构，字典、参数这类"不改代码也能调整"的设置，以及手机 App 的版本和可以用本系统账号登录的第三方应用。这一页按菜单顺序介绍每个页面能做什么。

权限的原理（功能权限、数据范围、防越权授予）见[权限与数据范围](/features/permission)，这里只讲页面上的操作。

## 菜单一览

| 菜单 | 作用 |
| --- | --- |
| [用户管理](#用户管理) | 系统里的账号：新建、停用、重置密码、分配角色、导入导出 |
| [角色管理](#角色管理) | 一组权限的集合：菜单权限、数据权限、分配用户 |
| [菜单管理](#菜单管理) | 侧边栏的目录和页面，以及页面里的按钮权限 |
| [部门管理](#部门管理) | 组织架构（树形） |
| [岗位管理](#岗位管理) | 职位，比如"开发工程师" |
| [字典管理](#字典管理) | 下拉框的选项和标签颜色 |
| [参数设置](#参数设置) | 管理员可以在线修改的配置，保存后立即生效 |
| [App 版本](#app-版本) | 发布手机 App 的新版本，App 启动时提示更新 |
| [地区管理](#地区管理) | 省市区数据和 IP 归属地查询 |
| 消息中心 | 通知公告、站内信模板、站内信，邮件账号、邮件模板、邮件记录，短信渠道、短信模板、短信记录，见[消息中心](/features/messaging)。本页只简单介绍[通知公告](#通知公告) |
| 日志管理 | 操作日志、登录日志、API 访问日志、API 错误日志，见[操作日志](/core/action-log) |
| 文件管理 | 存储配置、文件列表，见[文件管理](/features/storage) |
| [客户端管理](#客户端管理) | 可以用本系统账号登录的第三方应用，见[单点登录（OAuth2）](/features/oauth) |
| 租户管理 | 开通和管理租户（使用这套系统的各家公司）：套餐、到期时间、绑定域名、品牌，平台人员从这里进入租户。只在开启多租户时出现，见[多租户](/features/multi-tenancy) |
| 租户套餐 | 规定一个租户能用哪些菜单。只在开启多租户时出现，见[多租户](/features/multi-tenancy) |
| MCP 工具 | 智能体能调用的工具，可以整体停用某个工具。只在打开智能体接入（`APP_MCP`）时出现，见[MCP 智能体接入](/features/mcp) |
| 访问令牌 | 查看和吊销本租户用户的个人访问令牌。只在打开智能体接入时出现，见[MCP 智能体接入](/features/mcp) |

另外，右上角头像菜单里的[个人中心](#个人中心)每个登录用户都能用，不需要授权。

::: info 开启多租户时
租户管理和租户套餐只有默认租户（平台）的人员能用。系统管理里的菜单管理、字典管理、参数设置、App 版本、客户端管理，消息中心里的模板、邮件账号和短信渠道，存储配置，API 访问日志和 API 错误日志，以及 MCP 工具和智能体设置，也都是**平台专属页面**：只有平台能用，租户里看不到。见[权限与数据范围 · 租户套餐与平台专属页面](/features/permission#租户套餐与平台专属页面)。
:::

::: tip 谁能看到这些菜单
初始化后，只有超级管理员（`admin` 账号）能看到系统管理。初始数据里还有两个普通角色"注册成员"和"员工"，默认只能看到首页和流程审批里的发起申请、我的待办等页面。要让别人管理某个页面，在[角色管理](#角色管理)里给他的角色勾选对应的菜单和操作。
:::

### 列表页的共同点

这些页面用的是同一套列表和弹框，用法一样：

* 上方是搜索栏，"搜索"和"重置"；
* 表格右上角可以显示或隐藏搜索栏、刷新、**列设置**（调整列的顺序和显示哪些列，保存在你的账号上，换浏览器也在。每个账号最多保存 200 个列表的设置，超出时返回 409，提示“已保存的列表设置达到上限（200 个），请先将部分列表恢复默认设置”；在列设置里点“恢复默认”会删除这个列表的设置，腾出一个名额）；
* 第一次打开页面、数据还没读到时，表格先显示几行灰色的占位条（叫"骨架屏"），只画你在列设置里显示的列，并按你设置的顺序排列；之后搜索、翻页、刷新时保留原来的表格，只在上面盖一层"正在加载"；
* 表格最右边的操作列只直接显示前几个按钮（默认 2 个，可以在顶栏齿轮图标打开的 **页面设置** 里用“表格行内操作按钮数”改成 1 到 6 个，保存在当前浏览器），其余的收进“更多”，鼠标移上去就展开（也可以用键盘的 Enter 或空格打开）；删除这类危险操作总排在最后，所以最先被收进“更多”；没有权限的按钮不显示，也不占位置；操作列的宽度按实际显示出来的按钮自动算，按钮不会被截断；
* 勾选几行后出现"批量删除"；
* 列表里的"编辑"按钮需要同时有"修改"和"查看"两个权限，因为编辑弹框要先读出这条记录；
* 删除是**逻辑删除**：数据库里还保留着，但页面上不再显示，也不能在页面上恢复；
* 所有新增、修改、删除、导入导出都会记进 **系统管理 → 日志管理 → 操作日志**。

::: warning 重新执行种子时
**种子**是初始化数据库时写入的初始数据（菜单、字典、参数、角色……）。重新执行种子时，下面这些内容会恢复成种子里的值：内置菜单的名称、图标、排序、上级菜单、路由路径、视图组件和组件名、"显示"和"缓存页面"；内置参数的名称和分组。比如把内置页面移到别的目录后，重新执行种子会把它移回去。参数值、启用状态、菜单的"总是显示目录"和角色的授权不受影响，管理员删除的数据也不会被恢复。详见[种子与菜单](/core/seed#种子的规则)。

**字典不会被改回**：重新执行种子只插入缺少的字典和字典项，给已有的补上缺少的语言；你在[字典管理](#字典管理)里改的名称、文字、顺序、标签样式和默认值都保留。详见[字典 · 重新执行种子](/core/dict#重新执行种子)。
:::

## 用户管理

**系统管理 → 用户管理**

页面左边是部门树：点一个部门，列表只显示这个部门**及其所有下级部门**的用户，再点一次取消。部门树可以拖动边缘调整宽度，也可以收起。

![用户管理列表](/screenshots/zh-users.webp)

| 操作 | 说明 |
| --- | --- |
| 搜索 | 关键字（用户名或显示名）、手机号、启用状态、创建时间（日期范围，可以直接点"今天""最近 7 天""最近 30 天"） |
| 新增、编辑 | 用户名、显示名、密码（只在新增时填）、所属部门、手机号、邮箱、性别、角色、岗位、启用状态、备注 |
| 用户详情 | 点用户名，右侧弹出详情：部门、联系方式、角色、岗位、最后登录时间等 |
| 启用状态 | 在列表里直接切换。停用后，这个用户所有的登录状态立即失效 |
| 更多 → 重置密码 | 见下文 |
| 更多 → 分配角色 | 见下文 |
| 导入、导出 | Excel 文件，见下文 |
| 删除、批量删除 | 删除后，这个用户的登录状态立即失效 |

规则：

* 用户名只能用字母、数字和 `_ . @ -`，最长 64 个字符。用户名、手机号、邮箱都不能和别人重复；
* 新增时密码可以留空，这时使用参数 `iam.user.initial_password`（新用户初始密码）。这个值在初始化数据库时随机生成，在终端里显示一次，之后可以在[参数设置](#参数设置)里修改。无论填没填，新用户**第一次登录都必须改密码**；
* 密码要符合密码策略（最小长度、字符类别），策略在[参数设置](#参数设置)里调整；
* 没有"修改"权限的人，看到的手机号和邮箱是打了掩码的（比如 `138****5678`），搜索栏里也没有"手机号"；
* 不能停用、删除自己的账号；
* 超级管理员的账号不能停用、删除，也不能去掉它的超级管理员角色；只有超级管理员能编辑它、重置它的密码；
* 自己的手机号要在[个人中心](#个人中心)修改（需要密码和短信验证码）。修改别人的手机号还需要"重置密码"权限，改完后对方的登录状态全部失效。设置别人的手机号和重置密码一样，要求你能分配这个用户的全部角色，见[重置密码](#重置密码)；
* 你只能看到和管理自己**数据范围**内的用户，"所属部门"也只能选范围内的部门。

### 重置密码

在 **更多 → 重置密码** 里给这个用户设一个新密码（同样要符合密码策略）。重置后：

* 这个用户所有的登录状态立即失效；
* 他下次登录时必须再改一次密码；
* 他的微信小程序绑定会被解除（见[安全基线](/features/security#认证与会话)）。

重置别人的密码就等于拿到了这个账号，所以除了"重置密码"权限，你还必须能把这个用户**当前持有的全部角色**（停用的也算）分配给别人，规则和[分配角色](#分配角色)一样。否则返回 403，提示"该用户持有你不能授予的角色：只有能授予这些角色的管理员才能重置其密码或修改其手机号"。所以只有"重置密码"权限的服务台角色，不能重置权限或数据范围比它大的用户。租户管理员只按它自己持有的权限点（和平台专属的权限点）判断，用户角色里停用菜单或套餐外菜单的权限点不会挡住它。详见[防越权授予](/features/permission#防越权授予)。

### 分配角色

**更多 → 分配角色** 会打开一个单独的页面（不在侧边栏显示），列出所有启用的角色（超级管理员角色只对超级管理员列出），勾选后保存。

* 用户已有、但已停用的角色不会列出，保存时**原样保留**，页面上会提示有几个；
* 列表不按你的权限过滤：新勾选的角色不能超出你自己的权限和数据范围，否则保存失败，见[防越权授予](/features/permission#防越权授予)；用户原来就有的角色继续勾着不受这个限制；
* 修改在对方的下一次请求时生效，对方不用重新登录。

在用户的新增、编辑弹框里选角色，规则也一样。

### 导入导出

* **导出**：导出当前筛选条件下的全部用户（不分页）。手机号和邮箱的掩码规则和列表一样。部门一列是"部门编号 - 部门路径"；
* **导入**：先点"下载导入模板"，填好后上传 `.xlsx` 文件。模板里的部门、性别、启用状态都是下拉框，部门只列出你范围内启用的部门；
* **导入方式**："仅新增"，或者"新增并更新已有记录"（按用户名匹配，只匹配你数据范围内的用户；范围外的同名用户会作为重复数据失败）；
* **不导入**角色、岗位和密码：新用户使用初始密码，导入后再在页面上分配角色；
* 一行失败不影响其他行，失败的行可以"下载错误报告"；
* 默认单个文件不超过 10 MB、5000 行、100 列，可以在参数设置里修改（`excel.import_max_mb`、`excel.import_max_rows`、`excel.import_max_columns`）。

## 角色管理

**系统管理 → 角色管理**

角色是一组权限的集合，比如"财务"、"客服"。给用户分配角色，用户就拥有了这些权限。

| 操作 | 说明 |
| --- | --- |
| 搜索 | 角色名称、角色编码、启用状态 |
| 新增、编辑 | 角色名称、角色编码、排序号、启用状态、备注。名称和编码都不能重复 |
| 启用状态 | 在列表里直接切换 |
| 更多 → 菜单权限 | 勾选这个角色能用的菜单和操作 |
| 更多 → 数据权限 | 设置这个角色的数据范围 |
| 更多 → 分配用户 | 管理这个角色下有哪些用户 |
| 导出 | Excel 文件 |
| 删除、批量删除 | 内置角色不能删除；已经分配给用户的角色不能删除，要先取消分配 |

新建的角色**没有任何菜单**，数据范围默认是"本部门"，保存后再设置菜单权限和数据权限。

### 菜单权限

弹框里是完整的菜单树（包括停用的菜单），上方有"父子联动"开关，以及全部展开、全部收起、全选、全不选。

* **打开父子联动**：勾选上级会带上它所有的下级；只勾选某个操作时，它所在的页面和目录会以半选状态一起保存；
* **关闭父子联动**：每个节点单独勾选。即使只勾了操作、没勾页面，拥有这个角色的人也能看到这个页面和它的目录（系统会自动带上已授权菜单的上级）；
* 联动开关的状态记在角色上，下次打开还是这样。

用户管理的"分配角色"、角色管理的"分配用户"、字典管理的"字典数据"是隐藏页面，它们的操作挂在对应的隐藏页面下面，展开就能看到。

### 数据权限

**数据范围**决定一个人能看到哪些部门的数据，有五种：全部数据、指定部门、本部门、本部门及下级、仅本人（含义见[权限 · 数据范围](/features/permission#数据范围)）。

* 选"指定部门"时，下面出现部门树，同样有"父子联动"开关；
* "全部数据"只有超级管理员能设置，其他人的下拉框里没有这一项；
* 部门树只列出你能看到的部门。角色已经选了、但你看不到的部门，保存时保持不变，页面上会提示有几个。

### 分配用户

**更多 → 分配用户** 打开一个单独的页面，上方显示角色名称、编码和数据范围，下面有两个标签页："已分配用户"和"未分配用户"。

* 可以按用户名或姓名搜索；
* 每行可以"分配"或"取消分配"，勾选多行后可以"批量分配"、"批量取消分配"；
* 只列出你数据范围内的用户。

### 初始角色和保护规则

| 角色 | 编码 | 说明 |
| --- | --- | --- |
| 超级管理员 | `root` | 内置角色，拥有全部权限，不受数据范围限制。不能删除、停用，编码不能改，没有"菜单权限"和"数据权限"可设；只有超级管理员能编辑它 |
| 注册成员 | `member` | 自助注册的用户默认得到这个角色（参数 `auth.signup.default_role_id`），数据范围"仅本人" |
| 员工 | `staff` | 普通员工的示例角色，数据范围"仅本人"，能用首页和流程审批中心 |

"注册成员"和"员工"不是内置角色，可以修改，也可以删除。不过"注册成员"默认就是注册默认角色，见下面的规则。

* 列表里"内置"为"是"的角色，不能删除，编码也不能修改；
* **防越权**：非超级管理员在这个页面做的每一项授权（菜单权限、数据权限、分配用户，以及把停用的角色重新启用），都不能超出自己的权限和数据范围，否则保存失败，提示"不能授予超出自己权限或数据范围的角色"；
* 当前的注册默认角色（参数 `auth.signup.default_role_id` 指向的角色，默认是"注册成员"），只有超级管理员能修改、删除、设置菜单权限和数据权限、分配用户；
* 修改角色后，拥有这个角色的用户在下一次请求时自动更新权限，不用重新登录。

开启[多租户](/features/multi-tenancy)后，每开通一个租户，都会在这个租户里建一个内置角色"租户管理员"（`tenant_admin`）：数据范围"全部数据"，权限固定为租户套餐的全部内容，不能停用、删除，也不能改菜单权限和数据权限。在本租户里，它可以像超级管理员一样把角色设为"全部数据"、分配这样的角色，但仍然只能授予自己有的权限。见[权限与数据范围 · 租户套餐与平台专属页面](/features/permission#租户套餐与平台专属页面)。

## 菜单管理

**系统管理 → 菜单管理**

菜单是一棵树，它决定侧边栏显示什么、每个页面里有哪些按钮权限。在角色里授权时，勾选的就是这些菜单。

![菜单管理列表](/screenshots/zh-menus.webp)

### 三种菜单类型

| 类型 | 作用 | 可以放在哪里 |
| --- | --- | --- |
| 目录 | 侧边栏里的一组菜单，本身不是页面。下面没有可显示内容的目录不会出现在侧边栏；只有一个可显示的下级时，默认不显示目录这一层，直接显示那个下级（见下面的"总是显示目录"） | 最顶层，或者目录下 |
| 页面 | 一个页面。放在另一个页面下面时是**隐藏页面**：不在侧边栏显示，只能从上级页面跳转过去（比如用户管理的"分配角色"） | 最顶层、目录下或页面下 |
| 操作 | 一个权限点（如 `iam.user.create`），控制按钮和对应的接口，也就是"按钮权限" | 只能在页面下 |

菜单类型新增后不能修改。弹框只显示当前类型用得到的字段。

### 页面的三种链接方式

| 链接方式 | 效果 | 项目里的例子 |
| --- | --- | --- |
| 页面路由 | 打开项目里的一个页面 | 大多数页面 |
| 内嵌网页 | 在后台的标签页里，用 iframe（在页面里嵌入另一个网页）显示"链接地址" | **系统工具 → 系统接口** |
| 外部链接 | 在浏览器的新标签页里打开"链接地址"，不占后台的标签 | **系统工具 → Element Plus 文档** |

链接地址只能以 `http://` 或 `https://` 开头，或者是本站的一个路径（比如 `/api/docs`）。

### 主要字段

| 字段 | 说明 |
| --- | --- |
| 上级菜单 | 只能选启用的、能放这种类型的菜单 |
| 菜单名称 | 显示的名称，也可以填翻译键（如 `menu.iam.user`）。另外可以分别填中文名称、英文名称，填了的优先显示 |
| 图标 | 从图标选择器里选 |
| 路由路径 | 浏览器地址栏里的路径。以 `/` 开头是完整路径，否则接在上级菜单的路径后面 |
| 视图组件 | 页面文件在前端 `src/views` 目录下的路径，如 `platform/iam/user/index` |
| 组件名 | 页面缓存要用到，必须和页面代码里声明的名字一致 |
| 路由名 | 每个菜单唯一。**目录必须填**，只能用小写字母、数字和连字符，会按路由路径自动填好；**保存后不能修改**，因为种子和代码生成器按它找到这个目录 |
| 权限点 | 操作必填，格式是 `<域>.<资源>.<动作>` |
| 显示 | 关闭后不在侧边栏显示，但页面仍然可以打开 |
| 缓存页面 | 在标签页之间切换时，保留页面的状态（比如查询条件和页码），见[路由与菜单 · 页面缓存](/core/web-router#页面缓存-keep-alive) |
| 总是显示目录 | 只有目录有这个开关，默认关闭。关闭时，如果这个人在目录下只能看到一个菜单，侧边栏不显示目录这一层，直接显示那个菜单（菜单没有图标时用目录的图标）；能看到两个以上时照常显示目录。打开后，即使只有一个下级，也保留目录 |
| 排序号 | 同一级的菜单按它从小到大排列 |
| 启用状态 | 停用后，这个菜单和它下面的所有菜单都不再生效 |

### 列表上的操作

* 按名称（也会匹配权限点和路由）、菜单类型、启用状态筛选；
* 全部展开、全部收起；
* **调整排序**：排序号变成输入框，改完点"保存排序"一次提交；
* 每一行有"编辑"、"新增下级"（目录下默认新增页面，页面下默认新增操作）、"删除"；
* 停用的菜单下不能新增；有下级的菜单不能删除；已经授权给角色的菜单也不能删除，要先在角色里取消授权；
* 层级不能无限深：系统把从最顶层一直到这个菜单自己的各级编号拼成一条"层级路径"，用来记录它在树里的位置，这条路径最长 512 个字符。新增或移动后会超过时（移动时，已经删除的下级也算在内），保存失败，提示"树的层级路径过长，请选择较浅的上级节点"；
* 新增、修改（只改名称、图标也算）、启用或停用、调整排序、删除菜单之后，所有在线用户在下一次请求时自动重新加载菜单和权限；
* **防越权**：非超级管理员只能填写自己拥有的权限点；启用、移动菜单这类会让某个权限对某个角色生效的修改，也按授权来检查。

::: tip 新页面一般不在这里手工建
代码生成器生成页面时，会同时生成它的菜单种子；手写的模块也建议用种子建菜单，这样换一个环境部署时菜单也在。见[种子与菜单](/core/seed#菜单和按钮权限)。
:::

## 部门管理

**系统管理 → 部门管理**

树形表格。初始数据是一家虚构的公司：总部下面有研发中心（平台组、产品组）、运营中心（客户支持组）、财务与行政部。

| 操作 | 说明 |
| --- | --- |
| 搜索 | 部门名称、启用状态 |
| 新增、新增下级、编辑 | 上级部门、部门名称、排序号、负责人、联系电话、邮箱、启用状态 |
| 全部展开、全部收起 | |
| 启用状态 | 在列表里直接切换 |
| 删除 | 有下级的部门不能删除 |

规则：

* 同一个上级下面，部门名称不能重复；
* 修改上级部门，就是把这个部门**连同所有下级**一起移过去；不能移到它自己或它的下级下面；
* 层级深度有上限，规则和[菜单](#列表上的操作)一样：新增或移动后层级路径超过 512 个字符时，保存失败，提示"树的层级路径过长，请选择较浅的上级节点"；
* 停用的部门下面不能新增或移入部门；还有启用的下级时不能停用；启用一个部门时，它停用的上级会一起启用；
* 还有用户的部门不能删除；
* **负责人**从你数据范围内的用户里选。工作流里"部门负责人"这类审批人，取的就是这里的负责人（见[工作流 · 审批人](/features/workflow#审批人)）；
* 你只能看到和管理自己数据范围内的部门，新建或移动后的部门也必须还在你的范围内；
* 移动部门也按[防越权授予](/features/permission#防越权授予)检查：新上级部门里持有"本部门及下级"角色的人从此能看到这个部门，这些角色的每项权限都不能超出你的范围，否则返回 403；
* 部门移动后，这些部门里的用户在下一次请求时自动更新数据范围。

## 岗位管理

**系统管理 → 岗位管理**

岗位就是职位。一个用户可以有多个岗位，在用户的新增、编辑弹框里选。初始数据有技术负责人、开发工程师、产品设计师、客服专员。

| 操作 | 说明 |
| --- | --- |
| 搜索 | 岗位编码、岗位名称、启用状态 |
| 新增、编辑 | 岗位编码、岗位名称、排序号、启用状态、备注 |
| 启用状态 | 在列表里直接切换 |
| 导出 | Excel 文件 |
| 删除、批量删除 | 已经分配给用户的岗位不能删除 |

* 编码和名称都不能重复；
* 停用的岗位不会出现在用户弹框的岗位下拉框里；
* 工作流的审批人可以按岗位指定。

::: info 生成器的样板
岗位管理的前后端代码完全由[代码生成器](/features/codegen)的"单表"模板生成，没有手工修改，适合对照着学习生成的代码。
:::

## 字典管理

**系统管理 → 字典管理**

字典就是**下拉框的选项表**：数据库里只存值（比如 `male`），页面上显示文字（"男"）。概念和开发用法见[字典](/core/dict)。这里分两层：字典，和每个字典里的字典数据。

![字典管理列表](/screenshots/zh-dicts.webp)

### 字典

| 操作 | 说明 |
| --- | --- |
| 搜索 | 字典编码、字典名称、启用状态 |
| 新增、编辑 | 字典编码、字典名称、多语言名称、启用状态、备注 |
| 字典数据 | 打开这个字典的选项列表 |
| 刷新缓存 | 见下文 |
| 导出 | Excel 文件 |
| 删除、批量删除 | 还有字典数据的字典不能删除 |

* 字典编码用点分隔，只能有小写字母、数字、下划线和点，以字母开头，比如 `iam.gender`。**新增后不能修改**，因为代码按编码引用字典；
* 停用一个字典后，页面上的下拉框里就没有它的选项了，标签显示原始的值。

### 字典数据

在字典的那一行点"字典数据"，打开这个字典的选项列表（一个隐藏页面，上方有"返回字典列表"）。

| 字段 | 说明 |
| --- | --- |
| 字典值 | 存进数据库的值，同一个字典里不能重复 |
| 字典标签 | 显示的文字。"多语言标签"可以按语言分别填写，优先显示 |
| 排序号 | 下拉框里的顺序 |
| 标签样式 | 在列表里显示成什么颜色的标签：主要、成功、信息、警告、危险。不选就显示为普通文字 |
| 样式类名 | 再给这个标签加一个自定义的 CSS 样式类（class） |
| 默认值 | 标记这一项是默认项。**每个字典最多只有一个默认项**，见下文 |
| 启用状态 | 停用的项不会出现在下拉框、单选框里；已经存了这个值的数据，在列表、详情和导出的 Excel 里只显示原始的值（比如 `male`），不再显示字典标签 |

::: warning 每个字典只能有一个默认项
数据库保证同一个字典里最多只有一项打开了"默认值"：

* 已经有默认项时，再把另一项设为默认（新增或编辑），保存会失败，提示"数据已存在，不能重复"，原来的默认项保持不变。要换默认项，先编辑原来那一项、关掉"默认值"保存，再打开新的那一项；
* 停用的项如果是默认项，仍然占着这个位置；删除之后才让出来；
* 几个人同时设置默认项，也只有一个能保存成功。

默认值只是一个标记，下拉框不会自动选中默认项。
:::

::: tip 内置字典可以放心改
初始化时自带的字典（比如性别、启用状态）也可以改名称、文字、顺序、标签样式和默认值，重新执行种子不会把它们改回去，你删除的项也不会再出现。反过来，以后的版本如果修正了某个已有内置项的文字或样式，要靠数据迁移才能改到已经部署的系统里；没有的话，需要时自己在这里改。
:::

### 缓存

字典读取时有缓存（把常用数据暂存在内存数据库 Redis 里，读起来更快）：

* 在页面上修改字典或字典数据后，服务端的缓存立即失效，你自己的浏览器也马上用新数据；其他已经打开后台的人，刷新页面后看到新内容；
* 直接改了数据库、执行了数据迁移，或者重新执行了种子，点"刷新缓存"让所有字典重新读取。

## 参数设置

**系统管理 → 参数设置**

参数是管理员可以在线修改的配置，比如登录失败几次后锁定、上传文件的大小上限。保存后**立即生效**，不用重启服务。参数和环境变量的区别见[参数设置（开发指南）](/core/param)。

| 操作 | 说明 |
| --- | --- |
| 搜索 | 参数键、参数名称、分组、内置 |
| 新增、编辑 | 参数键、参数值、参数名称、多语言名称、分组、敏感、登录前可读、备注 |
| 刷新缓存 | 直接改了数据库或重新执行种子之后，点它让新值马上生效 |
| 导出 | Excel 文件 |
| 删除、批量删除 | 内置参数不能删除，列表里也不能勾选 |

* 参数键只能用小写字母、数字、下划线和点，以字母开头，比如 `storage.max_size_mb`。**新增后不能修改**；
* 参数值都是文字，最长 16383 个字符，可以为空。数字类的参数填了不是数字或超出范围的值时，系统按默认值处理；
* 参数值不会写进操作日志（不管是不是敏感参数）；
* 注册相关的参数（`auth.signup.enabled`、`auth.signup.default_role_id`、`auth.signup.default_dept_id`）、微信小程序登录开关 `auth.wx_mp.enabled`、日志保留天数 `audit.retention_days` 和智能体接入的急停 `mcp.paused`，只有超级管理员能修改，见[权限 · 只有超级管理员能做的事](/features/permission#只有超级管理员能做的事)。

### 参数的几种标记

| 标记 | 含义 |
| --- | --- |
| 内置 | 初始化时创建、代码会读取的参数。不能删除，也不能修改"登录前可读" |
| 敏感 | 值只显示为 `******`，列表、详情、导出都一样。编辑时不改就保留原值，输入新值就替换。只能在新增时设置；敏感参数不能设为登录前可读 |
| 登录前可读 | 没有登录也能读取。比如登录页要先知道验证码模式、是否开放注册 |
| 分组 | 用来分类和筛选。内置参数的分组一般是参数键的第一段，比如 `auth` |

### 内置参数

初始化后自带这些参数（按用途分组，键名和默认值的详细说明见各功能页）：

| 用途 | 参数 | 默认值 | 详见 |
| --- | --- | --- | --- |
| 登录、验证码、注册、密码策略、短信验证码 | `captcha.*`、`auth.*`、`iam.password_*`、`sms.otp.*` 共 18 个 | 滑块验证码、失败 5 次锁定 10 分钟、密码至少 8 位…… | [登录与账号 · 相关参数](/features/login#相关参数) |
| 新用户初始密码 | `iam.user.initial_password`（敏感） | 初始化时随机生成 | [用户管理](#用户管理) |
| 默认时区 | `core.default_timezone` | `Asia/Shanghai` | |
| Excel 导入上限 | `excel.import_max_mb`、`excel.import_max_rows`、`excel.import_max_columns` | 10 MB、5000 行、100 列 | [Excel 导入导出](/core/excel#导入限制) |
| 日志 | `audit.retention_days`（保留天数）、`audit.http_trace.mode`（API 访问日志记录哪些请求）、`audit.http_trace.exclude_paths`（不记录的路径） | 180 天、`write`（只记写操作） | [操作日志](/core/action-log) |
| 文件上传 | `storage.max_size_mb`、`storage.allowed_exts` | 20 MB、常见文件类型 | [文件管理](/features/storage#两个参数) |
| 记住授权天数 | `oauth.consent_ttl_days`（0 表示每次都询问） | 30 天 | [单点登录 · 记住授权](/features/oauth#记住授权) |
| 微信订阅消息 | `notify.wx_subscribe.enabled`（开关）、`notify.wx_subscribe.templates`（按通知编码配置的模板） | 关闭；预置了新待办提醒的模板配置，模板 ID 为空 | [消息中心 · 微信订阅消息](/features/messaging#微信订阅消息) |
| App 更新 | `app.update.enabled`（开关）、`app.update.review_version`（审核中的原生版本） | 关闭、空 | [App 版本](#app-更新的两个参数) |
| 智能体接入急停 | `mcp.paused`（`true` 时所有 MCP 工具调用立即被拒绝，只有超级管理员能改） | `false` | [MCP 智能体接入](/features/mcp#打开开关) |

## App 版本

**系统管理 → App 版本**

可以在这里给员工手机 App（安卓、iOS）发布新版本。App 每次启动时问一次服务端有没有新版本，有就弹窗提示更新。这个功能**默认关闭**，要先打开参数 `app.update.enabled`，见[下文](#app-更新的两个参数)。

| 操作 | 说明 |
| --- | --- |
| 搜索 | 平台、包类型、版本号、强制更新、发布状态、创建时间 |
| 新增、编辑 | 见下表 |
| 发布状态 | 在列表里直接切换。关闭就是**撤回**这个版本，App 不再收到它 |
| 删除、批量删除 | |

| 字段 | 说明 |
| --- | --- |
| 平台 | 安卓或 iOS |
| 包类型 | **资源热更新包**（wgt）：只更新页面和脚本，App 里下载、安装后自动重启；**整包**：安卓填安装包或应用市场的链接，iOS 填 App Store 的链接，App 用浏览器或商店打开 |
| 版本号 | 1–4 段数字，用点分隔，比如 `1.2.0`。同一个平台的同一个版本号只能有一条记录 |
| 最低原生版本 | **只对资源热更新包有效**：手机上装的整包版本低于它时，收不到这个热更新包。空表示不限 |
| 下载地址 | 只接受 `https://` 开头的地址 |
| 强制更新 | 打开后，提示框里没有"稍后" |
| 更新说明 | 提示框的正文。不填时显示"新版本已发布，建议立即更新。" |
| 发布状态 | 新增时默认打开：参数开着的话，保存后 App 下次启动就会收到 |

版本号按段比较数字：`1.2` 等于 `1.2.0`，`1.10` 比 `1.9` 新。平台和包类型的选项来自两个字典："App 平台"（`settings.app_platform`）和"App 更新包类型"（`settings.app_package_kind`）。

::: warning 新增和修改权限等于发布代码
有"新增"或"修改"权限（`settings.appVersion.create`、`settings.appVersion.modify`）的人，可以给所有装了 App 的手机下发代码（热更新包）。只把这两个权限给负责发版的人。
:::

### App 怎样检查更新

* 只有安卓和 iOS 的 App 检查，每次启动时一次。手机浏览器（H5）不检查；微信小程序由微信自己在冷启动时更新；
* App 把平台、当前的资源版本（装过热更新包时是它的版本，没装过时就是整包的版本）和原生版本（整包的版本）发给服务端。这是一个不用登录的公开接口 `GET /api/settings/app-versions/latest`，每个 IP 每分钟最多 60 次；
* 服务端在这个平台**已发布**的版本里，找出比当前资源版本高的，取最高的一个。热更新包还要满足两条：手机的原生版本不低于"最低原生版本"，并且不是正在商店审核的那个原生版本；
* 符合条件的版本里只要有一个是强制更新，这次提示就是强制的：跳过一个强制版本也躲不掉；
* 提示框的标题是"发现新版本 1.2.0"这样，按钮是"立即更新"和"稍后"。热更新包显示"正在下载更新…"，装好后 App 自动重启；整包在安卓上用浏览器下载安装包，在 iOS 上打开 App Store；
* 强制更新时，下载或安装失败（提示"更新失败，请稍后重试"）、从浏览器或商店返回 App 后，提示会再次弹出；
* 版本不比当前高、或者不属于这个 App 的热更新包，手机会拒绝安装；
* 检查失败（比如没网）时什么都不提示，App 照常使用。

接口和 App 端的完整说明见仓库的[移动端文档](https://github.com/732124645/qiwu-vue-admin/blob/main/docs/mobile.md#app-版本更新)。

### App 更新的两个参数

都在[参数设置](#参数设置)里修改，立即生效：

| 参数键 | 参数名称 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `app.update.enabled` | App 热更新与版本提示 | `false` | 关闭时服务端一律回答"没有新版本"，App 不提示 |
| `app.update.review_version` | 审核中的原生版本 | 空 | 把新的整包提交到应用商店审核之前，填上它的版本号：审核期间这个版本收不到热更新包，其他版本照常更新，整包照常提示。审核通过后清空。填的不是合法的版本号时，服务端忽略它 |

::: tip 什么时候必须发整包
改了原生层（比如新增模块或权限、升级 uni-app 或 HBuilderX）必须发整包。之后的热更新包要把"最低原生版本"填成这个整包的版本，否则旧的整包装上新的资源会出错。
:::

## 地区管理

**系统管理 → 地区管理**

一个页面，三块内容：

| 区块 | 说明 |
| --- | --- |
| 行政区划 | 全国省、市、区县三级树，每个节点显示名称和 6 位区划代码，点开一级显示一级。数据随项目提供（来自开源数据集），只读，名称只有中文 |
| IP 归属地查询 | 输入一个 IPv4 或 IPv6 地址，查出国家、省份、城市和运营商。需要"浏览"权限 `geo.area.browse` |
| 地区选择器 | 演示表单里用的省市区选择组件，选中后显示它保存的值（区划代码路径）。[表单设计器](/features/formkit)里的"地区选择"用的就是它 |

::: info IP 数据要单独下载
IP 归属地用的数据文件（约 11 MB）不在仓库里，要下载一次，见[快速开始 · 可选：IP 归属地数据](/guide/getting-started#可选-ip-归属地数据)。没有这个文件，或者查的是 IPv6 地址、内网地址时，结果显示"未知"。在线用户列表里的"登录地点"一列，以及登录日志、操作日志详情里的"登录地点""操作地点"，用的也是这份数据。
:::

## 通知公告

**系统管理 → 消息中心 → 通知公告**

管理员撰写公告，所有登录用户在右上角的铃铛里看到。

| 操作 | 说明 |
| --- | --- |
| 搜索 | 标题、类型、已发布、创建时间 |
| 新增、编辑 | 标题（最多 200 个字）、类型（通知、公告）、正文（富文本编辑器） |
| 已发布 | 列表里的开关：打开就是发布，关闭就是撤回，需要"发布"权限。新建的公告是草稿 |
| 已读用户 | 谁读过这条公告、什么时候读的（只列出你数据范围内的用户） |
| 删除、批量删除 | 已读记录一起删除 |

发布、撤回后铃铛怎样刷新，以及读者那边怎么看，见[消息中心 · 通知公告](/features/messaging#通知公告)和[铃铛](/features/messaging#铃铛)。

## 客户端管理

**系统管理 → 客户端管理**

本系统可以作为**单点登录**（OAuth2）的提供方：别的系统（第三方应用）把用户带到本系统的授权页，用户登录并同意后，第三方应用就能拿到令牌，读取这个用户的基本资料。每个要接入的第三方应用，先在这里登记成一个**客户端**。用户看到的流程见[单点登录（OAuth2）](/features/oauth)，第三方应用的开发者看[OAuth2 接入指南](/reference/oauth2)。

| 操作 | 说明 |
| --- | --- |
| 搜索 | 客户端标识、客户端名称、是否启用 |
| 新增、编辑 | 见下表 |
| 是否启用 | 在列表里直接切换。停用会立即结束这个客户端的全部会话，见[停用和删除](#停用和删除) |
| 重置密钥 | 生成新的客户端密钥，见[客户端密钥](#客户端密钥) |
| 删除、批量删除 | 同样立即结束全部会话 |

列表显示客户端标识、客户端名称、授权方式、内置、是否启用和创建时间。

| 字段 | 说明 |
| --- | --- |
| 客户端标识 | 第三方应用的 `client_id`。3–64 个字符，只能用小写字母、数字和 `. _ -`，以字母或数字开头，不能和现有的客户端重复。**新增后不能修改**。`console` 和 `mobile` 是系统保留的标识，不能使用 |
| 客户端名称 | 显示在授权同意页上，最多 64 个字符 |
| 图标 | 选填。上传一张图片，显示在授权同意页上 |
| 授权方式 | 多选：授权码、刷新令牌、客户端凭证，至少选一项；新增时默认选授权码和刷新令牌。选了刷新令牌，必须同时选授权码 |
| 回调地址 | 用户同意或拒绝后跳回第三方应用的地址。输入一个地址后按**回车**添加，最多 10 个；选了授权码时至少要有一个。必须是 `https://` 地址，本机调试可以用 `http://localhost` 或 `http://127.0.0.1`（可以带端口）；不能含 `#`、`*`、空白、反斜杠或用户名密码，也不能重复。授权时逐字比对，多一个结尾的 `/` 也算不同 |
| 授权范围 | 第三方应用能申请的权限。目前只有一项"读取你的基本资料（用户名、姓名、头像）"，新增时默认勾选；选了授权码时必须勾选。只选客户端凭证时也要勾选，否则申请令牌会失败 |
| 自动授权范围 | 只能从授权范围里选。这里勾选的范围不用用户同意，同意页上也不出现；从授权范围里去掉的，这里也自动去掉 |
| 访问令牌有效期（秒） | 300–86400，默认 1800（30 分钟）。到期就失效，用的时候也不延长 |
| 刷新令牌有效期（秒） | 3600–2592000，默认 604800（7 天），最长 30 天。选了刷新令牌时，它也是一次授权最长能用多久：从第三方应用用授权码换到令牌时算起，换新令牌也不会延长。没选刷新令牌，或者用客户端凭证申请的令牌，到访问令牌有效期就结束 |
| 是否启用 | 默认启用 |

授权方式、令牌和会话的含义见[单点登录 · 客户端管理](/features/oauth#客户端管理)和[单点登录 · 会话和令牌](/features/oauth#会话和令牌)。

### 客户端密钥

第三方应用换取令牌时要用客户端标识加**客户端密钥**。密钥由服务端随机生成（256 位），服务端只保存它的摘要，所以**只显示一次**：

* 新增保存后，弹出"保存客户端密钥"对话框，提示"密钥只显示这一次，请立即保存；丢失后只能重置"。对话框里有客户端标识和客户端密钥，右边各有一个复制图标按钮。按 Esc 不会关掉它，保存好之后点"我已保存"；
* 之后在页面、接口和日志里都看不到这个密钥；
* 密钥丢了，或者怀疑泄露了，在列表里点"重置密钥"，确认后生成一个新的，同样只显示一次。旧密钥立即失效，用它的应用要换上新密钥；已经发出的令牌不受影响。3 秒内重复重置会被拒绝；
* 重置密钥也记一条操作日志，动作是"重置密钥"。

### 停用和删除

* 停用或删除一个客户端（包括批量删除），它的**全部会话立即结束**：用户授权的和用客户端凭证申请的都算，第三方应用手里的令牌全部失效。重新启用也不会恢复，用户要重新授权；
* 删除时，用户对它的"记住授权"也一起作废。删除后可以用同一个客户端标识重新登记，新登记的客户端不会继承旧的会话和授权；
* 列表里有一个**内置**客户端 `console`，名称是"管理后台"，代表后台自己。它只读：不能勾选，编辑、重置密钥、删除和启用开关都不可用。

第三方应用的会话也会出现在 **系统监控 → 在线用户** 里，可以单独强退，见[监控与日志 · 第三方应用的会话](/features/monitor#第三方应用的会话)。用户同意过一次后，多少天内不用再同意，由参数 `oauth.consent_ttl_days` 决定（默认 30 天，0 表示每次都询问），见[单点登录 · 记住授权](/features/oauth#记住授权)。

## 个人中心

点右上角头像 → **个人中心**。每个登录用户都能用，不需要在角色里授权。

左边显示头像、显示名、用户名，以及只读的部门、角色、岗位。右边有几个标签页：

| 标签页 | 能做什么 |
| --- | --- |
| 基本资料 | 修改显示名、手机号、邮箱、性别，更换头像（先裁剪成正方形）。用户名不能改；改手机号要验证当前密码和新号码的短信验证码 |
| 修改密码 | 输入旧密码和两次新密码。改完后，你在其他设备和浏览器上的登录全部失效，微信小程序的绑定也会解除 |
| 偏好设置 | 界面语言。保存在账号上，系统发给你的通知和导出的文件也用这个语言 |
| 账号绑定 | 查看和解绑微信小程序。只在开启了微信小程序登录、或者账号还有绑定时显示 |
| 访问令牌 | 创建和吊销给智能体用的个人访问令牌，创建时要输入当前密码，令牌只显示一次。只在打开智能体接入（`APP_MCP`）时显示，见[MCP 智能体接入](/features/mcp#个人访问令牌) |

每一项的细节（手机号的验证步骤、头像格式、解绑的影响）见[登录与账号 · 个人中心](/features/login#个人中心)。

## 权限点一览

在 **系统管理 → 角色管理 → 菜单权限** 里，每个页面下面能勾选的操作如下（权限点是什么，见[权限 · 权限点](/features/permission#权限点)）：

| 页面 | 权限点前缀 | 操作 |
| --- | --- | --- |
| 用户管理 | `iam.user` | 浏览 `browse`、查看 `view`、新增 `create`、修改 `modify`、删除 `remove`、导出 `export`、导入 `import`、重置密码 `reset-password`、分配角色 `assign-roles` |
| 角色管理 | `iam.role` | 浏览、查看、新增、修改、删除、导出，授权 `grant`（菜单权限和数据权限）、分配用户 `assign-users` |
| 菜单管理 | `iam.menu` | 浏览、查看、新增、修改、删除 |
| 部门管理 | `iam.dept` | 浏览、查看、新增、修改、删除 |
| 岗位管理 | `iam.position` | 浏览、查看、新增、修改、删除、导出 |
| 字典管理 | `settings.dict` | 浏览、查看、新增、修改、删除、导出 |
| 字典数据 | `settings.dictEntry` | 浏览、查看、新增、修改、删除、导出 |
| 参数设置 | `settings.param` | 浏览、查看、新增、修改、删除、导出 |
| 地区管理 | `geo.area` | 浏览（IP 归属地查询） |
| 通知公告 | `messaging.bulletin` | 浏览、查看、新增、修改、删除，发布 `publish` |
| App 版本 | `settings.appVersion` | 浏览、查看、新增、修改、删除 |
| 客户端管理 | `oauth.client` | 浏览、查看、新增、修改、删除，重置密钥 `reset-secret` |
| 租户管理 | `iam.tenant` | 浏览、查看、新增、修改，进入租户 `enter`、重置初始密码 `reset-password` |
| 租户套餐 | `iam.tenantPackage` | 浏览、查看、新增、修改、删除 |
| MCP 工具 | `mcp.tool` | 浏览、修改（停用或启用工具） |
| 访问令牌 | `mcp.token` | 浏览，吊销 `revoke` |

几个容易忽略的地方：

* "编辑"按钮要同时有"修改"和"查看"；
* 字典和参数的"刷新缓存"需要"修改"；
* App 版本的"发布状态"开关和客户端的"是否启用"开关需要"修改"，没有时只显示状态；
* 通知公告的"已读用户"需要"查看"；
* 用户的"分配角色"需要"分配角色"和"查看"；
* App 版本的"新增"和"修改"可以给所有手机下发代码，见 [App 版本](#app-版本)。

## 开发指南

* [在代码中使用权限与数据范围](/core/permission)：权限常量、保护接口、给实体加数据范围
* [种子与菜单](/core/seed)：用种子预置菜单、按钮权限和隐藏页面
* [路由与菜单](/core/web-router)：菜单怎么变成前端路由，页面缓存、内嵌网页、外部链接
* [字典](/core/dict)、[参数设置](/core/param)：在代码里定义和读取字典、参数
* [Excel 导入导出](/core/excel)：导入模板、导入方式和限制
* [列表页](/core/crud-list)、[表单弹框](/core/crud-form)：这些页面共用的列表和弹框
* [富文本](/core/richtext)、[操作日志](/core/action-log)

相关功能：[权限与数据范围](/features/permission)、[登录与账号](/features/login)、[消息中心](/features/messaging)、[文件管理](/features/storage)、[工作流](/features/workflow)、[表单设计器](/features/formkit)、[代码生成器](/features/codegen)、[安全基线](/features/security)、[国际化](/features/i18n)、[实时推送](/features/realtime)。第一次接触后台，可以先跟着[逛一逛后台](/beginner/admin-tour)动手试一遍权限。
