权限系统使用说明
概述
MoFox_Bot的权限系统提供了完整的权限管理功能，支持权限等级和权限节点配置。系统包含以下核心概念：
- 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- 游戏插件房间创建权限
权限系统数据库表
系统会自动创建以下数据库表：
- permission_nodes - 存储权限节点信息
- user_permissions - 存储用户权限授权记录
最佳实践
- 细粒度权限：为不同功能创建独立的权限节点
- 默认权限设置：谨慎设置默认权限，敏感操作应默认拒绝
- 权限描述：为每个权限节点提供清晰的描述
- Master用户：只为真正的管理员分配Master权限
- 权限检查：在执行敏感操作前始终检查权限
示例插件
查看 plugins/permission_example.py 了解完整的权限系统使用示例。
故障排除
- 权限检查失败：确保权限节点已正确注册
- Master用户配置：检查配置文件中的用户ID格式是否正确
- 权限不生效：重启机器人以重新加载配置
- 数据库问题：检查数据库连接和表结构是否正确