mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-10 03:42:49 +08:00
107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
---
|
||
name: "ulthon-permission-cli"
|
||
description: "解释并指导 RBAC 权限体系与相关 CLI 命令（admin:role:* / admin:user:role:* / admin:permission:*）。用于查看节点、管理角色权限、给用户分配角色、排查权限问题。"
|
||
---
|
||
|
||
# 权限与角色管理（RBAC CLI）
|
||
|
||
## 何时调用
|
||
|
||
- 需要查看系统当前有哪些权限节点。
|
||
- 需要创建/查看/删除角色，或查看角色详情。
|
||
- 需要为角色分配/撤回权限节点。
|
||
- 需要给指定用户分配/撤回角色。
|
||
- 需要排查“有菜单但无权限 / 有权限但仍被拦截 / 节点名称不一致”等权限问题。
|
||
|
||
## 概念速览
|
||
|
||
- 权限节点：基于控制器/方法注解生成的权限标识（用于授权与鉴权）。
|
||
- 角色：权限节点的集合（`SystemAuth`）。
|
||
- 用户：后台用户（`SystemAdmin`），通过 `auth_ids`（逗号分隔）绑定角色 ID 列表。
|
||
- 角色-节点：`SystemAuthNode` 记录 `auth_id + node` 的多对多关系。
|
||
- 鉴权入口：后台请求进入后会根据“当前节点”进行权限检查（未授权则拦截）。
|
||
- 输出说明：权限相关命令默认以文本输出为主；如命令涉及交互确认，可使用 `--force-force` 或 `-ff` 跳过确认。
|
||
|
||
## 常用命令
|
||
|
||
### 1) 查看权限节点
|
||
|
||
```bash
|
||
php think admin:permission:nodes
|
||
```
|
||
|
||
常用参数（如需）：
|
||
- `--module=<模块>`：按模块过滤
|
||
- `--level=1|2`：按级别过滤（1=控制器，2=方法）
|
||
|
||
### 2) 角色管理
|
||
|
||
```bash
|
||
php think admin:role:list
|
||
php think admin:role:info --role-id=12
|
||
php think admin:role:create --title="测试角色" --remark="测试用"
|
||
php think admin:role:delete --role-id=12
|
||
```
|
||
|
||
要点：
|
||
- 删除角色会检查该角色是否仍被用户分配；若仍有用户绑定，则删除会失败。
|
||
|
||
### 3) 角色权限管理
|
||
|
||
```bash
|
||
php think admin:role:permission:list --role-id=12
|
||
php think admin:role:permission:assign --role-id=12 --nodes="system.admin/index,system.admin/add"
|
||
php think admin:role:permission:revoke --role-id=12 --nodes="system.admin/add"
|
||
```
|
||
|
||
要点：
|
||
- `--nodes` 支持逗号分隔批量操作。
|
||
- 建议先用 `admin:permission:nodes` 确认节点名称完全一致后再分配到角色。
|
||
|
||
### 4) 用户角色管理
|
||
|
||
```bash
|
||
php think admin:user:role:list --user-id=1
|
||
php think admin:user:role:assign --user-id=1 --role-ids="12,13"
|
||
php think admin:user:role:revoke --user-id=1 --role-ids="13"
|
||
```
|
||
|
||
### 5) 透视查询用户当前权限
|
||
|
||
```bash
|
||
php think admin:permission:user --user-id=1
|
||
```
|
||
|
||
## 典型工作流
|
||
|
||
### 工作流 A：新增/调整注解后，核对节点并授权
|
||
|
||
1. 在控制器/方法上新增或调整权限注解（节点名称、标题、模块等）。
|
||
2. 执行 `admin:permission:nodes`，确认节点列表中已出现新节点且名称符合预期。
|
||
3. 确定要使用的角色（可通过 `admin:role:list` / `admin:role:info` 查看；没有合适角色就用 `admin:role:create` 新建）。
|
||
4. 执行 `admin:role:permission:assign` 将新节点分配给角色。
|
||
5. 执行 `admin:user:role:assign` 将角色分配给用户。
|
||
6. 执行 `admin:permission:user` 透视确认该用户已拥有节点。
|
||
|
||
### 工作流 B：排查“明明有权限但仍被拦截”
|
||
|
||
1. 执行 `admin:permission:user --user-id=<id>`，确认用户是否真的拥有当前节点。
|
||
2. 执行 `admin:permission:nodes`，确认“当前被拦截节点名”是否存在、是否有大小写/分隔符差异。
|
||
3. 如果用户通过角色获得权限，执行 `admin:role:permission:list --role-id=<roleId>` 核对角色是否包含该节点。
|
||
4. 检查后台配置中是否存在免鉴权规则（例如 no_login/no_auth 的控制器/节点白名单）。
|
||
|
||
## 变更说明（重要）
|
||
|
||
- 旧命令 `admin:permission:assign` / `admin:permission:revoke` 已移除。
|
||
- “按用户直接增删节点”的需求，应通过“角色”承接：
|
||
- 只影响单个用户：创建专用角色 → 给该角色分配节点 → 将角色分配给该用户。
|
||
- 影响一批用户：维护共享角色 → 给该角色增删节点 → 所有拥有该角色的用户一起生效。
|
||
|
||
## 常见坑位
|
||
|
||
- 节点名不一致：注解里写的节点名与实际鉴权使用的当前节点不一致，导致分配了权限但无法命中。
|
||
- 只改了菜单没改权限：菜单能看到不代表有权限访问，权限检查以节点为准。
|
||
- 缓存/环境差异：在不同环境中节点生成来源不一致时，先以 `admin:permission:nodes` 的输出为准核对。
|
||
- 修改共享角色影响面过大：撤回/新增角色节点会影响所有拥有该角色的用户。
|
||
- 删除角色失败：仍有用户绑定该角色，先用 `admin:user:role:revoke` 撤回后再删除。
|