197 lines
6.0 KiB
Markdown
197 lines
6.0 KiB
Markdown
# 权限系统使用说明
|
||
|
||
## 概述
|
||
|
||
MaiMbot-Pro-Max的权限系统提供了完整的权限管理功能，支持权限等级和权限节点配置。系统包含以下核心概念：
|
||
|
||
- **Master用户**：拥有最高权限，无视所有权限节点，在配置文件中设置
|
||
- **权限节点**：细粒度的权限控制单元，由插件自行创建和管理
|
||
- **权限管理**：统一的权限授权、撤销和查询功能
|
||
|
||
## 配置文件设置
|
||
|
||
在 `config/bot_config.toml` 中添加权限配置：
|
||
|
||
```toml
|
||
[permission] # 权限系统配置
|
||
# Master用户配置（拥有最高权限，无视所有权限节点）
|
||
# 格式：[[platform, user_id], ...]
|
||
master_users = [
|
||
["qq", "123456789"], # QQ平台的Master用户
|
||
["qq", "987654321"], # 可以配置多个Master用户
|
||
]
|
||
```
|
||
|
||
## 插件开发中使用权限系统
|
||
|
||
### 1. 注册权限节点
|
||
|
||
在插件的 `on_load()` 方法中注册权限节点：
|
||
|
||
```python
|
||
from src.plugin_system.apis.permission_api import permission_api
|
||
|
||
class MyPlugin(BasePlugin):
|
||
def on_load(self):
|
||
# 注册权限节点
|
||
permission_api.register_permission_node(
|
||
"plugin.myplugin.admin", # 权限节点名称
|
||
"我的插件管理员权限", # 权限描述
|
||
"myplugin", # 插件名称
|
||
False # 默认是否授权（False=默认拒绝）
|
||
)
|
||
|
||
permission_api.register_permission_node(
|
||
"plugin.myplugin.user",
|
||
"我的插件用户权限",
|
||
"myplugin",
|
||
True # 默认授权
|
||
)
|
||
```
|
||
|
||
### 2. 使用权限装饰器
|
||
|
||
最简单的权限检查方式是使用装饰器：
|
||
|
||
```python
|
||
from src.plugin_system.utils.permission_decorators import require_permission, require_master
|
||
|
||
class MyCommand(BaseCommand):
|
||
@require_permission("plugin.myplugin.admin")
|
||
async def execute(self, message: Message, chat_stream: ChatStream, args: List[str]):
|
||
await send_message(chat_stream, "你有管理员权限！")
|
||
|
||
@require_master("只有Master可以执行此操作")
|
||
async def master_only_function(self, message: Message, chat_stream: ChatStream):
|
||
await send_message(chat_stream, "Master专用功能")
|
||
```
|
||
|
||
### 3. 手动权限检查
|
||
|
||
对于更复杂的权限逻辑，可以手动检查权限：
|
||
|
||
```python
|
||
from src.plugin_system.utils.permission_decorators import PermissionChecker
|
||
|
||
class MyCommand(BaseCommand):
|
||
async def execute(self, message: Message, chat_stream: ChatStream, args: List[str]):
|
||
# 检查是否为Master用户
|
||
if PermissionChecker.is_master(chat_stream):
|
||
await send_message(chat_stream, "Master用户可以执行所有操作")
|
||
return
|
||
|
||
# 检查特定权限
|
||
if PermissionChecker.check_permission(chat_stream, "plugin.myplugin.read"):
|
||
await send_message(chat_stream, "你可以读取数据")
|
||
|
||
# 使用 ensure_permission 自动发送权限不足消息
|
||
if await PermissionChecker.ensure_permission(chat_stream, "plugin.myplugin.write"):
|
||
await send_message(chat_stream, "你可以写入数据")
|
||
```
|
||
|
||
### 4. 直接使用权限API
|
||
|
||
```python
|
||
from src.plugin_system.apis.permission_api import permission_api
|
||
|
||
# 检查权限
|
||
has_permission = permission_api.check_permission("qq", "123456", "plugin.myplugin.admin")
|
||
|
||
# 检查是否为Master
|
||
is_master = permission_api.is_master("qq", "123456")
|
||
|
||
# 授权用户
|
||
success = permission_api.grant_permission("qq", "123456", "plugin.myplugin.admin")
|
||
|
||
# 撤销权限
|
||
success = permission_api.revoke_permission("qq", "123456", "plugin.myplugin.admin")
|
||
|
||
# 获取用户的所有权限
|
||
permissions = permission_api.get_user_permissions("qq", "123456")
|
||
|
||
# 获取所有权限节点
|
||
all_nodes = permission_api.get_all_permission_nodes()
|
||
|
||
# 获取指定插件的权限节点
|
||
plugin_nodes = permission_api.get_plugin_permission_nodes("myplugin")
|
||
```
|
||
|
||
## 权限管理命令
|
||
|
||
系统提供了内置的权限管理命令，需要相应权限才能使用：
|
||
|
||
### 管理员命令（需要 `plugin.permission.manage` 权限）
|
||
|
||
```
|
||
# 授权用户权限
|
||
/permission grant @用户 plugin.example.admin
|
||
/permission grant 123456789 plugin.example.admin
|
||
|
||
# 撤销用户权限
|
||
/permission revoke @用户 plugin.example.admin
|
||
/permission revoke 123456789 plugin.example.admin
|
||
```
|
||
|
||
### 查看命令（需要 `plugin.permission.view` 权限）
|
||
|
||
```
|
||
# 查看用户权限列表
|
||
/permission list @用户
|
||
/permission list 123456789
|
||
/permission list # 查看自己的权限
|
||
|
||
# 检查用户是否拥有权限
|
||
/permission check @用户 plugin.example.admin
|
||
/permission check 123456789 plugin.example.admin
|
||
|
||
# 查看权限节点列表
|
||
/permission nodes # 查看所有权限节点
|
||
/permission nodes example_plugin # 查看指定插件的权限节点
|
||
```
|
||
|
||
### 帮助命令
|
||
|
||
```
|
||
/permission help # 显示帮助信息
|
||
```
|
||
|
||
## 权限节点命名规范
|
||
|
||
建议使用以下命名规范：
|
||
|
||
```
|
||
plugin.<插件名>.<功能类别>.<具体权限>
|
||
```
|
||
|
||
示例：
|
||
- `plugin.music.play` - 音乐插件播放权限
|
||
- `plugin.music.admin` - 音乐插件管理权限
|
||
- `plugin.game.user` - 游戏插件用户权限
|
||
- `plugin.game.room.create` - 游戏插件房间创建权限
|
||
|
||
## 权限系统数据库表
|
||
|
||
系统会自动创建以下数据库表：
|
||
|
||
1. **permission_nodes** - 存储权限节点信息
|
||
2. **user_permissions** - 存储用户权限授权记录
|
||
|
||
## 最佳实践
|
||
|
||
1. **细粒度权限**：为不同功能创建独立的权限节点
|
||
2. **默认权限设置**：谨慎设置默认权限，敏感操作应默认拒绝
|
||
3. **权限描述**：为每个权限节点提供清晰的描述
|
||
4. **Master用户**：只为真正的管理员分配Master权限
|
||
5. **权限检查**：在执行敏感操作前始终检查权限
|
||
|
||
## 示例插件
|
||
|
||
查看 `plugins/permission_example.py` 了解完整的权限系统使用示例。
|
||
|
||
## 故障排除
|
||
|
||
1. **权限检查失败**：确保权限节点已正确注册
|
||
2. **Master用户配置**：检查配置文件中的用户ID格式是否正确
|
||
3. **权限不生效**：重启机器人以重新加载配置
|
||
4. **数据库问题**：检查数据库连接和表结构是否正确
|