认证授权#

XinAdmin 项目采用 Laravel Sanctum 进行 API 认证，并结合自定义的注解路由系统实现灵活的权限控制。系统支持双端认证，分别为管理员端（sys_users）和用户端（users），每端都有独立的认证守卫和权限体系。

Sanctum 认证#

XinAdmin 使用 Laravel Sanctum 作为 API 认证解决方案，它提供了一种轻量级的方式来处理 API 认证，支持令牌认证和无状态认证。

配置#

Sanctum 的配置位于 config/sanctum.php，关键配置包括：

• expiration: Token 过期时间（分钟）
• token_prefix: Token 前缀，用于防止意外提交到代码仓库
• middleware: Sanctum 使用的中间件

双端认证#

XinAdmin 支持管理员端和用户端两套独立的认证体系。

管理员认证#

管理员认证使用 sys_users 守卫，对应 sys_user 数据表。管理员模型为 App\Models\Sys\SysUserModel，继承自 Laravel 的 User 类并实现了 Sanctum 的 HasApiTokens 特征。

// 认证配置 (config/auth.php)
'guards' => [
    'sys_users' => [
        'driver' => 'session',
        'provider' => 'sys_users',
    ],
],
'providers' => [
    'sys_users' => [
        'driver' => 'eloquent',
        'model' => \App\Models\Sys\SysUserModel::class
    ],
],

用户认证#

普通用户认证使用 users 守卫，对应 user 数据表。用户模型为 App\Models\UserModel，同样实现了 Sanctum 的 API Token 功能。

'guards' => [
    'users' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
],
'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => \App\Models\UserModel::class
    ],
],

权限控制#

XinAdmin 实现了基于角色的权限控制（RBAC），支持细粒度的权限管理。

角色管理#

系统通过三个核心表实现权限管理：

• sys_user：用户表
• sys_role：角色表
• sys_rule：权限规则表
• sys_user_role：用户-角色关联表
• sys_role_rule：角色-权限关联表

权限规则#

权限规则通过 SysRuleModel 模型管理，支持树形结构的权限组织。每个权限规则包含以下字段：

• id: 权限ID
• parent_id: 父级权限ID
• type: 类型（'menu' | 'route' | 'nested-route' | 'rule'）
• key: 唯一标识，用于权限验证
• name: 权限名称
• path: 路径
• status: 状态（1正常 0禁用）

注解路由权限#

XinAdmin 实现了一套基于 PHP 8 注解的路由系统，简化了路由定义和权限控制。

类级注解#

使用 #[RequestMapping] 注解定义控制器级别的路由配置：

use App\Providers\AnnoRoute\Attribute\RequestMapping;

#[RequestMapping('/sys-user/role', 'sys-user.role')]
class SysUserRoleController extends BaseController
{
    // 控制器逻辑
}

RequestMapping 注解参数：

• routePrefix (string): 路由前缀
• abilitiesPrefix (string): 权限前缀
• middleware (string | array): 中间件配置
• authGuard (string): 认证守卫

你只需在改注解内定义 abilitiesPrefix 控制器内所有方法的权限都会添加改前缀，它们会以 . 拼装。

方法级注解#

#[GetMapping]、#[PostMapping]、#[PutMapping]、#[DeleteMapping] 等注解均支持权限控制：

/** 获取角色用户列表 */
#[GetMapping('/users/{id}', 'users')]
public function users(int $id, SysUserRoleService $service): JsonResponse
{
    return $this->success($service->users($id));
}

方法级注解参数：

• route (string): 路由路径，与类上的 routePrefix 拼接形成完整路由
• authorize (string): 权限字符串，与类上的 abilitiesPrefix 拼接形成完整权限
• middleware (string | array): 路由中间件配置
• where (array): 路由参数约束

CRUD 注解#

系统为默认的控制器方法提供默认的权限注解：

#[RequestMapping('/example/list', 'example.list')]
#[Create, Update, Delete, Query]  // 自动生成 CRUD 接口
class ExampleListController extends BaseController
{
    // 控制器逻辑
}

上面控制器的CRUD方法会校验用户是否拥有以下权限：

• 查询： example.list.query
• 新增： example.list.create
• 编辑： example.list.update
• 删除： example.list.delete

权限管理页面#

你可以在 UI 后台很方便的启用或者停用某个权限，当然也会限制接口的请求，具体内容请查看功能模块-权限管理