📖 简介

将 Minecraft 玩家 ID 与 QQ 号绑定，在 QQ 中完成白名单注册与注销，并实现对服务器内玩家的追根溯源。支持正版（online）与离线（offline）服务器，注册记录会持久化到本地 JSON 文件，供管理员随时查看。

[!IMPORTANT] 使用前请务必阅读「使用前配置」与「Bot 配置」两部分内容。插件正常工作需要你对 MC 服务器做少量配置，并为 Bot 填写必要的配置项。

功能特性

• 在 QQ 中注册 / 注销玩家白名单，自动绑定发送者的 QQ 号
• 自动生成并维护玩家 ID 与 QQ 号的绑定文件
• 支持正版（online）与离线（offline）服务器
• 管理员可查看全部已注册玩家的 ID 与 QQ 信息
• 查询服务器实时状态与在线玩家列表

🔨 依赖

• Python >= 3.9
• nonebot2 + nonebot-adapter-onebot
• httpx >= 0.22.0
• nonebot-plugin-localstore >= 0.7.4

本插件涉及到修改MC服务端的文件，因此MC服务端与Nonebot必须在同一机器内运行

💿 安装

方式一：pip 安装

在 nonebot2 项目目录下执行：

pip install nonebot-plugin-mc-whitelist-controller

方式二：git clone 安装

克隆到已建好的 NoneBot 项目目录，并在 pyproject.toml 中配置插件安装路径：

git clone https://github.com/leaf2006/nonebot-plugin-mc-whitelist-controller.git

⚠️ 使用前配置

白名单文件更新后不会立即生效，需要在服务器中执行 /whitelist reload 才会重新加载。请选择以下任一方式让服务器自动重载白名单：

• 定时任务（推荐）：大多数控制面板 / 面板服都支持定时任务。添加一个每 900 秒（15 分钟）执行一次 /whitelist reload 的任务即可。

  

• 白名单监听 Mod（试验性）：作者维护的 Minecraft Whitelist Watcher Fabric Mod 会在白名单文件变动时自动重载，目前支持的 MC 版本较少，仍在持续更新。

⚙️ Bot 配置

插件基于 nonebot-plugin-localstore 存储配置文件 config.json，默认位置：

• Windows：C:\Users\<username>\AppData\Roaming\nonebot2\nonebot_plugin_mc_whitelist_controller
• Linux：~/.config/nonebot2/nonebot_plugin_mc_whitelist_controller

不确定位置时，可在 Bot 根目录执行 nb localstore 查看。

首次运行 Bot 后，插件会自动在上述目录生成 config.json 模板；若未生成，可手动创建并按以下字段填写：

{
    "whitelist_path": "C:\\Users\\Minecraft\\whitelist.json",
    "profile_path": "",
    "server_status": "offline",
    "administrator_id": [1111111111, 2222222222],
    "address_intranet": "127.0.0.1:25565",
    "address": "example.org"
}

[!IMPORTANT] 填写文件路径时请使用 / 或 \\ 作为分隔符，不要使用单个 \，避免解析出错。 profile_path 的路径末尾必须包含文件名（即使该文件尚未创建）。

🚀 使用

指令列表

使用效果

注册玩家 leaf2006：

🤵：/注册 leaf2006
🤖：成功注册玩家leaf2006到白名单！

注册后，whitelist.json 会新增该玩家条目：

[
    {
        "uuid": "dbc89c79-8236-36b0-b2cf-7dd0b9989b27",
        "name": "leaf2006"
    }
]

同时 profile.json 会记录玩家 ID 与 QQ 号的绑定关系：

[
    {
        "name": "leaf2006",
        "qq": "此处为该玩家 QQ 号"
    }
]

[!IMPORTANT] 首次使用本插件，或切换过 server_status 配置后，请先手动将 whitelist.json 清空为 []，避免数据异常。

以上示例为离线服务器场景。

📦 旧版本

历史版本请前往 PyPI 查看。