---
url: /docs/3.0/server/permission.md
---
# CatchAdmin 权限管理

> 基于 RBAC 模型的权限系统介绍

CatchAdmin 采用业界成熟的 `RBAC`（基于角色的访问控制）权限模型，即用户一对多角色，角色一对多权限的设计。这种模式通过角色作为中间层，实现了灵活的权限分配和管理。

如果对 `RBAC` 权限模型需要深入了解，建议参考 [Oracle 官方文档：基于角色的访问控制](https://docs.oracle.com/cd/E19253-01/819-7061/rbac-38/index.html)。

## 基本约定

* **超级管理员免检**：超级管理员不受任何权限控制，拥有系统全部操作权限
* **GET 请求放行**：所有 `GET` 请求默认放行，不受权限限制（查询操作通常不涉及数据变更）

## 权限约定

## 权限模块

CatchAdmin 为保持系统轻量化，默认不开启权限模块和动态菜单功能。如果项目需要权限控制，第一步需要安装权限模块：

```php
php artisan catch:module:install permissions
```

:::info
开启之后如果没有权限菜单，可以刷新一下
:::

### 中间件

权限模块提供了权限控制的中间件，实现自动的权限验证：

```php title="modules/Permissions/Middlewares/PermissionGate.php"
class PermissionGate
{
    public function handle(Request $request, \Closure $next)
    {
        // GET 请求全部通过（遵循基本约定）
        if ($request->isMethod('get')) {
            return $next($request);
        }

        /* @var User $user */
        $user = $request->user(getGuardName());

        // 权限验证失败则拦截请求
        if (! $user->can()) {
            throw new PermissionForbidden();
        }

        return $next($request);
    }
}
```

### 添加权限

权限配置是系统的核心功能。由于 CatchAdmin 采用前后端分离架构，权限配置相比传统项目略为复杂，需要同时考虑前端路由和后端 API 的权限控制。

建议先熟悉 [Vue Router](https://router.vuejs.org/) 的基本概念。配置入口：**权限管理/菜单管理** → **新增**：

![pSl4dVP.png](https://s1.ax1x.com/2023/01/16/pSl4dVP.png)
CatchAdmin 将权限分为三种层级类型：

* **目录**：构建导航结构的一级菜单容器，用于功能分组

* **菜单**：对应具体的功能页面，关联前端路由组件

* **按钮**：页面内的具体操作功能，每个按钮对应后端控制器的一个 `action` 方法（这是后端权限控制的关键）

* 路由 `Path` 对应前端 `vue` 路由的 `path`

* 组件 对应前端 `vue` 路由的 `component`
  * 目录类型一般都是选择 Layout 组件
  * 菜单类型则是选择对应页面的组件

**前后端分离的权限控制特点**：

传统 Laravel 项目中，页面和数据都由 PHP 控制。CatchAdmin 采用前后端分离后：

* **前端负责**：页面渲染、菜单显示、路由跳转
* **后端负责**：API 接口访问控制、数据操作权限

因此，CatchAdmin 的 RBAC 权限重点在于**控制 API 访问**。后端需要为每个控制器的 `action` 方法配置对应的权限，确保数据操作的安全性。

### 权限判断

基于 CatchAdmin 的模块化架构，权限标识采用统一格式：

```
module@controller@action  // 模块名称@控制器名称@控制器方法名称
```

**示例说明**：权限模块的角色列表功能，位于权限模块(Permissions)的角色控制器(RolesController)的 `index` 方法，其权限标识为：

```php
Modules\Permissions\Http\Controller\RolesController@index
```

**权限验证失败排查**：当遇到权限认证失败时，通常是权限配置问题。请检查数据库 `permissions` 表中的配置：
![catchadmin 权限-laravel admin](https://image.catchadmin.com/202405220926755.png)
确认 `module` 和 `permission_mark` 字段是否符合 `module@controller@action` 的格式规则。

#### 当前用户是否有权限

```php
Auth::user()->can(string $permission = null);
```

* `$permission` 参数：权限标识，格式为 `module@controller@action`，例如 `Permissions@Roles@index`

#### 用户的权限

```php
/*@var Model\Roles $user*/
$user->withPermissions()->permissions;
```

#### 角色权限

```php
/*@var Model\Roles $role*/
$role->getPermissions()
```

## 取消权限中间件验证

下面是示例代码，使用`withoutMiddleware(\Modules\Permissions\Middlewares\PermissionGate::class)`

```php
Route::withoutMiddleware(\Modules\Permissions\Middlewares\PermissionGate::class)
    ->group(function(){
    Route::prefix('official')->group(function (){
       Route::get('sign', [OfficialAccountController::class, 'sign']);
    });
    //next
});
```