跳转到内容
GitHub

用户 · 角色 · 部门 · 菜单

权限的基础是四张表、四个页面:部门组成一棵树,用户挂在一个部门上、可以有多个角色,角色勾选能用哪些菜单和按钮,菜单表同时决定侧边栏长什么样、每个按钮要什么权限码。这一页讲这四个页面怎么操作、各自有哪些限制;权限码和数据范围在服务端怎么判,见数据权限。

角色管理:功能权限矩阵
页面路径打开页面要其余权限码
系统管理 → 用户管理/system/usersys:user:del查看 sys:user:list · 导出 sys:user:export。新建、编辑、改权限、重置密码、重置二次验证、导入只给超级管理员
系统管理 → 角色管理/system/rolesys:role:add查看 sys:role:list · 编辑与增删角色用户 sys:role:edit · 改功能权限 sys:role:menu:edit · 改数据范围 sys:role:scope:edit · 删除 sys:role:del
系统管理 → 部门管理/system/deptsys:dept:add查看 sys:dept:list · 编辑 edit · 删除 del · 导入 sys:dept:import · 导出 sys:dept:export
系统管理 → 菜单管理/system/menusys:menu:add查看 sys:menu:list · 编辑 edit · 删除 del

⚠️ 「打开页面要」那一列是前端路由守卫目前认的权限码:四个页面认的都是新增或删除,不是「查询」。只授了查询的角色会被重定向到 403 —— 种子里的 MANAGER 角色有「用户管理」「部门管理」菜单和两个查询码,但没有 sys:user:del / sys:dept:add。E2E 里实测踩过(e2e/AGENTS.md:测试角色不绑「部门管理」那几个按钮,打开部门页就是 /403)。超级管理员不受路由守卫限制。

「超级管理员」和「后台管理权限」有什么区别?

Section titled “「超级管理员」和「后台管理权限」有什么区别?”

用户上有两个开关,在用户列表的「权限与安全」里改(只有超级管理员能改,不能改自己):

开关作用
超级管理员(is_superuser)跳过所有权限码和数据范围检查,侧边栏显示全部菜单
后台登录(is_staff)没有它,账号能登录、能看,但所有写操作(GET 以外的请求)都被拒绝,提示「用户已被禁止后台管理操作,请联系系统管理员」

只给超级管理员的接口要求两个都开。

⚠️ 新建和导入的用户,「后台登录」默认是关的,所以他们第一次登录后什么都保存不了,要超级管理员去打开。这个开关在界面上的说明是「关掉后账号仍在,但进不了这个系统」,实际上关掉之后照样能登录、能查看,只是不能做任何修改。

  • 新建:必须选部门,密码要符合密码规则,表单要求至少一个角色。一个用户只属于一个部门,可以有多个角色;保存时整组替换他的角色。
  • 停用 / 启用:用户只有「正常」「停用」两种状态。停用立即结束他的所有会话,他开着的页面当场回到登录页。
  • 锁定不是一种状态:密码连续输错 5 次锁 5 分钟(参数配置可改),到时间自动解开,界面上没有手动解锁。
  • 重置密码:只给超级管理员,不需要旧密码;新密码同样不能和最近几次相同;重置后他的所有会话结束。
  • 删除:可以多选批量删,逐条执行、哪几条失败会说出来。超级管理员那几行不能勾选。删除是逻辑删除(数据还在库里),但界面上没有恢复入口。
  • 手机号全局唯一;管理员改了某人的手机号,这个号的「已验证」标记会被清掉,他要在个人中心重新验证后才能用手机验证码登录。
  • 批量导入见导入导出:只给超级管理员,只能新增,初始密码来自 USER_IMPORT_DEFAULT_PASSWORD。

列表的部门筛选只匹配这一个部门,不含下级。

角色页左边是角色列表,右边三个页签:功能权限、数据范围、角色用户。

  • 角色编码:大写字母开头,只能是大写字母、数字、下划线,2–32 位,创建后不能改(代码里按编码认角色)。编码和名称都不能重复。
  • 功能权限是一棵菜单树,按钮收在所属菜单那一行右侧,显示「已授权 n/m」。两种勾选方式:
    • 节点关联:勾一个节点,连带勾上它的全部下级和所有上级。
    • 节点独立:只勾这一个。下级勾了、上级没勾时会提示,并给一个「一键补齐上级」。
    • 搜索框能按菜单名搜,也能按权限码搜。改动先是草稿,「保存」才生效,「还原」丢掉没保存的改动。要 sys:role:menu:edit 才能改。
  • 数据范围:给角色绑定数据范围。角色表单里还有一个「启用数据权限过滤」开关,关掉 = 这个角色看全部数据。规则怎么写见数据权限。
  • 角色用户:只增减「这个用户有这个角色」的关联,不动用户本身。移除会让某人一个角色都不剩时会提示。

删除角色是逻辑删除,删掉之后它不再给任何用户提供权限。

改了权限,对方要重新登录吗?

Section titled “改了权限,对方要重新登录吗?”

不用。角色的功能权限、数据范围、角色用户一改,受影响的人的权限缓存在事务提交后就清掉,后端从他的下一个请求起按新权限判。但浏览器里缓存的权限码和侧边栏不会自动刷新(没有实时推送),所以他要刷新一下页面才能看到新菜单、新按钮。E2E 实测过:解绑数据范围后,目标账号不重新登录、刷新即变。细节见数据权限。

  • 部门编码全局唯一、创建后不能改;名称只要求同级不重名。
  • 负责人必须是一个已启用的用户(只在改负责人时校验)。
  • 不能把部门挪到它自己或它的下级下面。
  • 部门下还有用户或下级部门时不能删;有下级时删除按钮直接是灰的。
  • 停用一个部门后,直接属于这个部门的用户再发请求会被拒绝(「用户所属部门已被锁定,请联系系统管理员」),会话本身不结束。
  • 部门树受数据范围约束:看的人只能看到自己范围里的部门。
  • 一份 xlsx 能建出整棵部门树,见导入导出。
类型侧边栏里必填
目录一个可展开的分组;没有可见的下级时变成普通链接,路径也无效就不显示路径
菜单一个页面;路径必须是前端真实存在的路由,否则不显示(控制台留一条警告)路径
按钮不显示,只承载权限码;一行可以写多个,用逗号隔开权限码
内嵌页在页签里用 iframe 打开一个外部地址(路由 /embedded/<名称>);只放行 http / https,页面上同时显示原地址和「在新标签页打开」地址
外链点击在新标签页打开地址

内嵌地址在 Web 端支持完整 HTTP(S) 地址和同源根相对路径(如 /help);桌面客户端需要完整 HTTP(S) 地址,打开相对地址菜单时会提示修改地址或使用 Web 端。外链始终需要完整 HTTP(S) 地址。

升级时请检查历史内嵌地址:help、./x、docs/a 等不以 / 开头的相对地址不再加载,保存时也会被拒绝。请先确认目标,再改成 /help、/x、/docs/a 等根相对路径,或改为完整 HTTP(S) 地址。

  • 菜单表单里的「路径」只能从前端已有的路由里选;「名称」只能是英文字母和数字、字母开头。
  • 隐藏(不在侧边栏显示)的菜单照样能按地址打开 —— 「个人中心」就是这样。
  • 停用一个目录,它下面整枝都失效:侧边栏里消失,权限码也一起不算数;重新启用就回来。超级管理员只是侧边栏里看不到,没加权限守卫的页面仍能按地址打开。
  • 菜单管理页会标出死链(「N 个死链」角标,可以只看死链):路径在前端找不到对应路由的菜单。按钮、外链、内嵌页不算;目录只要有一个可见的下级就不算。
  • 菜单标题:中文界面显示库里的标题;其他语言按路径查内置的翻译(menu:<路径>),所以在菜单管理里改了中文标题,英文界面不会跟着变。表单上有这条提示。
  • 不能把菜单挪到它自己的下级下面;有下级时不能删。

这四个页面的行为几乎都在界面上配。相关的配置项:

键在哪改默认值说明
USER_LOCK_THRESHOLD · USER_LOCK_SECONDS参数配置 →「口令与锁定」5 · 300连续输错几次、锁多少秒,见登录安全配置
USER_IMPORT_DEFAULT_PASSWORD.env空导入用户的初始密码;留空 = 用户导入关闭
RBAC_ROLE_MENU_MODE.envtrue权限码模式;false 是 casbin 模式,见数据权限
RBAC_ROLE_MENU_EXCLUDE.env[]列在这里的权限码跳过检查

从零加一个业务模块的第 7 步讲了两种做法:本地试验时直接在「菜单管理」里点出目录、菜单和按钮;要随代码发布的,把菜单行写进三种数据库的种子 SQL(ID 相同)、再写一条数据迁移,跑 pnpm seed:manifest --write,test_permission_codes.py 会核对后端守卫、前端 <Can perm> 和种子菜单里的权限码是否对得上。

  • 四个页面的前端路由守卫认的是新增 / 删除权限码,不是查询码,见上文。
  • 新建、导入的用户默认没有「后台登录」,第一次登录后什么都存不了;这个开关的界面说明和实际行为不一致,见上文。
  • 删除用户的确认框写着「不可撤销」,实际是逻辑删除,只是没有恢复入口。
  • 数据范围没有「本部门及所有下级」这种模板,见数据权限。

后端(apps/api/backend/app/admin/tests/):

浏览器端(Playwright):perm-matrix.spec.ts(保存只写到地址栏里点名的那个角色上;「还原」丢掉没保存的改动;节点独立模式的缺上级提示和一键补齐)、dept-crud.spec.ts(重复编码、编辑时编码不可改、同级不能重名、删不掉的部门)、menu-dead-link.spec.ts、menu-rename-disable.spec.ts(改内置菜单标题;停用目录整枝消失、重新启用回来)、data-permission.spec.ts(解绑数据范围后目标账号不重新登录,刷新即变)。

在线演示(admin / 123456):打开「系统管理 → 角色管理」,选一个角色,在「功能权限」里切换「节点关联 / 节点独立」看勾选的差别,搜一个权限码(如 sys:user:list)看它落在哪一行。「菜单管理」里能看到当前有没有死链。演示站是共用的,改了角色权限会影响所有用这个角色的演示账号,试完请「还原」。