Minecraft 服务器状态监控插件

这是一个 Minecraft 服务器状态监控插件（NcatBot 5），支持实时状态查询、历史数据记录、图表生成和自动监控等功能。

功能特性

🔍 实时状态查询

• 查询单个 Minecraft 服务器状态
• 批量查询群组绑定的所有服务器
• 显示在线玩家数量、最大玩家数、版本信息等

📊 历史数据记录

• 使用 SQLite 数据库存储服务器状态历史
• 记录在线玩家数量、响应时间、服务器状态等
• 支持数据查询和统计

📈 图表生成

• 使用 matplotlib 生成服务器状态图表
• 显示在线玩家数量变化、服务器响应时间变化、在线/离线占比
• 支持自定义时间范围（默认 24 小时）

📋 统计信息

• 服务器在线率统计
• 玩家数量统计（平均值、最大值、最小值）
• 响应时间统计（平均值、最大值、最小值）

⚡ 自动监控系统

• 可配置监控间隔时间
• 自动记录状态变化到数据库
• 支持按服务器启用/禁用监控

安装与加载

插件依赖 mcping 和 matplotlib（见 requirements.txt，同时在 manifest.toml 的 [pip_dependencies] 中声明，框架可自动安装）。

pip install -r requirements.txt

将插件目录放入 NcatBot 的 plugins/ 目录，启动后插件自动加载。

配置说明

插件使用框架自带的双层配置系统（init_defaults 注册默认值，全局 config.yaml 的 plugin.plugin_configs.minecraft_status_plugin 覆盖），支持以下配置项：

配置项	类型	默认值	说明
MonitorInterval	int	300	定时监控间隔（秒）
MentionOnlinePlayersChange	bool	false	在线玩家数变化时通知（预留）
MentionServerStatusChange	bool	false	服务器状态变化时通知（预留）
ForceBase64ImageSend	bool	true	强制 Base64 编码发送图片（慢但几乎 100% 成功）

命令列表

所有命令仅在群聊中可用；管理员命令需 RBAC 权限 minecraft_status_plugin.admin。 插件 on_load() 会自动授予机器人 owner（config.yaml 的 root）管理员权限； 其他管理员由 owner 通过 /mcrbac grant 授权。

用户命令

/mcs [ip:port]

查询服务器状态。

• 不指定参数：查询群组绑定的所有服务器
• 指定 IP:端口：查询指定服务器

/mcs
/mcs mc.example.com:25565

/mclist [群组ID]

显示群组绑定的服务器列表。

• 不指定群组ID：显示当前群组
• 指定群组ID：显示指定群组

/mclist
/mclist 123456789

/mcchart <服务器名称> [小时数]

生成服务器状态图表（默认 24 小时）。

/mcchart MyServer
/mcchart MyServer 48

/mcstats <服务器名称> [小时数]

查看服务器统计信息（默认 24 小时）。

/mcstats MyServer
/mcstats MyServer 72

/mchelp

显示帮助信息。

管理员命令

/mcadd <名称> <ip:port> [群组ID]

添加服务器到群组监控列表。

• 名称：只能包含字母、数字、下划线和连字符
• 群组ID：可选，默认当前群组

/mcadd MyServer mc.example.com:25565
/mcadd MyServer mc.example.com:25565 123456789

/mcdel <名称> [群组ID]

从群组监控列表中删除服务器。

/mcdel MyServer
/mcdel MyServer 123456789

/mcmonitor set <名称> <on|off>

启用/禁用服务器自动监控。

/mcmonitor set MyServer on
/mcmonitor set MyServer off

/mcmonitor list

列出所有正在监控的服务器。

/mcmonitor purge [天数]

清理超过指定天数的旧数据（默认 30 天，最大 365 天）。

/mcmonitor purge
/mcmonitor purge 30

/mchelp-admin

显示管理员帮助信息。

运营命令

仅机器人 owner（config.yaml 的 root）可用，用于管理其他管理员。

/mcrbac grant @用户 或 /mcrbac grant <用户QQ>

授予指定用户管理员权限（支持 @ 提及或直接输入 QQ 号）。

/mcrbac grant @123456789
/mcrbac grant 123456789

/mcrbac revoke @用户 或 /mcrbac revoke <用户QQ>

撤销指定用户的管理员权限（支持 @ 提及或直接输入 QQ 号）。

/mcrbac revoke @123456789
/mcrbac revoke 123456789

/mcrbac list

列出所有管理员。

数据库结构

插件使用 SQLite 数据库（data/minecraft_status_plugin/server_history.db），包含一张表：

server_status_history

服务器状态历史记录表：记录每次查询/监控的服务器状态，包含在线玩家数、响应时间、状态等字段。

定时任务

插件使用框架的 add_scheduled_task 注册定时监控任务：

• 任务名称：minecraft_monitor
• 执行函数：monitor_all_servers
• 调度间隔：MonitorInterval 配置（默认 300 秒）

文件结构

minecraft_status_plugin/
├── __init__.py          # 插件初始化文件
├── main.py              # 插件生命周期与核心业务逻辑
├── command_handler.py   # 命令 handler（@registrar.qq.on_group_command）
├── manifest.toml        # 插件清单（入口类 + pip 依赖声明）
├── requirements.txt     # Python 依赖
├── Pipfile             # 依赖管理文件
├── README.md           # 说明文档
├── AGENTS.md           # 开发辅助文档
└── LICENSE             # 许可证文件

注意事项

1. 权限要求：管理员命令需要 RBAC 权限 minecraft_status_plugin.admin；机器人 owner 自动获得，其他管理员经 /mcrbac 授权
2. 数据库路径：数据库文件存储在插件工作区 data/minecraft_status_plugin/ 下
3. 图表生成：图表文件输出到系统临时目录
4. 监控间隔：建议监控间隔不少于 60 秒，避免对服务器造成压力
5. 服务器名称：只能包含字母、数字、下划线和连字符
6. 定时任务：使用框架自带的定时任务机制，无需手动管理协程

故障排除

常见问题

1. 服务器连接超时

   • 检查服务器地址和端口是否正确
   • 确认服务器是否在线
   • 检查网络连接

2. 图表生成失败

   • 确认服务器有足够的历史数据
   • 检查 matplotlib 是否正确安装
   • 查看日志文件获取详细错误信息

3. 数据库错误

   • 检查数据库文件权限
   • 确认 SQLite3 支持
   • 查看日志文件获取详细错误信息

4. 定时任务不工作

   • 检查配置的监控间隔是否合理
   • 确认服务器是否启用了监控
   • 查看日志文件获取详细错误信息

日志查看

插件会记录详细的日志信息，包括：

• 服务器状态查询结果
• 数据库操作记录
• 定时任务注册和执行情况
• 错误和警告信息

TODO

• 实现玩家数量变化时发送通知功能
• 实现服务器状态变化时发送通知功能
• 支持更多自定义配置选项
• 优化图表样式和信息展示

许可证

本项目采用 GNU Affero General Public License v3.0 许可证，详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request 来改进这个插件！