SunshineCommandGuard

插件

· 作者 sunshinepharmacy

从 Tab 补全中隐藏命令、阻止其执行,并保持插件列表的私密性——所有操作均按 LuckPerms 组进行范围限定。

0 本站下载 0 关注 更新于 1 个月前

最新 2.0.1 · 1.21.11 · Bukkit / Paper

一键开服(送7天)

SunshineCommandGuard

隐藏命令补全、阻止命令执行,并保护你的插件列表不被泄露——所有设置均基于 LuckPerms 用户组 进行独立作用域控制,并提供一个管理工具,让你在开启或关闭任何功能之前,就能确切知道为何某个特定命令会被允许或拦截。

大多数服务器都运行着数十个插件,每个插件都会注册命令、子命令以及命名空间别名,而普通玩家本不该看到这些内容。/plugins 会将你的整个插件栈暴露给任何询问者;命令补全(Tab-complete)则会泄露你所有的管理员工具。SunshineCommandGuard 在不触碰你 LuckPerms 中已有权限节点的前提下,同时关闭了这两条信息泄露渠道。

目录

功能特性

  • Tab 补全过滤:通过 PlayerCommandSendEvent 实现——玩家只能看到他们有权使用的命令。 命令不仅从建议列表中消失;客户端甚至不会得知其存在。
  • 执行拦截:玩家无权执行的命令会表现为未知命令,并显示完全自定义的消息。
  • 服务器隐私:隐藏 /plugins、/pl、/ver、/version、/about 以及 ? 帮助别名,替换为你编写的消息(保留原样的 /help:被阻止的玩家会被引导至该命令)。
  • 防枚举保护:移除带命名空间的命令标签,阻止直接执行带命名空间的命令,并过滤由客户端插件扫描器使用的直接 /version//plugins 补全探测。提供显式的命名空间例外以兼容其他插件。
  • 按组配置文件:基于 LuckPerms 权限解析的组(sunshine.cmdguard.group.<name>),支持 inherit(继承)和 priority(优先级),因此一个 staff 组可以扩展 vip,而 vip 又扩展 default,无需重复任何一行配置。
  • 灵活匹配:支持字面名称、regex: 正则表达式模式、否定 !entries(拒绝优先)、以及 plugin:<Name> 展开语法,可在单行内获取某插件注册的所有命令。
  • 隐藏别名:保持命令完全可运行,但使其从 Tab 补全中消失,适用于你不希望公开宣传但仍需正常工作的别名。
  • 参数级规则:每个命令的 args 允许/拒绝列表,例如允许玩家使用 /gamemode survival 但不允许 /gamemode creative。在 Tab 补全 和 执行时均强制生效(2.0.0+),包括带命名空间的形式及 /execute ... run。
  • 实时验证:/cmdguard test <player> <command> 会在你启用任何设置之前,打印出已解析的组、匹配的规则,以及该命令可见或被拦截的原因。
  • 一键生成配置:/cmdguard generate 扫描你的在线服务器,并生成一份经过审查的初始配置文件(config.generated.yml):无需权限即可使用的命令归入 default,受权限限制的命令归入 staff。将需要的内容复制到 config.yml 即可。
  • 交互式安装向导:/cmdguard setup 会在聊天栏引导你回答三个可点击的问题(初始列表、隐私设置、权限同步),并自动为你写入 config.yml。
  • 精确的配置验证:每次 /cmdguard reload 都会将你的列表与在线服务器的实际状态进行交叉检查,并指出具体条目中的问题:拼写错误、未知的插件、错误的正则表达式、未知的组或未加载的世界(groups.default.commands[1]: 'spwan' matches no registered command)。
  • 自我诊断:/cmdguard diagnose [player] 捕捉常见错误:过滤器未开启、使用 OP 账号测试、零可见命令、配置警告等——并附带实时统计(“可见:340 个命令中的 12 个”)。
  • 权限同步模式:可选地要求每个命令都拥有独立的 Bukkit 权限节点,这样当玩家的等级无法执行某些命令时,这些命令会自动从他们的可用列表中移除,无需手动维护列表。
  • 临时授权:/cmdguard grant <player> <command> <10m|2h|1d> 可为特定命令开放有限时间(用于活动或客服案例),/cmdguard ungrant 可收回权限。无需编辑配置文件。授权匹配精确的命令令牌:对 plugins 的授权并不涵盖 bukkit:plugins。
  • 按世界分组:可将任意组限制在特定世界中(worlds: [arena]),并在切换世界时自动刷新配置文件。
  • 拦截监控:记录所有被拦截的尝试,并/或在限流的情况下通知在线工作人员,确保侦察行为不会被忽视。
  • Discord 警报 (2.0.0):通过 Webhook 将被拦截的尝试发布到 Discord 频道,具有速率限制,默认禁用 @提及,并可配置仅报告 /pl、/ver 和带命名空间的探测请求。
  • 一键迁移 (2.0.0):/cmdguard import commandwhitelist 将 CommandWhitelist 的配置转换为可供审查的 config.imported.yml。
  • PlaceholderAPI 支持 (2.0.0):提供 %cmdguard_group%、%cmdguard_visible%、%cmdguard_filter%,可用于计分板、Tab 列表和全息图。
  • Folia 支持 (2.0.0):同一个 jar 包即可在 Paper 和 Folia 上运行。
  • 实时网页编辑器 (2.0.0):运行 /cmdguard editor 可在 Sunshine Live Web Studio 中打开你服务器真实的命令列表,通过一次点击切换命令状态(Allow、Hide in Tab、Block),并通过 /cmdguard apply <code> 实时推送更改(每个服务器均可享受 3天免费试用,之后可通过 SunshineCommandGuard Pro 永久解锁)。你的 pro-key 和 Discord Webhook URL 永远不会上传(2.0.1+)。
  • Velocity 网络支持 (Pro):代理级别的命令过滤(/server、/glist、/send 等)仅在 SunshineCommandGuard Pro 中提供(参见 Velocity networks (Pro))。
  • 更新通知:当 GitHub 上有新版本发布时,控制台和管理员上线时会收到通知(仅通知功能;详见下文)。
  • 包含 bStats 指标:已重新定位,确保不会与其他插件的副本发生冲突。

截图

以下四张截图均来自真实的生产服务器,而非演示实例——其中的拦截和隐私消息均为该服务器自身的文本,可在 config.yml 中完全自定义。

Allowed command still tab-completes normally 允许 — 白名单内的命令可正常进行 Tab 补全。 Hidden command does not appear in tab-complete 隐藏 — 不在建议列表中,甚至不被客户端自身的命令树识别——但如果完整输入仍可运行。
Non-whitelisted command is rejected as unknown 拦截 — 不在该组成员列表中的命令对客户端不可见,并被拒绝为未知命令。 The /plugins command is replaced with a custom message 服务器隐私 — /plugins 返回自定义消息,而非真实的插件列表。

依赖

  • Paper、Folia 或基于 Paper 的分支 1.21.x 至 26.x,Java 21 或更高版本(26.x 服务器运行 Java 25)
  • 可选:PlaceholderAPI 用于占位符
  • LuckPerms 为可选(softdepend):若未安装,所有玩家将回退至 default 组。
  • 拥有 bypass 权限或 OP 状态的玩家将跳过所有过滤——务必使用非 OP 账号进行测试。

安装

  1. 将 SunshineCommandGuard-2.0.1.jar 放入你的 plugins/ 文件夹并启动服务器一次 (这将创建默认的 config.yml)。
  2. 在游戏中运行 /cmdguard setup 并回答三个问题,然后运行 /cmdguard generate 以扫描你的服务器配置至 config.generated.yml,或在浏览器中使用 在线配置构建器 构建初始配置文件。
  3. 在启用之前验证:使用非 OP 测试账号执行 /cmdguard test <player> <command>(或 /cmdguard diagnose)。
  4. 设置 enabled: true,然后运行 /cmdguard reload。

从 CommandWhitelist 迁移?保留其文件夹于 plugins/ 中,运行 /cmdguard import commandwhitelist,并在覆盖前审查 config.imported.yml。

⚠️ 警告

配置错误的过滤器可能导致玩家完全看不到任何命令。因此该插件默认附带 enabled: false。在设置 enabled: true 之前,请务必检查你的用户组并为默认组玩家运行 /cmdguard test。

配置示例

极简模式 —— 隐藏除少数命令外的所有内容:

enabled: true
bypass-permission: "sunshine.cmdguard.bypass"
groups:
  default:
    priority: 0
    blocked-message: "<red>Unknown command."
    commands:
      - help
      - spawn
      - msg
      - "regex:^(msg|tell|w|r|reply)$"
      - "!op"
      - "!stop"
    hidden: []
    args: {}

基于用户组的访问控制与继承:

groups:
  default:
    priority: 0
    blocked-message: "<red>Unknown command."
    commands: [help, spawn, msg]
    hidden: []
    args: {}
  vip:
    priority: 10
    inherit: [default]
    commands: [hat, nick, workbench]
    hidden: [ecraft, ehat]
    args:
      gamemode:
        allow: [survival, creative]
        deny: []
  staff:
    priority: 50
    inherit: [vip]
    commands: ["plugin:WorldEdit"]
    hidden: []
    args: {}

服务器隐私保护 —— 替换 /plugins、/ver 和帮助别名(纯 /help 故意保持可见:它是被拦截消息引导玩家使用的后备选项):

privacy:
  plugins-command:
    enabled: true
    message: "<gold>My Server <grey>| <white>Server information is private."
    aliases: [plugins, pl, "bukkit:pl", "bukkit:plugins", ver, version, about, icanhasbukkit]
  help-command:
    enabled: true
    message: "<yellow>Type <white>/help <yellow>for a list of commands."
    aliases: ["?", "bukkit:help", "minecraft:help"]

客户端插件扫描防护 —— 隐藏带命名空间的别名并阻止直接补全探测。此部分仅在全局过滤器启用时生效:

anti-enumeration:
  enabled: true
  hide-namespaced-commands: true
  block-namespaced-execution: true
  block-completion-probes: true
  namespace-allowlist: []

为了实现纵深防御,请在 spigot.yml 中也设置 commands.send-namespaced: false。 该插件会在 /cmdguard diagnose 中报告此项服务器设置。

复制粘贴配方

EssentialsX 生存服 —— 仅限常用玩家命令,无其他内容:

enabled: true
groups:
  default:
    priority: 0
    blocked-message: "<red>Unknown command."
    commands:
      - help
      - spawn
      - home
      - sethome
      - delhome
      - tpa
      - tpaccept
      - tpdeny
      - msg
      - mail
      - pay
      - balance
      - kit
      - warp
      - afk
      - rules
      - "regex:^(msg|tell|w|r|reply)$"
      - "!op"
      - "!stop"
    hidden: []
    args: {}
    worlds: []

小游戏大厅 + 生存世界 —— 大厅命令仅在其所属世界中存在:

enabled: true
groups:
  default:
    priority: 0
    blocked-message: "<red>Unknown command."
    commands: [help, spawn, msg]
    hidden: []
    args: {}
    worlds: []
  minigames:
    priority: 20
    inherit: [default]
    commands: [queue, leave, spectate, party]
    hidden: []
    args: {}
    worlds: [arena, lobby]

严格模式 —— 极短的列表加上权限同步,使得命令还需要其对应的 Bukkit 权限节点,且新安装的插件在未获允许前保持隐藏:

enabled: true
permission-sync: true
groups:
  default:
    priority: 0
    blocked-message: "<red>Unknown command."
    commands: [help, rules]
    hidden: []
    args: {}
    worlds: []

匹配规则: 条目匹配不区分大小写,可带或不带前导 /,带命名空间的标签(如 essentials:heal)也能匹配其基础名称(heal)。!entry 表示拒绝(拒绝始终优先于任何允许),regex:<pattern> 允许完整匹配的模式,plugin:<Name> 会展开为该插件注册的所有命令。hidden 条目可运行但不会在 Tab 补全中显示建议——用于你不希望推广的别名。当启用 anti-enumeration.hide-namespaced-commands 时,带命名空间的标签将从命令树和 Tab 补全中隐藏。当启用 anti-enumeration.block-namespaced-execution 时,除非命名空间列在 namespace-allowlist 中,否则直接执行也会被阻止。

可选的全局模式(旧配置可安全加载;缺失 anti-enumeration 部分的配置将获得安全的默认值):

# 同时要求每个命令拥有独立的 Bukkit 权限节点。
permission-sync: false

monitoring:
  log-blocked: false        # 记录控制台上的每次拦截尝试
  notify-staff: false       # 在被拦截尝试时向在线工作人员发送消息
  notify-permission: "sunshine.cmdguard.notify"
  notify-cooldown-seconds: 5  # 每位玩家的冷却时间

updates:
  enabled: true             # GitHub Releases 检查(仅通知)
  notify-console: true
  notify-admins: true

按世界分组的组 — 带有 worlds 的组仅在该世界生效(为空表示所有世界)。 如果 default 本身限制了世界,则会收到配置警告,因为那些世界之外的玩家将不会被过滤:

groups:
  minigames:
    priority: 20
    inherit: [default]
    commands: [queue, leave, spectate]
    hidden: []
    args: {}
    worlds: [arena, lobby]

命令与权限

命令 权限 描述
/cmdguard reload sunshine.cmdguard.admin 重新加载配置、重建索引、清除缓存
/cmdguard refresh <player> sunshine.cmdguard.admin 清除单个玩家的缓存并重新发送命令树
/cmdguard test <player> <command> [args] sunshine.cmdguard.admin 显示命令所属的组、可见性、原因(及参数规则)
/cmdguard debug sunshine.cmdguard.admin 在运行时暂停/恢复过滤(不写入配置)
/cmdguard dump sunshine.cmdguard.admin 将所有注册的命令写入 commands_dump.yml
/cmdguard generate sunshine.cmdguard.admin 生成一份可供审查的检查就绪的初始配置到 config.generated.yml
/cmdguard import commandwhitelist sunshine.cmdguard.admin 将 CommandWhitelist 配置转换为 config.imported.yml
/cmdguard grant <player> <command> <30s|10m|2h|1d> sunshine.cmdguard.admin 临时允许执行某个命令(仅内存保留,重启后丢失)
/cmdguard ungrant <player> [command] sunshine.cmdguard.admin 撤销一个或所有临时授权
/cmdguard setup sunshine.cmdguard.admin 交互式聊天设置(仅限玩家):初始列表、隐私、同步、防枚举
/cmdguard diagnose [player] sunshine.cmdguard.admin 检查常见错误,显示实时计数和防枚举状态
/cmdguard editor sunshine.cmdguard.admin 上传已注册的命令及 config.yml 至 Live Web Studio(3天免费试用 + Pro)
/cmdguard apply <code> sunshine.cmdguard.admin 备份 config.yml 并应用保存在 Live Web Studio 中的更改
权限 默认值 描述
sunshine.cmdguard.bypass op 绕过所有命令过滤
sunshine.cmdguard.admin op 允许使用 /cmdguard
sunshine.cmdguard.notify op 接收被拦截命令的管理员通知
sunshine.cmdguard.group.<name> — 将玩家分配到 <name> 组(通过 LuckPerms)

Discord 警报

monitoring:
  discord:
    enabled: true
    webhook-url: "https://discord.com/api/webhooks/..."
    cooldown-seconds: 10        # 每位玩家
    max-per-minute: 20          # 整个 webhook
    only-reconnaissance: false  # true = 仅 /pl, /ver 和命名空间探测

每条警报格式如下:? **Steve** tried `/plugins` — privacy (group: default)。@提及功能已禁用,请求是异步进行的,且 webhook URL 绝不会记录到日志中。

PlaceholderAPI

占位符 值
%cmdguard_group% 玩家优先级最高的组
%cmdguard_visible% 玩家可见的命令数量
%cmdguard_filter% enabled 或 disabled

Velocity 网络(Pro)

Velocity 自身的代理命令(如 /server、/glist、/send 等)由代理处理, 永远不会到达后端 Paper 服务器,因此后端插件无法隐藏或阻止它们。

SunshineCommandGuard Pro 添加了具有相同分组规则的配套 Velocity 代理插件 (字面量、regex:、!deny、inherit、priority)、sunshine.cmdguard.group.<name> LuckPerms 权限以及 /cmdguardv reload|test 诊断工具,同时将所有后端命令传递给 Paper 插件。

常见问题

这能替代 LuckPerms 吗? 不能。LuckPerms 仍然控制玩家有权运行什么。 SunshineCommandGuard 控制玩家看到什么,以及当他们尝试超出其组范围的操作时会发生什么—— 权限系统和可见性过滤器解决的是两个不同的问题,本插件仅解决后者。

OP 和管理员会受到影响吗? 不会,这是设计使然——sunshine.cmdguard.bypass 默认为 op,因此操作员始终可以看到并运行所有内容。请使用真实的非 OP 账号进行测试,否则 当你实际上并未被应用过滤器时,它看起来像是坏了。

如果一个玩家已经知道某个被隐藏的命令会发生什么? 它仍然可以运行。hidden 仅从自动补全建议中移除命令;它与 commands 是不同的列表,后者控制命令是否真正运行。 对于不想宣传的别名请使用 hidden,而对于真正想禁止的命令请使用普通的阻断列表。

客户端仍能否枚举插件? 防枚举盾牌移除了命名空间的命令标签并阻止了常见的直接补全探测。 但这并不能保证插件行为永远无法被推断出来;公开命令、消息、资源包数据和其他服务器行为 仍可能泄露信息。不要依赖客户端品牌检测,因为修改过的客户端可以伪造其品牌。

这会影响服务器性能吗? 过滤仅在加入服务器和 /cmdguard reload 时运行,而不是在每次按键时—— 每个玩家的命令树只重建一次,而不是为每次 Tab 键按下重新计算。

我可以不使用 LuckPerms 吗? 可以。LuckPerms 是软依赖;如果没有它,所有玩家都会解析为 default 组。

兼容性

基于 Paper 1.21.4 API (Java 21) 构建。已在干净的 Paper 26.2 服务器上测试。 支持 Paper、Folia (2.0.0+,通过每玩家实体调度) 及兼容的 Paper 分支。 未测试较旧或较新的服务器版本——请在您的设置下遇到问题或成功时提交 Issue。

开发者 API (1.4.0+)

CommandGuard 为 Sunshine Sentinel 等集成触发公共监控事件:

  • com.sunshine.commandguard.api.event.CommandGuardBlockedEvent — 在命令尝试被确切地阻止一次后触发,包含 getPlayerId()、getPlayerName()、getCommandToken()、getReason()(类型为 com.sunshine.commandguard.api.BlockReason)、getTimestamp() 和 getWorld()。BlockReason 为以下之一:PRIVACY、NAMESPACE_PROTECTION、PERMISSION_SYNC、GROUP_LIST 以及(2.0.0+)ARGUMENT_RULE。
  • 不可取消 —— 监听器仅观察决策结果,永远无法解除对命令的阻止。
  • Token 是标准化后的根命令,所有参数均被剥离且命名空间保留:/plugins → plugins,/BUKKIT:Plugins → bukkit:plugins,/minecraft:help foo bar → minecraft:help。
  • 隐私保护: 事件中永远不会出现任何命令参数、聊天内容、IP 地址或凭据。

从源代码构建

.\gradlew.bat build   # 需要 JDK 21,输出文件位于 build/libs/SunshineCommandGuard-2.0.1.jar
.\gradlew.bat test    # 单元测试 (JUnit 5)

上传的 jar 包必须是 shadowJar 的输出结果(build/libs/...),其中捆绑了 bStats(已重定位至 com.sunshine.cmdguard.bstats,以确保与其他插件无冲突)。build.ps1 仍作为原作者机器上的快速本地编译脚本保留。

指标统计

本插件通过 bStats 收集匿名使用统计数据。服务器管理员可以在 plugins/bStats/config.yml 中选择退出。

更新通知

CommandGuard 可在每次服务器启动时检查 GitHub Releases 是否有新版本。SunshineCommandGuard 绝不会自动下载或安装更新。

updates:
  enabled: true
  notify-console: true
  notify-admins: true

设置 updates.enabled: false 将完全禁用外部更新请求——不会发起任何 HTTP 调用,也不会显示任何消息。持有 sunshine.cmdguard.admin 权限的管理员在加入服务器时会在每个服务器会话期间收到一次通知,并附带指向发布页面的可点击链接。该检查仅为通知性质:不下载、不重启、无遥测数据。

关键词

command hide, tab complete, plugin hide, pl hide, command blocker, permissions, luckperms

许可证

GPL-3.0 — 请参阅 LICENSE。衍生作品必须保持开源。

欢迎提交问题报告 (Issues) 和拉取请求 (Pull requests)。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源