权限链路详解
本页来自仓库 docs/permission-control-overview.md 的实践总结，覆盖“权限定义 → 菜单/按钮 → 角色 → 管理员缓存 → 中间件校验”全链路，适用于管理端（/manage）API。
TL;DR
- 新接口务必先在
permission/definitions注册，再在菜单按钮绑定同一permissionCode，否则会被中间件拒绝 - 权限匹配按 Method+Path 精准比对，未命中才回退按钮 API/菜单路由
- 管理员权限缓存默认 5 分钟，角色/管理员变更会自动失效
总览
- 权限注册：
server/app/permission/definitions/manage.js统一声明 code、method、path，并支持旧版module/action别名 - 装载：
server/app.js初始化PermissionRegistry，自动合并插件 definitions，白名单由config.permission.whiteList聚合 - 存储：菜单/按钮模型持久化按钮的
permissionCode + httpMethod + api，角色直接绑定按钮的permissionCode - 缓存：管理员权限聚合后写入缓存（默认 5 分钟），更新角色/管理员后自动失效
- 校验：
authAdminPower中间件按 Method+Path 精准匹配，未命中再回退到按钮 API/菜单路由
权限定义与注册表
- 位置：
server/app/permission/definitions/manage.js - 功能：声明
code + method + path，兼容aliases以适配旧按钮 - 注册：
server/app.js装载主应用 + 插件 definitions，写入PermissionRegistry - 白名单：
config.permission.whiteList（含插件扩展）→app.permissionWhiteList
核心接口（PermissionRegistry）：
register/getByCode/getByLegacyApi/match，匹配时同时校验 HTTP Method 与路由正则，避免不同 Method 混淆
菜单与按钮
- 模型：
server/app/model/menu.js的按钮字段携带desc/api/permissionCode/httpMethod - 校验：
server/app/validate/menu.js&MenuController.validateButtonSecurity拒绝危险 API，严格模式要求按钮绑定合法permissionCode - 关联查询：
MenuMongoRepository提供getButtonApis/getMenuButtonsWithPermissionCodes/getMenuRoutePaths
角色授权
- 角色保存时读取菜单按钮，直接存储按钮
permissionCode（controller/manage/role.js） - 校验规则：
server/app/validate/role.js要求按钮数组为字符串集合 - 更新/删除角色触发管理员权限缓存失效
管理员权限聚合与缓存
- 入口：
ctx.helper.getAdminPower（server/app/extend/helper.js） - 流程：读取管理员角色 → 提取菜单/按钮 → 结合
PermissionRegistry映射最终权限 → 写入缓存 - 缓存失效：管理员或角色变更时调用
invalidateAdminPowerCache*
请求期校验（authAdminPower）
- 顺序：会话校验/白名单 →
PermissionRegistry.match(Method+Path) → 按钮 API 严格匹配 → 菜单路由回退 - 安全：拒绝时输出安全日志，严格模式下按钮缺失权限会被拒绝
前端管理链路
- 菜单抽屉：
client/admin-center/src/views/manage/menu/modules/menu-operate-modal.vue录入按钮permissionCode/httpMethod - 权限树：
client/admin-center/src/views/manage/role/modules/menu-auth-modal.vue以按钮permissionCode作为树节点 ID - 类型/文案：
client/admin-center/src/locales与src/typings保持同步
建议
- 新增路由时同步更新
permission/definitions并在菜单按钮上绑定permissionCode - CI 中可增加 definitions 与路由比对脚本，提醒缺失的权限登记
常见问题 FAQ
新接口上线需要同步哪些文件？
在server/app/permission/definitions/manage.js注册permissionCode/method/path，管理端菜单按钮使用同一permissionCode，提交后刷新管理员权限缓存。如何排查权限匹配不到的情况？
先确认 HTTP Method 与路由是否与 definitions 一致，再检查按钮 API 是否携带permissionCode/httpMethod，最后查看authAdminPower日志中的匹配结果。插件的权限如何生效？
插件自带的 definitions 会在server/app.js装载时合并进PermissionRegistry，确保插件按钮同样绑定对应permissionCode即可。