---
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` 撤回后再删除。