owl-admin 权限子系统使用手册

owl-admin 权限子系统使用手册

owl-admin 是 Owl 框架上的后台子系统，提供用户、角色、菜单、接口权限、部门、字典、日志等能力。其中最容易让人困惑的是权限：登录之后，一个请求要经过哪些判断？菜单上的按钮权限从哪里来？给角色分配菜单后，为什么用户还是 403？

这套手册只讲权限子系统，从模型到操作再到二次开发，按顺序读即可。

先看全貌

Owl Admin 的权限体系可以概括成一条链：

用户 ──多对多──> 角色 ──多对多──> 菜单（页面 + 按钮）
                                      │
                                      └── 按钮携带权限标识
角色 ──Casbin policy──> 权限标识
用户 ──Casbin grouping──> 角色

请求进来时：

Authorization: Bearer <token>
        ↓
解析 JWT，得到用户与是否超管
        ↓
按方法 + 路径查运行时路由表
        ↓
读取 AccessLevel
        ↓
公开 / 仅登录 / 需授权（Casbin）/ 仅超管

核心结论：接口权限由「菜单分配」驱动。给角色分配了某个按钮菜单，角色才会获得该按钮携带的权限标识；用户又被分配了该角色，Casbin 才允许访问对应接口。

章节导航

顺序	章节	读完你能做到
1	权限模型总览	说清用户、角色、菜单、路由、Casbin 的关系
2	登录与 JWT	拿到令牌，理解令牌里有什么
3	访问级别	知道四种级别各自校验什么
4	权限标识与路由	能算出任意接口的权限标识
5	菜单与角色授权	在后台完成一次完整的授权
6	权限计算与生效	理解「我的菜单」「我的权限」和生效时机
7	前端权限控制	在页面上正确隐藏按钮
8	新模块接入与排查	给新业务模块接上权限并定位 403

涉及的主要代码

能力	位置
权限中间件	owl-admin/app/middleware/permission_check.go
路由注册与访问级别	owl-admin/app/route/api.go
权限引擎 Provider	owl/provider/permission/casbin.go
路由表与权限标识	owl/provider/router/router.go
菜单与权限推导	owl/provider/router/menu.go
角色授权	owl-admin/app/service/role_service.go
用户与登录	owl-admin/app/service/user_service.go
事件同步 Casbin	owl-admin/app/listener/listener.go

读之前需要准备

• 一个能启动的 owl-admin；
• 能登录的超管账号（配置在 conf/app.yaml 的 admin.username / admin.password）；
• 会用 curl 或接口调试工具；
• 最好再准备一个普通用户，用来验证权限（超管会绕过所有限制，只测超管等于没测）。

一句话记住

菜单是权限的载体，角色是权限的集合，用户通过角色获得权限；超管不在体系内，直接放行。