astrbot_mcgetter

!!!!!!!!重要提示

!!! 2025/7/9的更新改变了json配置文件格式,更新后请先手动备份原来的json文件,再重新添加!!!

!!!!!!!!重要提示

!!! 2025/7/9的更新改变了json配置文件格式,更新后请先手动备份原来的json文件,再重新添加!!!

!!!!!!!!重要提示

!!! 2025/7/9的更新改变了json配置文件格式,更新后请先手动备份原来的json文件,再重新添加!!!

简介

AstrBot Minecraft服务器信息查询插件，用于查询Minecraft服务器状态信息并使用图片展示和查询在线人数柱状图。支持多服务器管理、实时状态查询、玩家列表显示、自动清理等功能。

功能特性

• 🎮 多服务器管理 - 支持添加、删除、查询多个Minecraft服务器
• 📊 实时状态查询 - 获取服务器在线状态、玩家数量、延迟等信息
• 👥 玩家列表显示 - 显示当前在线玩家列表
• 🖼️ 图片化展示 - 将服务器信息渲染为美观的图片
• 🔒 地址验证 - 自动验证服务器地址格式和连接性
• 📝 群组独立 - 每个群组独立管理服务器列表
• 🧹 自动清理 - 自动删除长时间未查询成功的服务器
• 🆔 ID管理 - 基于ID的服务器管理系统，支持名称和ID双重操作

安装说明

1. 确保已安装 AstrBot
2. 将插件文件放入 AstrBot 插件目录
3. 重启 AstrBot 或重新加载插件
4. 在群聊中使用 /mchelp 查看帮助

使用方法

基础命令

详细说明

添加服务器

/mcadd 服务器名称 服务器地址 [force]

• 服务器名称: 自定义的服务器名称
• 服务器地址: 服务器IP地址或域名（支持端口号）
• force: 可选参数，设为True时跳过预查询检查强制添加

示例:

/mcadd Hypixel mc.hypixel.net
/mcadd 本地服务器 127.0.0.1:25565 True

查询服务器

/mc

查询所有已保存的服务器状态，返回包含以下信息的图片：

• 服务器名称和ID
• 在线状态
• 玩家数量（当前/最大）
• 服务器版本
• 延迟
• 在线玩家列表

自动清理: 每次执行 /mc 命令时会自动清理10天未查询成功的服务器

获取服务器地址

/mcget 服务器名称/ID

获取指定服务器的地址信息。支持通过名称或ID查找。

删除服务器

/mcdel 服务器名称/ID

从列表中删除指定的服务器。支持通过名称或ID删除。

更新服务器信息

/mcup 服务器名称/ID [新名称] [新地址]

更新指定服务器的名称或地址信息。

列出所有服务器

/mclist

显示所有保存的服务器及其ID和地址。

列有服务器玩家柱状图

/mcdata 服务器名称/id 小时数

查看服务器最近N小时柱状图

手动清理

/mccleanup

手动触发自动清理，删除10天未查询成功的服务器。

自动清理功能

功能特性

• 自动状态记录: 记录服务器创建时间、最后成功/失败时间、失败次数
• 自动清理规则: 服务器连续10天未查询成功时自动删除
• 清理时机: 每次使用 /mc 命令时自动触发，或使用 /mccleanup 手动触发
• 清理提示: 删除服务器时显示详细信息（名称、ID、地址、最后成功时间）

清理消息示例

自动清理完成，以下服务器因10天未查询成功已被删除:
• 过期服务器1 (ID: 2) - 地址: example.com:25565 - 最后成功: 2024-01-01 12:00:00
• 过期服务器2 (ID: 3) - 地址: test.server.com - 最后成功: 2024-01-02 15:30:00

JSON配置系统

数据格式

插件使用基于ID的JSON配置系统，支持自动版本迁移：

{
    "version": "2.3",
    "next_id": 5,
    "last_cleanup": 1752028440,
    
    "trends": {
        "1": {"history": [{"ts": 1752024800, "count": 5}, {"ts": 1752028400, "count": 7}]},
        "2": {"history": [{"ts": 1752024800, "count": 0}]}
    },
    "servers": {
        "1": {
            "id": 1,
            "name": "主服务器",
            "host": "main.example.com:25565",
            "created_time": 1752028440,
            "last_success_time": 1752028440,
            "last_failed_time": null,
            "failed_count": 0
        }
    }
}

主要特性

• 自动版本迁移: 旧版配置会自动迁移到新版格式
• ID管理: 使用递增的数字ID，删除后不重用
• 向后兼容: 支持通过名称或ID进行操作
• 状态跟踪: 记录服务器查询状态和时间戳

支持的功能

• ✅ 多服务器管理
• ✅ 实时状态查询
• ✅ 玩家列表显示
• ✅ 图片化信息展示
• ✅ 地址格式验证
• ✅ 群组独立配置
• ✅ 强制添加模式
• ✅ 自动清理功能
• ✅ ID管理系统
• ✅ 服务器信息更新
• ✅ 状态跟踪记录

技术特性

• 地址验证: 只允许字母、数字和符号 .:- 在服务器地址中
• 预查询检查: 添加服务器前自动验证连接性
• 错误处理: 完善的异常处理和用户友好的错误提示
• 日志记录: 详细的操作日志便于调试
• 异步操作: 所有操作都是异步的，性能优异
• 数据安全: 删除操作前会显示详细信息

使用场景

场景1: 定期维护

1. 定期使用 /mc 命令查询服务器
2. 系统自动清理过期服务器
3. 查看清理结果，了解服务器状态

场景2: 服务器管理

1. 使用 /mclist 查看所有服务器
2. 通过 /mcget 获取特定服务器信息
3. 使用 /mcup 更新服务器信息
4. 用 /mcdel 删除不需要的服务器

场景3: 监控服务器状态（柱状图）

1. 添加服务器后系统默认开始按小时记录在线人数
2. 使用 /mcdata 查看全部服务器最近N小时柱状图

#### 柱状图指令使用示例

/mcdata # 全部服务器，默认24小时
/mcdata 24 # 全部服务器，24小时
/mcdata GTNH 48 # 名称为 GTNH 的服务器，48小时
/mcdata 2 24 # ID 为 2 的服务器，24小时

3. 结合 /mc 实时状态图，定位波动与问题

配置参数

自动清理配置

• 清理天数: 10天（可在代码中修改 AUTO_CLEANUP_DAYS 常量）
• 清理时机: 每次 /mc 命令执行时
• 清理提示: 显示被删除服务器的详细信息

版本信息

• 插件版本: 1.5.0
• JSON格式版本: 2.3
• 兼容性: 兼容原插件数据

注意事项

1. 数据安全

• 删除操作不可逆，请谨慎使用
• 建议定期备份重要的服务器配置
• 清理前会显示详细的删除信息

2. 时间计算

• 基于Unix时间戳计算
• 精确到秒级别
• 自动处理时区问题

3. 性能考虑

• 清理操作是异步的，不会阻塞其他功能
• 只在必要时执行清理（有服务器需要清理时）
• 清理结果会缓存，避免重复计算

故障排除

常见问题

Q: 为什么服务器没有被自动清理？
A: 检查服务器的 last_success_time 是否真的超过10天，或者使用 /mccleanup 手动触发

Q: 如何查看服务器的查询状态？
A: 使用 /mclist 查看所有服务器，或直接查看JSON配置文件

Q: 可以修改清理天数吗？
A: 可以，修改 script/json_operate.py 中的 AUTO_CLEANUP_DAYS 常量

Q: 清理操作会影响正常使用吗？
A: 不会，清理操作是异步的，不会阻塞其他功能

Q: 如何恢复被删除的服务器？
A: 被删除的服务器无法自动恢复，需要重新使用 /mcadd 添加

Q: 支持通过ID操作吗？
A: 是的，所有命令都支持通过名称或ID进行操作

最佳实践

1. 定期维护

• 每周使用 /mc 命令查询一次所有服务器
• 定期使用 /mccleanup 手动清理
• 关注清理结果，及时处理问题

2. 服务器管理

• 及时删除不再使用的服务器
• 定期检查服务器状态
• 保持服务器列表的整洁

3. 监控建议

• 关注失败次数较多的服务器
• 定期检查最后成功时间
• 根据清理结果调整服务器配置

支持

• AstrBot 帮助文档
• GitHub Issues

TODO

• 定时自动查询功能

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

贡献

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