koishi-plugin-minecraft-search

一个用于查询 Minecraft 服务器状态和控制麦块联机服务器的 Koishi 插件。

功能特性

🎮 服务器状态查询

• 支持 Java 版服务器
• 支持查询全部服务器状态（简短信息）
• 支持查询指定服务器状态（详细信息）
• 可配置查询超时时间
• 自动移除 Minecraft 颜色代码，显示纯文本 MOTD

⚡ 服务器电源控制

• 支持通过麦块联机 API 启动服务器
• 支持通过麦块联机 API 重启服务器
• 支持通过麦块联机 API 强制重启服务器
• 自动重试机制，提高操作成功率

📊 服务器资源查询

• 支持通过麦块联机 API 查询服务器资源使用情况
• 显示 CPU、内存、磁盘使用情况
• 显示网络接收和发送数据量
• 显示服务器运行时间
• 显示服务器状态和暂停状态

🗄️ 数据库存储

• 使用数据库存储服务器配置，支持多群组管理
• 支持按群组绑定服务器，每个群组只能管理自己的服务器
• 支持 API 密钥按群组存储

🔧 服务器管理

• 支持绑定服务器（自动解析地址和端口）
• 支持解绑服务器
• 支持修改服务器信息（名称、超时时间）
• 支持设置麦块实例ID
• 支持查看服务器列表

安装

1. 安装插件：

npm install koishi-plugin-minecraft-search

2. 在 Koishi 配置文件中启用插件。

配置说明

基础配置

{
  "minekuaiApiUrl": "https://minekuai.com/api/client", // 麦块API地址
  "showIpInDetail": true, // 是否在详细状态中显示IP地址
  "enablePermissionCheck": false, // 启用管理员权限检查
  "allowMemberPowerCommands": true // 允许普通成员使用开服、重启、强制重启指令
}

使用指令

服务器管理

mc/绑定服务器 <host> [-n <name>] [-t <timeout>] [-i <instance>]  # 绑定服务器，支持指定名称、超时时间和麦块实例ID
mc/解绑服务器 <id>                               # 解绑服务器
mc/修改服务器 <id> [-n <name>] [-t <timeout>] [-i <instance>]    # 修改服务器信息，支持修改名称、超时时间和麦块实例ID
mc/服务器列表                              # 查看已绑定的服务器列表
mc/设置实例 <id> <instanceId>              # 设置服务器的麦块实例ID
mc/绑定API密钥 <apiKey>                    # 绑定麦块API密钥
mc/服务器状态 <id> [状态]                   # 查询或设置服务器活跃状态（状态：启用/停用）

查询服务器状态

mc/查服        # 查询全部服务器状态（简短信息）
mc/查服 1      # 查询ID为1的服务器的详细信息
mc/查服 <ip>   # 直接输入IP地址查询服务器状态

输出示例：

📊 服务器状态汇总 (当前在线2/3台)

[ID:1] 🟢 主服务器 - 在线 | 玩家: 15/50 | 版本: 1.20.1
[ID:2] 🟢 生存服 - 在线 | 玩家: 8/30 | 版本: 1.19.4
[ID:3] 🔴 创造服 - 离线

💡 输入"查服+服务器ID"即可查询详细状态，例如：查服 1

服务器电源控制

mc/开服 1      # 启动ID为1的麦块服务器
mc/重启 1      # 重启ID为1的麦块服务器
mc/强制重启 1  # 强制重启ID为1的麦块服务器

服务器资源查询

mc/资源 1      # 查看ID为1的麦块服务器资源使用情况

输出示例：

📊 服务器名称 资源使用情况
📋 状态: 运行中
🔄 暂停: 否
🖥️ CPU: 33.08%
💾 内存: 10.71GB
💿 磁盘: 18.50GB
📡 网络接收: 384.50MB
📡 网络发送: 2679.00MB
⏱️ 运行时间: 425天 12小时 39分钟 5秒
⏰ 查询时间: 2026-03-13 12:00:00

指令说明

绑定服务器

• 命令：mc/绑定服务器 <host> [-n <name>] [-t <timeout>] [-i <instance>]
• 参数：
  • <host>：服务器地址，支持带端口格式（如：play.example.com:25565）
  • -n <name>：服务器名称（可选，默认使用地址作为名称）
  • -t <timeout>：查询超时时间（可选，默认5秒）
  • -i <instance>：麦块实例ID（可选，用于电源控制）
• 示例：
  • mc/绑定服务器 s3.ungc.com.cn - 绑定默认端口的服务器
  • mc/绑定服务器 s3.ungc.com.cn:37095 -n 测试服 -t 10 - 绑定指定端口、名称和超时的服务器
  • mc/绑定服务器 s3.ungc.com.cn -i abc123 - 绑定服务器并设置麦块实例ID

绑定API密钥

• 命令：mc/绑定API密钥 <apiKey>
• 参数：
  • <apiKey>：麦块联机平台的API密钥
• 说明：每个群组只需绑定一次，后续会自动使用该密钥

服务器管理指令

• mc/解绑服务器 <id>：解绑指定ID的服务器
• mc/修改服务器 <id> [-n <name>] [-t <timeout>] [-i <instance>]：修改服务器名称、超时时间或麦块实例ID
• mc/设置实例 <id> <instanceId>：为服务器设置麦块实例ID，用于电源控制
• mc/服务器列表：查看当前群组已绑定的所有服务器
• mc/服务器状态 <id> [状态]：查询或设置服务器活跃状态（状态：启用/停用）

服务器控制指令

• mc/开服 <id>：启动指定服务器
• mc/重启 <id>：重启指定服务器
• mc/强制重启 <id>：强制停止并重启指定服务器
• mc/资源 <id>：查询服务器资源使用情况

技术特性

• 🔄 自动重试机制：API 请求失败时自动重试，提高成功率
• 🎯 智能地址解析：自动分离主机名和端口
• 📱 友好输出格式：使用 emoji 和清晰排版，信息易读
• ⚡ 高性能查询：支持并行查询多个服务器
• 🛡️ 错误处理：完善的错误处理和用户提示
• 🗄️ 数据库存储：使用数据库存储服务器配置，支持多群组管理
• 🔒 权限控制：支持全局权限管理，每个群组只能管理自己绑定的服务器，默认允许普通成员使用电源指令（可通过配置项调整）
• 🌐 直接IP查询：支持直接输入IP地址查询服务器状态
• 🔧 实例ID管理：支持在绑定和修改服务器时直接设置麦块实例ID

依赖说明

• 使用 https://www.npmjs.com/package/mc-server-util 库进行服务器状态查询
• 支持麦块联机平台的 API 集成
• 基于 Koishi 框架开发，依赖数据库插件

注意事项

1. 麦块联机功能需要配置正确的 API 地址和密钥
2. 服务器地址支持带端口格式（如：play.example.com:25565）
3. 插件会自动处理 MOTD 中的换行符，确保输出整洁
4. 所有服务器操作指令均限制为群组指令，只能操作本群绑定的服务器
5. API 密钥按群组存储，每个群组需要单独绑定

故障排除

如果遇到查询失败，请检查：

• 服务器地址是否正确
• 网络连接是否正常
• 防火墙是否阻止了查询请求
• 麦块 API 配置是否正确
• 服务器是否为本群绑定的服务器

更新日志

v2.0.9

• 修复指令名称不一致问题，统一使用"绑定API密钥"指令名称

v2.0.8

• 新增服务器活跃状态管理功能
• 在 minecraft_server 数据库中添加 active 字段（boolean 类型）
• 绑定服务器后默认设置为活跃状态
• 新增 mc/服务器状态 指令，支持查询和设置服务器活跃状态
• 修改 mc/查服 指令，过滤掉不活跃的服务器
• 修改 mc/服务器列表 指令，显示服务器活跃状态
• 当查询不活跃的服务器时，显示提示信息
• 兼容旧数据：已存在的服务器 active 字段为 null 时，视为活跃状态

v2.0.7

• 优化指令命名，将"绑定"改为"绑定服务器"，"解绑"改为"解绑服务器"，"修改"改为"修改服务器"

v2.0.5

• 调整权限检查配置项默认值：enablePermissionCheck 默认值改为 false，allowMemberPowerCommands 默认值改为 true
• 优化权限配置项的描述，明确权限配置仅适用于onebot机器人

v2.0.4

• 简化权限检查功能，移除群组级别的权限设置
• 优化权限检查功能配置项描述，明确仅限onebot机器人使用

v2.0.3

• 新增权限检查功能，支持全局权限控制
• 新增配置项 enablePermissionCheck 控制是否启用权限检查
• 新增配置项 allowMemberPowerCommands 控制是否允许普通成员使用电源指令
• 优化权限检查逻辑

v2.0.1

• 新增绑定服务器时支持 -i 选项直接设置麦块实例ID
• 新增修改服务器时支持 -i 选项修改麦块实例ID
• 新增支持直接输入IP地址查询服务器状态
• 优化服务器绑定逻辑，避免重复绑定
• 完善错误提示信息

v2.0.0

• 全新数据库存储架构，支持多群组管理
• 新增服务器绑定、解绑、修改等管理指令
• 支持按群组存储 API 密钥
• 增加服务器列表查看功能
• 优化错误提示，明确权限限制
• 移除配置文件中的服务器列表，改为数据库存储

v1.3.6

• 新增服务器资源使用情况查询功能
• 支持查看 CPU、内存、磁盘使用情况
• 支持查看网络接收和发送数据量
• 支持查看服务器运行时间
• 支持查看服务器状态和暂停状态

v1.3.4

• 优化错误信息显示，将英文错误信息翻译成中文
• 统一服务器状态显示格式，离线服务器显示具体错误原因
• 移除错误信息中的IP地址和域名，保护服务器隐私
• 添加对 connect ENOTFOUND 错误的处理

v1.3.0

• 替换服务器状态查询库为 mc-server-util
• 移除对基岩版服务器的支持（暂不支持）
• 移除 Query 查询选项
• 添加自动移除 Minecraft 颜色代码功能
• 优化错误处理和类型检查

v1.1.1

• 初始版本发布
• 支持服务器状态查询
• 支持麦块联机电源控制
• 支持 Java 和基岩版服务器

支持与反馈

如有问题或建议，请通过相关渠道联系开发者。