Allow group owners and admins to manage MOTD server settings

This commit is contained in:
itxiaohui committed 2026-10-05 13:38:37 +08:00
1 parent 2144e218ec
commit 1bbecbfaa1
8 files changed
+352 -14

No files matched your search

+13 -4
View File
@@ -7,7 +7,7 @@ Minecraft Java 服务器状态查询插件,适用于 AstrBot 的 QQ 官方机
## 保留的功能
- `/motd`、`/mc`、`/mcstatus` 三个命令入口;群默认服务器查询与临时地址查询。
- 机器人管理员设置/清除群默认服务器,支持 `set / 设置`、`unset / clear / 清除 / 取消`。设置成功后立即查询。
- 本群群主、群管理员或机器人管理员均可设置/清除群默认服务器,支持 `set / 设置`、`unset / clear / 清除 / 取消`。设置成功后立即查询。
- 查询在线/离线、版本、MOTD、在线/上限人数、人数进度条、公开玩家样本、服务器图标。没有图标时显示像素苦力怕。
- Minecraft 状态握手和 ping/pong 测得的真实 RTT;保留域名 SRV 解析与显式端口。
- 保留原像素风图片;图片渲染或上传失败时回复文字,包含人数历史摘要。
@@ -69,17 +69,26 @@ Windows 自动使用系统微软雅黑。Linux / Docker 建议在 AstrBot 运行
| `/motd` | 查询本群默认服务器,并显示波动图 |
| `/motd mc.example.com` | 临时查询,不改变群默认设置 |
| `/motd mc.example.com:25565` | 指定端口查询 |
| `/motd set mc.example.com` | 管理员设置本群服务器并立即查询 |
| `/motd unset` | 管理员清除本群服务器 |
| `/motd set mc.example.com` | 群主/群管理员/机器人管理员设置本群服务器并立即查询 |
| `/motd unset` | 群主/群管理员/机器人管理员清除本群服务器 |
| `/motd identity` | 查看当前用户在本群的授权标识(不会授予权限) |
| `/motd history` | 默认服务器的状态与 24 小时波动 |
| `/motd history mc.example.com` | 指定服务器的状态与波动 |
| `/motd help` | 帮助 |
私聊可以临时查询地址;默认服务器设置/清除在群聊中使用。当前查询 Minecraft **Java 版**,保持旧项目的查询范围。
### 群管理权限
`set` 和 `unset` 都允许本群群主、本群管理员以及机器人管理员操作,普通群成员可以查询状态和历史。群角色取自平台消息中的 `sender.role` / `author.member_role`;消息没有角色时尝试通过平台群成员接口核实,不能用 AstrBot 全局 `event.is_admin()` 代替群角色。
OneBot 支持读取群消息角色及查询成员信息。QQ 官方(WebSocket / Webhook)支持读取消息原始角色,并复用当前适配器的鉴权请求查询 `/v2/groups/{group_openid}/members/{member_openid}`。实际可用性取决于机器人接口权限;[QQ SDK 的群成员接口说明](https://zhinjs.github.io/qq-official-bot/api/group.html#群成员查询) 介绍了接口权限限制。角色无法核实会明确提示,不会把普通成员当作管理员。
如果 QQ 官方接口无法提供角色,可以由机器人管理员配置**单群授权**:让该群管理人员在对应群发送 `/motd identity`,把返回的 `平台ID|群ID|用户ID` 加入插件 `group_admin_ids`。该授权只允许此人在此群管理 MOTD,不会获得全局机器人权限,也不对其他群生效。群管理人员变更后应移除旧授权。
## 配置
在 WebUI 插件配置中调整:`bot_name`、`admin_ids`、`api_url`、`request_timeout`、`ping_timeout`、`history_enabled`、`sample_interval`、`retention_hours`、`monitor_servers`、`font_path`。后台采样参数修改后重载插件。
在 WebUI 插件配置中调整:`bot_name`、`admin_ids`、`group_admin_ids`、`api_url`、`request_timeout`、`ping_timeout`、`history_enabled`、`sample_interval`、`retention_hours`、`monitor_servers`、`font_path`。后台采样参数修改后重载插件。
## 本地验证与打包
+1
View File
@@ -1,6 +1,7 @@
{
"bot_name": {"description": "状态卡署名", "type": "string", "default": "xiaohuicat"},
"admin_ids": {"description": "额外机器人管理员 ID", "type": "list", "default": [], "hint": "AstrBot 管理员自动拥有权限。QQ 官方机器人请填写平台用户 ID/openid,可通过 /sid 查看,不要填写旧机器人的数字 QQ 号。"},
"group_admin_ids": {"description": "本群管理授权(平台无法获取群角色时)", "type": "list", "default": [], "hint": "通常自动识别群主/群管理员,无需填写。QQ 官方接口无法获取角色时,让该群管理人员在对应群发送 /motd identity,把返回的 平台ID|群ID|用户ID 填入此列表,只授权该用户管理该群 MOTD,不授予全局机器人管理权限。群管理人员变更后请及时移除旧授权。"},
"api_url": {"description": "备用查询 API", "type": "string", "default": "https://api.mcsrvstat.us/2/{address}", "hint": "直连失败时使用,保留 {address} 占位符。响应应为 mcsrvstat.us 格式。"},
"request_timeout": {"description": "备用 API 超时(秒)", "type": "float", "default": 10.0},
"ping_timeout": {"description": "Minecraft 直连超时(秒)", "type": "float", "default": 4.0},
+38 -6
View File
@@ -14,13 +14,15 @@ from .services.address import normalize_address
from .services.mc_api import MinecraftServerAPI
from .services.monitor import PlayerMonitor
from .services.motd_card import render_motd_card
from .services.permissions import get_group_role
from .services.storage import MotdStore
HELP = """Minecraft MOTD 查询
/motd 查询本群默认服务器
/motd 服务器地址 临时查询(不改变默认设置)
/motd set 服务器地址 设置本群服务器(机器人管理员)
/motd unset 清除本群设置(机器人管理员)
/motd set 服务器地址 设置本群服务器(群主/群管理员/机器人管理员)
/motd unset 清除本群设置(群主/群管理员/机器人管理员)
/motd identity 查看本群授权标识(平台无法识别群角色时使用)
/motd history [服务器地址] 查看最近 24 小时玩家波动
/motd help 查看帮助
别名:/mc、/mcstatus;设置、清除、取消、波动、趋势也可使用。
@@ -70,6 +72,19 @@ class MotdPlugin(Star):
str(value) for value in self.config.get("admin_ids", [])
}
@staticmethod
def _group_authorization_key(event):
return f"{event.get_platform_id()}|{event.get_group_id()}|{event.get_sender_id()}"
async def _can_manage_group(self, event):
if self._is_admin(event):
return True, True
# Manual grants are confined to one adapter instance, group and user.
if self._group_authorization_key(event) in self.config.get("group_admin_ids", []):
return True, True
role = await get_group_role(event)
return role in {"owner", "admin"}, role is not None
@filter.command("motd", alias={"mc", "mcstatus"})
async def motd(self, event: AstrMessageEvent, action: str = "", address: str = ""):
"""查询 Minecraft 状态、设置群默认服务器,以及查看 24 小时玩家波动图。"""
@@ -93,12 +108,18 @@ class MotdPlugin(Star):
if verb in {"help", "帮助"}:
await event.send(event.plain_result(HELP))
return
if verb in {"set", "设置", "unset", "clear", "清除", "取消"}:
if not self._is_admin(event):
if verb in {"identity", "身份"}:
if not event.get_group_id():
await event.send(event.plain_result("⚠️ 请在群内查看授权标识。"))
else:
await event.send(
event.plain_result("❌ 只有机器人管理员可以设置或清除本群 MOTD 服务器。")
event.plain_result(
"本群授权标识(仅供机器人管理员配置,本命令不会授予权限):\n"
+ self._group_authorization_key(event)
)
)
return
return
if verb in {"set", "设置", "unset", "clear", "清除", "取消"}:
if not event.get_group_id():
await event.send(
event.plain_result(
@@ -106,6 +127,17 @@ class MotdPlugin(Star):
)
)
return
allowed, verified = await self._can_manage_group(event)
if not allowed:
message = "❌ 只有本群群主、群管理员或机器人管理员可以设置或清除 MOTD 服务器。"
if not verified:
message += (
"\n⚠️ 平台未提供可用的群角色信息,暂时无法核实身份。"
"请检查群成员查询接口权限,或发送 /motd identity,"
"由机器人管理员在插件配置 group_admin_ids 中按群授权。"
)
await event.send(event.plain_result(message))
return
if verb in {"set", "设置"}:
if not address:
raise ValueError("格式: /motd set 服务器地址")
+1 -1
View File
@@ -1,7 +1,7 @@
name: astrbot_plugin_motd
display_name: Minecraft MOTD 与玩家波动
desc: Minecraft Java 服务器状态图片、群默认服务器、真实 Ping、玩家名单和最近 24 小时人数波动图。
version: v1.0.0
version: v1.0.1
author: itxiaohui
support_platforms:
- qq_official
+100
View File
@@ -0,0 +1,100 @@
"""Resolve the sender's group role without confusing it with AstrBot's global admin role."""
import asyncio
import logging
from collections.abc import Mapping
from urllib.parse import quote
logger = logging.getLogger(__name__)
ROLES = {"owner", "admin", "member"}
def field(value, key, default=None):
return value.get(key, default) if isinstance(value, Mapping) else getattr(value, key, default)
def role_of(value):
for key in ("member_role", "role"):
role = field(value, key)
if isinstance(role, str) and role.lower() in ROLES:
return role.lower()
return None
async def get_group_role(event) -> str | None:
"""Return owner/admin/member, or None if the platform cannot verify membership."""
group_id, user_id = str(event.get_group_id()), str(event.get_sender_id())
if not group_id or not user_id:
return None
platform = event.get_platform_name()
message = getattr(event, "message_obj", None)
raw = field(message, "raw_message")
if platform == "aiocqhttp":
if (
field(raw, "group_id", group_id) is not None
and str(field(raw, "group_id", group_id)) != group_id
):
return None
if str(field(field(raw, "sender"), "user_id", user_id)) != user_id:
return None
role = role_of(field(raw, "sender"))
elif platform in {"qq_official", "qq_official_webhook"}:
# New AstrBot parsers retain raw_data even when botpy drops author fields.
raw_data = field(raw, "raw_data")
if str(field(raw_data, "group_openid", field(raw, "group_openid", group_id))) != group_id:
return None
author = field(raw_data, "author", field(raw, "author"))
if str(field(author, "member_openid", user_id)) != user_id:
return None
role = role_of(field(raw_data, "author")) or role_of(field(raw, "author"))
else:
return None
if role:
return role
async def lookup():
bot = getattr(event, "bot", None)
if platform == "aiocqhttp":
routing = {}
self_id = field(raw, "self_id")
if self_id is not None:
routing["self_id"] = self_id
info = await bot.call_action(
"get_group_member_info",
group_id=int(group_id),
user_id=int(user_id),
no_cache=True,
**routing,
)
if not isinstance(info, Mapping):
return None
if str(info.get("user_id", "")) != user_id or str(info.get("group_id", "")) != group_id:
return None
return role_of(info)
# Reuse the adapter's authenticated SDK client; do not duplicate secrets.
from botpy.http import Route
info = await bot.api._http.request(
Route(
"GET",
"/v2/groups/{group_openid}/members/{member_openid}",
group_openid=quote(group_id, safe=""),
member_openid=quote(user_id, safe=""),
)
)
if not isinstance(info, Mapping):
return None
# Some clients wrap the member response; never accept a different user's role.
info = info.get("data", info)
if not isinstance(info, Mapping) or str(info.get("member_openid", "")) != user_id:
return None
response_group = info.get("group_openid")
if response_group is not None and str(response_group) != group_id:
return None
return role_of(info)
try:
return await asyncio.wait_for(lookup(), timeout=5)
except Exception as exc:
logger.warning("MOTD 群角色查询不可用 (%s): %s", platform, type(exc).__name__)
return None
+115
View File
@@ -0,0 +1,115 @@
import sys
import types
import pytest
from services.permissions import get_group_role
class Event:
def __init__(self, platform="qq_official", raw=None, group="g", user="u", bot=None):
self.platform, self.group, self.user, self.bot = platform, group, user, bot
self.message_obj = types.SimpleNamespace(raw_message=raw)
def get_group_id(self):
return self.group
def get_sender_id(self):
return self.user
def get_platform_name(self):
return self.platform
@pytest.mark.parametrize("role", ["owner", "admin", "member"])
async def test_official_preserved_raw_data(role):
raw = types.SimpleNamespace(
author=types.SimpleNamespace(member_openid="u"),
raw_data={"author": {"member_openid": "u", "member_role": role}, "group_openid": "g"},
)
assert await get_group_role(Event(raw=raw)) == role
@pytest.fixture
def fake_botpy(monkeypatch):
class Route:
def __init__(self, method, path, **kwargs):
self.method, self.path, self.parameters = method, path, kwargs
module = types.ModuleType("botpy.http")
module.Route = Route
monkeypatch.setitem(sys.modules, "botpy", types.ModuleType("botpy"))
monkeypatch.setitem(sys.modules, "botpy.http", module)
@pytest.mark.parametrize("platform", ["qq_official", "qq_official_webhook"])
@pytest.mark.parametrize("role", ["owner", "admin", "member"])
async def test_official_authenticated_member_lookup(fake_botpy, platform, role):
seen = []
async def request(route):
seen.append(route)
return {"member_openid": "u", "member_role": role}
bot = types.SimpleNamespace(
api=types.SimpleNamespace(_http=types.SimpleNamespace(request=request))
)
assert await get_group_role(Event(platform=platform, bot=bot)) == role
assert seen[0].method == "GET"
assert seen[0].path == "/v2/groups/{group_openid}/members/{member_openid}"
assert seen[0].parameters == {"group_openid": "g", "member_openid": "u"}
@pytest.mark.parametrize(
"response",
[
{"member_openid": "wrong-user", "member_role": "owner"},
{"member_openid": "u", "member_role": "admin", "group_openid": "wrong-group"},
{"code": 11253, "message": "API not enabled"},
None,
],
)
async def test_wrong_identity_or_unavailable_official_api_never_grants(fake_botpy, response):
async def request(route):
return response
bot = types.SimpleNamespace(
api=types.SimpleNamespace(_http=types.SimpleNamespace(request=request))
)
assert await get_group_role(Event(bot=bot)) is None
async def test_onebot_live_lookup_passes_routing_and_no_cache():
seen = []
async def action(name, **kwargs):
seen.append((name, kwargs))
return {"user_id": 2, "group_id": 1, "role": "owner"}
bot = types.SimpleNamespace(call_action=action)
event = Event("aiocqhttp", raw={"self_id": 123}, group="1", user="2", bot=bot)
assert await get_group_role(event) == "owner"
assert seen == [
("get_group_member_info", {"group_id": 1, "user_id": 2, "no_cache": True, "self_id": 123})
]
async def test_api_failure_denies_without_crashing(fake_botpy):
async def request(route):
raise PermissionError("not enabled")
bot = types.SimpleNamespace(
api=types.SimpleNamespace(_http=types.SimpleNamespace(request=request))
)
assert await get_group_role(Event(bot=bot)) is None
async def test_mismatched_incoming_author_and_message_text_do_not_grant():
assert (
await get_group_role(
Event(raw={"author": {"member_openid": "wrong", "member_role": "owner"}})
)
is None
)
assert await get_group_role(Event(raw={"content": '{"member_role": "owner"}'})) is None
assert await get_group_role(Event(raw={"author": {"member_role": "admin"}}, group="")) is None
+78 -2
View File
@@ -10,8 +10,19 @@ import pytest
class Event:
def __init__(self, platform="qq-main", group="group-openid", admin=False, image_error=False):
def __init__(
self,
platform="qq-main",
group="group-openid",
admin=False,
image_error=False,
platform_name="qq_official",
raw=None,
user="user-openid",
):
self.platform, self.group, self.admin = platform, group, admin
self.platform_name, self.user = platform_name, user
self.message_obj = types.SimpleNamespace(raw_message=raw)
self.image_error = image_error
self.unified_msg_origin = f"{platform}:private:user"
self.messages = []
@@ -23,8 +34,11 @@ class Event:
def get_platform_id(self):
return self.platform
def get_platform_name(self):
return self.platform_name
def get_sender_id(self):
return "user-openid"
return self.user
def is_admin(self):
return self.admin
@@ -146,3 +160,65 @@ async def test_missing_default_invalid_and_private_setting(plugin_class):
await plugin.motd(event, "help")
assert "/mcstatus" in event.messages[-1][1]
await plugin.terminate()
@pytest.mark.parametrize("platform_name", ["qq_official", "qq_official_webhook", "aiocqhttp"])
@pytest.mark.parametrize("role", ["owner", "admin", "member"])
async def test_group_roles_can_set_and_clear_only_when_privileged(
plugin_class, platform_name, role
):
plugin = plugin_class(object(), {"history_enabled": False})
async def no_send(*args):
pass
plugin._query_and_send = no_send
raw = (
{"sender": {"role": role}}
if platform_name == "aiocqhttp"
else {"author": {"member_role": role}}
)
event = Event(platform_name=platform_name, raw=raw)
await plugin.motd(event, "set", "a.test")
scope = plugin._scope(event)
if role == "member":
assert await plugin.store.get_binding(scope) is None
assert "暂时无法核实" not in event.messages[-1][1]
await plugin.store.set_binding(scope, "original.test", "bot-admin")
await plugin.motd(event, "unset")
assert await plugin.store.get_binding(scope) == "original.test"
else:
assert await plugin.store.get_binding(scope) == "a.test"
await plugin.motd(event, "unset")
assert await plugin.store.get_binding(scope) is None
await plugin.terminate()
async def test_group_grant_is_limited_to_one_group_and_adapter(plugin_class):
plugin = plugin_class(
object(),
{"history_enabled": False, "group_admin_ids": ["qq-main|group-openid|user-openid"]},
)
async def no_send(*args):
pass
plugin._query_and_send = no_send
event = Event()
await plugin.motd(event, "set", "a.test")
assert await plugin.store.get_binding(plugin._scope(event)) == "a.test"
for outsider in [
Event(group="another-group"),
Event(platform="another-bot"),
Event(user="another-user"),
]:
await plugin.motd(outsider, "set", "unauthorized.test")
assert "无法核实" in outsider.messages[-1][1]
if outsider.group != event.group or outsider.platform != event.platform:
assert await plugin.store.get_binding(plugin._scope(outsider)) is None
else:
assert await plugin.store.get_binding(plugin._scope(outsider)) == "a.test"
await plugin.motd(event, "identity")
assert "qq-main|group-openid|user-openid" in event.messages[-1][1]
assert not plugin._is_admin(event)
await plugin.terminate()
+6 -1
View File
@@ -1,5 +1,6 @@
"""Build an installable archive without local data, test stubs, or development downloads."""
import re
from pathlib import Path
from zipfile import ZIP_DEFLATED, ZipFile
@@ -7,7 +8,11 @@ ROOT = Path(__file__).resolve().parents[1]
def main():
target = ROOT / "dist" / "astrbot_plugin_motd-v1.0.0.zip"
metadata = (ROOT / "metadata.yaml").read_text(encoding="utf-8")
version = re.search(r"^version:\s*(v[0-9]+\.[0-9]+\.[0-9]+)\s*$", metadata, re.MULTILINE).group(
1
)
target = ROOT / "dist" / f"astrbot_plugin_motd-{version}.zip"
target.parent.mkdir(exist_ok=True)
files = (
[