molong/laravel_swoole
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
laravel_swoole/docs/README_AUTH.md
molong 334d2c6312 初始化项目
2026-02-08 22:38:13 +08:00

14 KiB
Raw Permalink Blame History

Auth 基础模块文档

概述

Auth 基础模块提供了完整的后台管理系统的认证授权功能，包括用户管理、角色管理、权限管理、部门管理等功能。

控制器结构

app/Http/Controllers/Auth/
└── Admin/
    ├── Auth.php              # 认证控制器
    ├── User.php              # 用户管理控制器
    ├── Role.php              # 角色管理控制器
    ├── Permission.php         # 权限管理控制器
    └── Department.php        # 部门管理控制器

命名空间: App\Http\Controllers\Auth\Admin

路由前缀: /admin

中间件: auth.check:admin (后台管理认证)

技术栈

  • PHP 8.1+
  • Laravel 11
  • JWT 认证 (tymon/jwt-auth)
  • Redis 缓存
  • Laravel Excel (maatwebsite/excel)

数据库表结构

auth_users (用户表)

  • id: 主键
  • username: 用户名（唯一）
  • password: 密码（加密）
  • real_name: 真实姓名
  • email: 邮箱
  • phone: 手机号
  • avatar: 头像
  • department_id: 部门ID
  • status: 状态（0:禁用, 1:启用）
  • last_login_at: 最后登录时间
  • last_login_ip: 最后登录IP
  • last_active_at: 最后活跃时间
  • created_at, updated_at: 时间戳

auth_roles (角色表)

  • id: 主键
  • name: 角色名称
  • code: 角色编码（唯一）
  • description: 角色描述
  • sort: 排序
  • status: 状态
  • created_at, updated_at: 时间戳

auth_permissions (权限表)

  • id: 主键
  • name: 权限名称
  • code: 权限编码（唯一，格式：模块.功能.操作）
  • type: 类型（menu:菜单, api:接口, button:按钮）
  • route: 路由
  • component: 组件路径
  • icon: 图标
  • parent_id: 父级ID
  • meta: 元数据（JSON格式）
  • sort: 排序
  • status: 状态
  • created_at, updated_at: 时间戳

auth_role_permission (角色权限关联表)

  • id: 主键
  • role_id: 角色ID
  • permission_id: 权限ID

auth_user_role (用户角色关联表)

  • id: 主键
  • user_id: 用户ID
  • role_id: 角色ID

auth_departments (部门表)

  • id: 主键
  • name: 部门名称
  • parent_id: 父级ID
  • leader: 负责人
  • phone: 联系电话
  • sort: 排序
  • status: 状态
  • created_at, updated_at: 时间戳

API 接口文档

中间件说明

AuthCheckMiddleware

这是一个通用的认证中间件，支持通过参数指定不同的路由守卫和权限验证。

基本用法

1. 只进行登录认证（不检查权限）

// 使用 admin 守卫
Route::middleware(['auth.check:admin'])->group(function () {
    Route::get('/users', [UserController::class, 'index']);
});

// 使用 api 守卫
Route::middleware(['auth.check:api'])->group(function () {
    Route::get('/profile', [UserController::class, 'profile']);
});

2. 登录认证 + 权限验证

// 验证用户是否有特定权限
Route::middleware(['auth.check:admin,system.user.list'])->group(function () {
    Route::get('/users', [UserController::class, 'index']);
});

// 验证多个权限
Route::middleware(['auth.check:admin,system.user.create'])->group(function () {
    Route::post('/users', [UserController::class, 'store']);
});

3. 单个路由应用中间件

Route::middleware('auth.check:admin,system.user.delete')->delete('/users/{id}', [UserController::class, 'destroy']);

参数说明

  • guard: 认证守卫名称（必需），例如：admin、api
  • permission: 权限编码（可选），如果指定则会验证用户是否有该权限

功能特性

  • ✅ 支持多个路由守卫（admin、api等）
  • ✅ 支持登录状态检查
  • ✅ 支持用户状态检查（禁用用户无法访问）
  • ✅ 支持权限验证
  • ✅ 自动将用户信息注入到请求中（$request->auth_user）
  • ✅ 自动更新用户最后活跃时间

认证相关

登录

  • 接口: POST /admin/auth/login
  • 参数: 
    {
  "username": "admin",
  "password": "123456"
}
  • 返回: 
    {
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "user": {...},
    "menu": {...},
    "permissions": {...}
  }
}

登出

  • 接口: POST /admin/auth/logout
  • Header: Authorization: Bearer {token}

刷新Token

  • 接口: POST /admin/auth/refresh
  • Header: Authorization: Bearer {token}

获取当前用户信息

  • 接口: GET /admin/auth/me
  • Header: Authorization: Bearer {token}

修改密码

  • 接口: POST /admin/auth/change-password
  • 参数: 
    {
  "old_password": "123456",
  "new_password": "654321"
}

用户管理

获取用户列表

  • 接口: GET /admin/users
  • 参数:
    • page: 页码（默认1）
    • page_size: 每页数量（默认20）
    • keyword: 搜索关键词（用户名/真实姓名/邮箱）
    • status: 状态（0:禁用, 1:启用）
    • department_id: 部门ID
    • role_id: 角色ID
    • order_by: 排序字段（默认id）
    • order_direction: 排序方向（asc/desc，默认asc）

获取用户详情

  • 接口: GET /admin/users/{id}

创建用户

  • 接口: POST /admin/users
  • 参数: 
    {
  "username": "test001",
  "password": "123456",
  "real_name": "测试用户",
  "email": "test@example.com",
  "phone": "13800138000",
  "department_id": 1,
  "role_ids": [1, 2],
  "status": 1
}

更新用户

  • 接口: PUT /admin/users/{id}
  • 参数: 同创建用户（所有字段都是可选的）

删除用户

  • 接口: DELETE /admin/users/{id}

批量删除用户

  • 接口: POST /admin/users/batch-delete
  • 参数: 
    {
  "ids": [1, 2, 3]
}

批量更新用户状态

  • 接口: POST /admin/users/batch-status
  • 参数: 
    {
  "ids": [1, 2, 3],
  "status": 1
}

批量分配部门

  • 接口: POST /admin/users/batch-department
  • 参数: 
    {
  "ids": [1, 2, 3],
  "department_id": 1
}

批量分配角色

  • 接口: POST /admin/users/batch-roles
  • 参数: 
    {
  "ids": [1, 2, 3],
  "role_ids": [1, 2]
}

导出用户

  • 接口: POST /admin/users/export
  • 参数: 
    {
  "ids": [1, 2, 3]  // 可选，不传则导出所有用户
}

导入用户

  • 接口: POST /admin/users/import
  • 参数: file (multipart/form-data, xlsx/xls文件)
  • 返回: 
    {
  "code": 200,
  "message": "导入完成，成功 10 条，失败 0 条",
  "data": {
    "success_count": 10,
    "error_count": 0,
    "errors": []
  }
}

下载用户导入模板

  • 接口: GET /admin/users/download-template

在线用户管理

获取在线用户数量

  • 接口: GET /admin/online-users/count

获取在线用户列表

  • 接口: GET /admin/online-users
  • 参数:
    • limit: 数量限制（默认100）

获取用户的所有会话

  • 接口: GET /admin/online-users/{userId}/sessions

强制用户下线（单个会话）

  • 接口: POST /admin/online-users/{userId}/offline
  • 参数: 
    {
  "token": "用户token"
}

强制用户所有设备下线

  • 接口: POST /admin/online-users/{userId}/offline-all

角色管理

获取角色列表

  • 接口: GET /admin/roles
  • 参数:
    • page, page_size, keyword, status, order_by, order_direction

获取所有角色（不分页）

  • 接口: GET /admin/roles/all

获取角色详情

  • 接口: GET /admin/roles/{id}

创建角色

  • 接口: POST /admin/roles
  • 参数: 
    {
  "name": "编辑",
  "code": "editor",
  "description": "编辑角色",
  "sort": 1,
  "status": 1,
  "permission_ids": [1, 2, 3]
}

更新角色

  • 接口: PUT /admin/roles/{id}

删除角色

  • 接口: DELETE /admin/roles/{id}

批量删除角色

  • 接口: POST /admin/roles/batch-delete

批量更新角色状态

  • 接口: POST /admin/roles/batch-status

分配权限

  • 接口: POST /admin/roles/{id}/permissions
  • 参数: 
    {
  "permission_ids": [1, 2, 3]
}

获取角色的权限列表

  • 接口: GET /admin/roles/{id}/permissions

复制角色

  • 接口: POST /admin/roles/{id}/copy
  • 参数: 
    {
  "name": "新角色名称",
  "code": "new_role_code",
  "description": "新角色描述",
  "status": 1
}

批量复制角色

  • 接口: POST /admin/roles/batch-copy
  • 参数: 
    {
  "ids": [1, 2, 3],
  "name": "新角色名称（可选）",
  "code": "new_code（可选）"
}

权限管理

获取权限列表

  • 接口: GET /admin/permissions
  • 参数:
    • page, page_size, keyword, type, status, order_by, order_direction

获取权限树

  • 接口: GET /admin/permissions/tree

获取菜单树

  • 接口: GET /admin/permissions/menu
  • 返回: 当前登录用户的菜单树

获取权限详情

  • 接口: GET /admin/permissions/{id}

创建权限

  • 接口: POST /admin/permissions
  • 参数: 
    {
  "name": "用户列表",
  "code": "system.user.list",
  "type": "api",
  "route": "/admin/users",
  "component": "",
  "icon": "user",
  "parent_id": 0,
  "sort": 1,
  "status": 1,
  "meta": {
    "title": "用户列表",
    "keepAlive": true
  }
}

更新权限

  • 接口: PUT /admin/permissions/{id}

删除权限

  • 接口: DELETE /admin/permissions/{id}

批量删除权限

  • 接口: POST /admin/permissions/batch-delete

批量更新权限状态

  • 接口: POST /admin/permissions/batch-status

部门管理

获取部门列表

  • 接口: GET /admin/departments
  • 参数:
    • page, page_size, keyword, status, order_by, order_direction

获取部门树

  • 接口: GET /admin/departments/tree

获取所有部门（不分页）

  • 接口: GET /admin/departments/all

获取部门详情

  • 接口: GET /admin/departments/{id}

创建部门

  • 接口: POST /admin/departments
  • 参数: 
    {
  "name": "技术部",
  "parent_id": 0,
  "leader": "张三",
  "phone": "13800138000",
  "sort": 1,
  "status": 1
}

更新部门

  • 接口: PUT /admin/departments/{id}

删除部门

  • 接口: DELETE /admin/departments/{id}

批量删除部门

  • 接口: POST /admin/departments/batch-delete

批量更新部门状态

  • 接口: POST /admin/departments/batch-status

导出部门

  • 接口: POST /admin/departments/export

导入部门

  • 接口: POST /admin/departments/import
  • 参数: file (multipart/form-data, xlsx/xls文件)

下载部门导入模板

  • 接口: GET /admin/departments/download-template

权限设计

权限编码规则

权限编码采用 模块.功能.操作 的格式，例如：

  • system.user.list - 系统管理-用户-列表
  • system.user.create - 系统管理-用户-创建
  • system.user.update - 系统管理-用户-更新
  • system.user.delete - 系统管理-用户-删除

权限类型

  • menu: 菜单类型，用于前端路由配置
  • api: API接口类型，用于后端权限验证
  • button: 按钮类型，用于前端按钮权限控制

缓存机制

用户在线状态缓存

  • 缓存键: user_online:{userId}:{tokenHash}
  • 过期时间: 5分钟
  • 用途: 跟踪用户在线状态、最后活跃时间、登录设备信息

权限缓存

  • 用户权限列表: permission:user:{userId}:permissions (60分钟)
  • 用户权限编码: permission:user:{userId}:permission_codes (60分钟)
  • 用户菜单树: permission:user:{userId}:menu_tree (60分钟)
  • 角色权限: permission:role:{roleId}:permissions (60分钟)

缓存更新时机

  • 用户登录/刷新token时，更新在线状态
  • 用户角色变化时，清除用户权限缓存
  • 角色权限变化时，清除角色和所有关联用户的权限缓存
  • 权限本身变化时，清除所有权限缓存

导入导出

用户导入模板字段

  • 用户名*（必填）
  • 密码*（必填）
  • 真实姓名*（必填）
  • 邮箱
  • 手机号
  • 部门名称
  • 角色名称（多个用逗号分隔）
  • 备注

部门导入模板字段

  • 部门名称*（必填）
  • 上级部门名称
  • 负责人
  • 联系电话
  • 排序
  • 备注

导出功能

  • 支持导出全部数据
  • 支持按选中的ID导出
  • 导出文件为Excel格式
  • 下载后自动删除临时文件

初始化数据

运行数据库迁移和填充命令：

# 执行迁移
php artisan migrate

# 填充初始数据
php artisan db:seed --class=AuthSeeder

初始数据包括：

  • 超级管理员账号（username: admin, password: 123456）
  • 基础角色（超级管理员、管理员）
  • 完整的权限菜单
  • 默认部门

注意事项

  1. Swoole环境注意事项:

    • 避免使用静态变量存储状态
    • 避免使用全局变量
    • 正确管理数据库连接
    • 使用Redis缓存时注意连接池配置

  2. 安全注意事项:

    • 所有密码必须加密存储
    • 使用JWT进行身份认证
    • 敏感操作需要记录日志
    • 定期清理过期的导出文件

  3. 性能优化:

    • 使用Redis缓存权限数据
    • 大批量操作使用队列处理
    • 分页查询避免一次性加载过多数据

  4. 权限验证:

    • 在中间件中验证用户权限
    • 前端根据权限控制按钮显示
    • 使用权限缓存减少数据库查询

扩展建议

  1. 日志审计: 添加操作日志记录
  2. 数据权限: 实现基于部门的数据权限控制
  3. 多租户: 支持多租户场景
  4. SSO登录: 支持第三方单点登录
  5. 动态权限: 支持运行时动态添加权限

常见问题

Q: 如何添加新的权限模块？

A: 在Seed文件中添加新的权限数据，或者通过API创建新的权限节点。

Q: 导入大量数据时超时怎么办？

A: 使用队列处理导入任务，分批导入数据。

Q: 如何清理权限缓存？

A: 调用 PermissionCacheService::clearAllPermissionCache() 方法。

Q: Swoole环境下如何热重载？

A: 运行 php bin/laravels reload 命令进行平滑重启。

Q: Excel文件支持哪些格式？

A: 支持.xlsx和.xls格式文件。

Reference in New Issue View Git Blame Copy Permalink