小猪管理员

小猪管理员

一个用于帮助管理反作弊设置和管理服务器的服务器端管理模组

管理

build test release

Piggy Admin

一个服务端管理模组,旨在帮助管理和强制执行兼容客户端模组(如 Piggy Build 和 Piggy Inventory)的设置。目前,它作为管理反作弊选项、日志记录和检测的中心枢纽,但未来将扩展以包含更多管理工具。


⚠️ 免责声明

这是一个个人项目。 它按原样提供,可能会引发问题。

  • 无支持:不要期望获得定期支持或错误修复。
  • 无 Forge 移植:没有将此模组移植到 Forge 的计划。
  • 使用风险自负。

如果你想贡献修复或功能,欢迎 Fork 该项目或提交 Pull Request!


功能

🛡️ 反作弊强制

  • 集中控制:配置服务器上是否允许“作弊”功能(如快速放置、工具切换)。
  • 自动同步:当玩家加入时,服务器的反作弊配置会自动发送到其客户端。
  • 严格强制:如果服务器禁用作弊,客户端覆盖将被忽略,确保公平游戏。
  • 细粒度控制:单独启用/禁用特定功能(例如,允许工具切换但禁止快速放置)。

🕵️ 高级 X-Ray 检测

Piggy Admin 使用多层启发式引擎来检测可疑的挖掘模式,而不会因分支挖掘产生误报。

  • 矿石缓存管理器:在高效的 ConcurrentHashMap 中异步跟踪有价值的矿石位置,最大限度地减少主线程影响。
  • 向量相关性:使用 HeuristicsMathUtil 计算玩家视线向量与不可见矿石距离之间的数学相关性。
  • 混合检测器:结合原始挖掘比率与对“可疑转向”和“直通矿石”路径的语义分析。
  • 灵敏度级别:从 LOW(宽松)到 PARANOID(严格),可通过 xraySensitivity 配置。
  • 管理员警报:为管理员提供实时通知,包含可点击的传送链接到可疑玩家的坐标。

📜 取证数据与归属

该模组是调查破坏行为的强大工具。

  • 爆炸归属:跟踪 TNT 的真正所有者,即使是由打火石、火焰弹或其他实体点燃的。
  • 苦力怕归属:识别故意点燃苦力怕(使用打火石)以破坏领土的玩家。
  • 岩浆与火焰归责:用于流体流动和方块火焰蔓延的专用跟踪器。即使原始源方块已消失,模组也会保留放置者的历史记录。
  • 发射器跟踪:在发射器层面的自定义 Mixin 将所有发射的弹射物或桶操作归属于放置或最后与发射器交互的玩家。
  • 交互式通知:AdminNotifier 向 OP 发送丰富的、可悬停的聊天组件,允许直接从警报中进行即时“归责查询”。

📜 审核引擎

  • AI 驱动的审核:与 Google Gemini AI 集成,自动过滤有毒或不适当的聊天和告示牌文本。
  • 动态规则系统:定义自定义审核规则和类别(例如,脏话、骚扰、仇恨言论)。
  • 性能优化:包含高性能缓存和速率限制系统,以最大限度地减少 API 延迟并优雅地处理免费层 API 限制。
  • 混合检查:结合快速的本地 正则 检查与 Gemini 的深度语义分析。
  • 分类日志:所有被阻止的消息都按其特定类别记录,便于审查。

🤖 Gemini AI 设置

要使用 AI 审核功能,你需要一个 Google Gemini API 密钥。

  1. 获取 API 密钥:访问 Google AI Studio 并创建一个免费 API 密钥。
  2. 配置模组:
    • 启动一次服务器以生成配置文件。
    • 打开 config/piggy-admin-server.json。
    • 将你的密钥粘贴到 "geminiApiKey" 字段中。
    • 设置 "moderationEnabled": true。
  3. 高级选项:
    • geminiModel:默认为 gemini-1.5-flash(推荐用于速度和成本)。
    • geminiSystemPrompt:你可以在此自定义 AI 的“个性”和严格程度。

[!NOTE] Gemini 的免费层有速率限制(约每分钟 15 次请求)。模组包含内置缓存和速率限制器,以优雅地处理这些限制,而不会导致服务器卡顿。

📜 历史记录与日志

  • 告示牌历史:跟踪谁放置了告示牌以及上面写了什么。
  • 聊天历史:记录所有聊天消息以供管理审查。
  • 爆炸日志:TNT 放置、点燃和爆炸的详细日志,尽可能包括玩家归属。
  • 归责工具:检查现有的告示牌/方块,查看谁在何时与它们交互过。
  • 持久化存储:历史记录在服务器重启后仍保留(保存到 config/piggy-admin-history.json)。

命令

所有命令需要 OP 等级 2 或更高。

通用管理

  • /piggy cheats <allow|forbid>:全局允许或禁止所有玩家的“作弊”功能。
  • /piggy feature list:列出所有可控功能及其当前状态。
  • /piggy feature <id> <enable|disable>:启用或禁用特定功能(例如,flexible_placement、tool_swap)。
  • /piggy sync:手动触发所有管理设置和审核规则同步到所有连接的客户端。

调查与日志

  • /blame:看着一个方块或告示牌并运行此命令以查看交互历史。
    • 适用于:火、岩浆、告示牌、容器和爆炸区域。
  • /logs <player>:查看玩家的分类历史(聊天、告示牌、火、爆炸、审核)。
    • 可点击传送:日志条目包含坐标,你可以点击以调查现场。
  • /piggy xray <clear|stats>:管理 X-Ray 启发式缓存或查看当前玩家排名。

配置

模组在 config/piggy-admin-server.json(服务端)生成配置文件。

{
  "allowCheats": false,
  "features": {
    "flexible_placement": true,
    "fast_place": false,
    "tool_swap": true
  },
  "xrayCheck": true,
  "xrayMaxRatio": 0.15,
  "xrayMinBlocks": 20,
  "moderationEnabled": true,
  "geminiApiKey": "YOUR_KEY",
  "geminiModel": "gemini-1.5-flash"
}
  • "allowCheats": false:强制所有连接的客户端禁用受限功能。
  • "allowCheats": true:允许客户端使用其本地设置。
  • "features":对单个功能的细粒度控制。
  • "xrayMaxRatio":稀有矿石与总方块的允许最大比率(默认 15%)。
  • "xrayMinBlocks":X-Ray 检测激活前挖掘的最少方块数(默认 20)。
  • "xrayCheck":切换 X-Ray 检测系统。
  • "moderationEnabled":切换 AI 和正则审核引擎。
  • "geminiApiKey":你的 Google Gemini API 密钥。
  • "geminiModel":要使用的 Gemini 模型(默认:gemini-1.5-flash)。

依赖与安装

要求

  • Minecraft:~1.21.1
  • Fabric Loader:>=0.18.1
  • Java:>=21

必需模组

安装

  1. 从 Releases 下载 .jar 文件。
  2. 为 Minecraft 1.21.1 安装 Fabric Loader。
  3. 将 piggy-admin jar(连同 Fabric API 和 Piggy Lib)放入服务器的 mods 文件夹。
  4. 启动服务器!

待办 / 未来功能

  • 检测 XRay:实现启发式/检查以检测使用 XRay 材质包或模组的玩家。
  • 审核告示牌文本:添加工具以检查和过滤告示牌上的文本,防止不适当的内容。

灵感来源

此模组受以下启发:

  • ItemSwapper - 服务端物品管理和切换机制的概念。

许可证:CC0-1.0