Download the PHP package wiseadmin/wise-auth without Composer

wiseadmin/wise-auth

为 ThinkPHP 6 设计的通用 RBAC 权限管理包，支持多应用、多用户类型、角色继承（RBAC1）与职责分离约束（RBAC2 扩展）。

目录

• 核心特性
• 环境要求
• 安装
• 快速开始
• 核心概念
• 配置说明
• 使用指南
  • 用户模型接入
  • 权限检查
  • 角色管理
  • 中间件集成
  • 超级管理员
  • 角色继承（RBAC1）
  • 约束检查（RBAC2）
  • 数据权限
• 权限来源
• 事件系统
• 命令行工具
• 数据库表结构
• 目录结构
• 最佳实践
• License

核心特性

• 标准 RBAC — 用户 → 角色 → 权限 三层模型，清晰直观
• 多应用支持 — 通过多态关联支持 admin、member 等多种用户类型
• 角色继承（RBAC1） — 父子角色树，子角色自动继承父角色权限，支持无限层级与循环检测
• 职责分离约束（RBAC2 扩展） — 互斥角色、基数限制、前置角色三种内置约束规则
• 超级管理员机制 — 支持超级角色 slug 与超级用户 ID 列表两种方式
• 多来源权限加载 — 数据库 / 配置文件 / 注解三种权限定义方式
• 缓存优化 — 用户权限缓存，支持 Redis / 文件缓存，TTL 可配
• 路由自动匹配 — 中间件自动将路由映射到权限标识，支持黑白名单策略
• 事件驱动 — 角色/权限变更时自动清除缓存，支持业务侧自定义监听
• 灵活的错误处理 — 未授权时可选择抛出异常、重定向、JSON 响应或自定义处理器

环境要求

安装

1. 通过 Composer 安装

2. 初始化

安装完成后，执行初始化命令：

该命令会：

• 将配置文件 wise-auth.php 发布到项目的 config/ 目录
• 提示你执行数据库迁移
• 加载配置文件中权限并注册权限数据

3. 执行数据库迁移

将创建以下 4 张数据表：

快速开始

第一步：给你的用户模型加上权限能力

第二步：配置超级管理员（可选）

在 config/wise-auth.php 中：

第三步：在路由中使用中间件

第四步：在控制器中检查权限

核心概念

• 用户（User）：使用 HasRoles Trait 的模型实例，通过 user_type + user_id 多态关联到角色
• 角色（Role）：权限的集合，用 slug 唯一标识，支持父子继承
• 权限（Permission）：最小的授权单位，用 ident 唯一标识（如 admin.user.list），可关联路由、请求方法等

配置说明

完整配置文件位于 config/wise-auth.php，以下是所有配置项的详细说明：

用户模型

数据表

超级管理员

缓存

权限来源

中间件策略

未授权处理

角色继承

RBAC2 约束

数据权限

使用指南

用户模型接入

HasRoles Trait 提供以下方法：

HasRoles 还会自动注册 saved 和 deleted 模型事件，在用户信息变更时自动清除权限缓存。

权限检查

方式一：通过 Trait 实例方法

方式二：通过门面（静态调用）

方式三：模板中使用

角色管理

创建角色

赋予权限

获取角色树

返回格式示例：

检测循环继承

中间件集成

基础用法

在路由定义中注册中间件：

中间件会自动：

1. 从 Session（admin_id）或自定义解析器获取当前用户
2. 超级管理员直接放行
3. 检查当前路由是否在白名单中（白名单命中则跳过鉴权）
4. 将当前路由匹配到权限标识（如 /admin/admins/index → admin.admins.index）
5. 执行 checkAny（OR 模式）或 checkAll（AND 模式）
6. 根据 unauthorized_action 配置处理未授权情况

按路由指定权限

中间件注册

在 app/middleware.php 中注册中间件别名（TP8 仅支持静态配置）：

自定义用户解析器

当用户信息不在 Session 时（如使用 JWT）：

黑白名单策略

白名单模式（默认）：未匹配路由默认需要鉴权，白名单内路由可跳过。

黑名单模式：未匹配路由默认允许访问，黑名单内路由必须鉴权。

未授权处理

四种模式可选：

超级管理员

支持两种超管判断方式：

方式一：用户 ID 列表

全局生效，不受 user_type 影响。通常与项目 config('app.super_admin_ids') 保持一致。

方式二：超级角色 slug

拥有 super_admin 角色的用户自动拥有全部权限。此方式受 user_type 多态关联约束。

角色继承（RBAC1）

通过 parent_id 字段建立角色父子关系，子角色自动继承父角色的所有权限。

• 支持多层级继承（受 inheritance_max_depth 限制）
• 自动检测循环引用（cycle_check_enabled 开启时）
• 继承链通过 path 字段快速查询（如 0-1-3-7）
• 角色权限变更时自动清除所有受影响用户的缓存

约束检查（RBAC2）

内置三种约束规则，在 config/wise-auth.php 中配置：

互斥角色（mutual_exclusion）

某些角色不能同时分配给同一个用户：

基数限制（cardinality）

限制某个角色的最大用户数：

前置角色（prerequisite）

分配某角色前必须先拥有另一角色：

自定义约束检查器

需实现 \wise\auth\contract\ConstraintCheckerInterface 接口：

数据权限

通过 data_policy 配置行级数据过滤策略：

auth_user_role 表的 data_scope 字段支持为特定用户-角色关联附加数据范围（如部门 ID 列表）。

权限来源

WiseAuth 支持三种权限定义来源，可在 permission_sources 中组合使用：

数据库（database）

通过后台管理界面动态增删权限，数据持久化在 auth_permissions 表中。

配置文件（config）

在 wise-auth.php 的 permissions 节点定义：

注解（annotation）

在控制器方法的注释中声明：

扫描目录配置：

通过命令手动导入：

事件系统

WiseAuth 通过 ThinkPHP 事件系统提供了丰富的事件钩子：

触发事件

监听事件

或在 app/event.php 中订阅：

命令行工具

wise:auth:publish

初始化 WiseAuth，发布配置并注册权限。

wise:auth:import

从不同来源批量导入权限。

JSON 文件格式：

wise:auth:clear

清除权限缓存。

数据库表结构

auth_roles（角色表）

auth_permissions（权限表）

auth_role_permission（角色-权限中间表）

auth_user_role（用户-角色多态关联表）

唯一索引：(user_id, role_id)

目录结构

最佳实践

1. 权限标识命名规范

推荐使用点分格式，体现层级关系：

2. 缓存策略建议

• 开发环境：关闭缓存（cache_enabled => false），便于调试权限变更
• 生产环境：启用 Redis 缓存（cache_store => 'redis'），推荐 TTL 1 小时
• 权限变更后：触发 RoleChanged / PermissionChanged 事件，自动清除缓存

3. 路由通配符使用

权限的 route 字段支持 * 通配符：

4. 防范循环继承

5. 用户模型事件

HasRoles Trait 的 bootHasRoles 方法会在模型 saved/deleted 时自动清除缓存。如果需要在用户模型中定义自己的 boot 方法，务必调用 parent::boot() 或手动 static::bootHasRoles()。

6. 多用户类型场景

7. 与 WiseAdmin 框架集成

在 WiseAdmin 中，wise-auth 已作为核心依赖预装。默认用户模型指向 \app\admin\model\Admin::class，超管 ID 通常通过 config('app.super_admin_ids') 配置。

License

MIT License. 详见 LICENSE 文件。