• 后端
• 前端
• 认证鉴权
• 代码生成
• 移动开发

🔐FastapiAdmin是一款完全开源、免费使用的中后台快速开发平台，内置基于RBAC（基于角色的访问控制）的完整权限体系：从菜单级控制"能看到什么页面"、按钮级控制"能执行什么操作"，到数据级控制"能查到哪些数据"，三级权限一次配置到位。本教程带你从零走通 FastapiAdmin 权限管理的全流程，让新手也能快速搭建出安全、专业的后台系统。

为什么中后台系统必须做好权限管理？

一个多人协作的中后台系统，至少需要回答三个问题：

FastapiAdmin 的权限体系正是围绕这三层设计的，且前端拦截 + 后端强校验双保险——即使有人绕过界面直接调接口，后端同样会拒绝无权限的请求。

RBAC 权限模型：用户、角色、菜单三者如何关联？

FastapiAdmin 采用经典的 RBAC 模型，核心关系是：用户 ←→ 角色 ←→ 菜单（权限），通过三张关联表串联：

• 用户角色关联表sys_user_roles：一个用户可绑定多个角色
• 角色菜单关联表sys_role_menus：一个角色可授权多个菜单/按钮
• 角色部门关联表sys_role_depts：配合数据权限使用

模型定义可参考 role/model.py 与 user/model.py。简单说：你不需要给每个用户单独配权限，只要配好角色，把用户分进角色即可——这也是 RBAC 最实用的地方。

权限链路解析：从登录到接口校验的完整流程

理解这条链路，你就看懂了整个权限系统：

第 1 步：登录时装配权限。用户登录后，系统遍历其所有启用状态的角色的菜单，把菜单 ID 和权限标识（permissions）收集起来，存入 Redis 会话。核心逻辑见 auth/service.py 的_collect_permissions方法。

第 2 步：每次请求校验身份与权限。每个请求携带 Token，框架通过 dependencies.py 中的AuthPermission类完成鉴权：超管直接放行；普通用户则检查请求所需的权限标识是否在自己拥有的权限集合里，否则返回"无权限操作"。权限数据结构定义在 base_schema.py 的AuthSchema（含permissions与menu_ids两个字段）。

第 3 步：前端按权限渲染菜单与按钮。后端返回的菜单树由 MenuProcessor.ts 转换为前端动态路由——没有被授权的菜单，侧边栏根本不会出现，路由也没法访问。

这套"登录装配 → 请求鉴权 → 前端渲染"的闭环，就是 FastapiAdmin RBAC 权限管理的骨架。

菜单权限配置：四种菜单类型的正确用法

在 menu/model.py 中，菜单被定义为 4 种类型，按钮就是"不挂路由的菜单"，这是理解按钮级权限的关键：

权限标识采用统一的三段式命名：模块:资源:动作，如module_system:role:delete表示"系统模块-角色资源-删除动作"。系统的初始菜单与权限标识可通过 SQL 脚本 sys_menu.json 查看，新增功能时建议沿用该规范，保持全局一致。

角色管理实操：创建角色并分配菜单权限

配置流程非常简单，只需两步：

① 创建角色：进入"系统管理 → 角色管理"，填写角色名称（如"部门经理"）、角色编码（字母开头，如dept_manager），并可同时设置数据权限范围（下文详述）。

② 角色授权：在角色列表点击"授权"，打开的授权面板由 role/schema.py 的RolePermissionSettingSchema定义，包含三个核心字段：

• menu_ids：勾选该角色可见的菜单树（目录、页面、按钮全部在这里勾选）
• data_scope：该角色的数据权限范围
• dept_ids：自定义场景下可访问的部门列表

对应接口为PUT /role/permission（role/controller.py）。💡小技巧：勾选按钮权限时记得展开到"按钮"层级——只勾页面不勾按钮，用户能进页面却没有任何可操作项，是新手最常踩的坑。

按钮级权限：前后端双重防护怎么落地？

按钮级权限的核心思想：前端负责"不显示"，后端负责"不放行"。

前端：FastapiAdmin 提供了v-hasPerm自定义指令（directives/permission/index.ts）。在 Vue 模板中给按钮加上权限标识，用户没有该权限时，按钮会被直接从 DOM 中移除：

指令内部统一委托checkPerm函数判断，该函数会校验超管身份、ROOT 角色、*:*:*通配符和具体权限标识（checkPerm.ts）。

后端：每个受控接口在控制器上都声明了所需权限，例如角色删除接口要求module_system:role:delete（role/controller.py）。即便攻击者绕过前端直接发请求，AuthPermission也会在鉴权阶段拦截。

这种双重防护意味着：你只需要在配置菜单时把按钮的权限标识写好，前后端会自动按同一套标识对齐，无需重复维护。

数据权限配置：三种范围精确控制可见数据

数据权限是 RBAC 进阶能力，由后端 permission.py 中的Permission类在查询 SQL 层面自动注入过滤条件，对业务代码完全透明。角色上只需选择一个范围：

几个值得注意的工程细节（都在 permission.py 中实现）：

• 超管跳过过滤：is_superuser用户直接放行，不附加任何条件；
• 降级保护：计算子部门树失败时，会安全降级为"仅本部门"范围并记录日志，宁可缩小范围也不静默扩大越权；
• 用户表特殊处理：查询用户列表时按dept_id直接过滤，而普通业务表按"创建人所在部门"关联过滤。

新手避坑指南与最佳实践

1. 先规划角色，再创建用户：按"岗位"而非"人"建角色（如 admin / dept_manager / staff），人员变动只需调整用户-角色绑定。
2. 权限标识先定规范：严格沿用模块:资源:动作三段式，与 sys_menu.json 中既有标识保持风格一致，避免前后端对不上。
3. 授权后让测试账号重新登录：权限集合在登录时写入会话，旧会话不会自动刷新，改完授权用新会话验证才准确。
4. 按钮权限别漏勾：页面能进但按钮全消失，90% 是授权时只勾了菜单没勾按钮节点。
5. 数据权限宁小勿大：子部门计算异常时系统会自动降级为"仅本部门"，配置时理解这一兜底逻辑，排查问题时心里有数。

写在最后

FastapiAdmin 的权限管理把 RBAC 的复杂性封装到了框架层：菜单即权限、角色即授权、数据范围即边界。你只要按"建菜单 → 建角色 → 勾权限 → 分用户"四步走，就能得到一套前后端双重防护、覆盖菜单/按钮/数据三级的完整权限体系。这套源码结构清晰、注释完善，非常适合作为学习 RBAC 权限设计的开源范本，也适合作为中后台项目的直接底座。

• 后端
• 前端
• 认证鉴权
• 代码生成
• 移动开发