Staff+

插件

· 作者 AyoSynk

一个易于使用的插件,集成了高级管理员工具与处罚管理功能。

0 本站下载 0 关注 更新于 2 周前

最新 1.3.0 · 26.3 · Folia / Paper

一键开服(送7天)

Staff+

Staff+

Staff+ 是一款企业级、高性能的管理与实用插件,专为现代 Minecraft 网络打造。它提供两个平台专用的 JAR 文件——一个用于 Paper/Purpur/Folia 后端服务器,另一个用于 Velocity 代理服务器——共享统一的核心引擎,从而在整个网络中实现一致的管理处罚管理。

Paper 版运行于 Paper/Purpur/Folia 1.20–1.21+ 服务器,完全支持 Folia 多线程区域安全,并包含高级管理工具,如隐身(vanish)、物品栏检查和旁观者监控。

Velocity 版运行于 Velocity 3.3.0+ 代理服务器,在玩家到达后端服务器之前,就在网络网关处执行封禁、IP 封禁和静音操作。

两个版本共享相同的数据库、配置文件和迁移系统——根据你的设置部署其中一个或两个均可。


平台对比

功能 Paper (Paper/Purpur/Folia) Velocity (代理)
Ban / TempBan / Unban ✅ ✅
IP-Ban / TempIP-Ban / UnIP-Ban ✅ ✅
Mute / TempMute / Unmute ✅ ✅
Warn / Warns / Clear ✅ ✅
History / StaffHistory ✅ ✅
Staff Rollback ✅ ✅
IP-Ban Exemption (/staffallow) ✅ ✅
Punishment Migration (/staffimport) ✅ ✅
Discord Webhook Logging ✅ ✅
Warning Escalation Ladder ✅ ✅
Hierarchy Protection ✅ ✅
Alt-Detection (IP Matching) ✅ ✅
SQLite / MySQL Storage ✅ ✅
Vanish System ✅ ❌
Spectator Monitor/Follow ✅ ❌
Inventory Inspector (/invsee) ✅ ❌
Gamemode Shortcuts ✅ ❌
Flight Toggle (/fly) ✅ ❌
Global Ban History (/bans) ✅ ✅
Ban Leaderboard (/bansleaderboard) ✅ ✅
Kick (/kick) ✅ ✅
Unwarn (/unwarn) ✅ ✅
Checkban (/checkban) ✅ ✅
Live Reload (/staff reload) ✅ ✅
Bedrock Geyser Forms ✅ N/A
Modrinth Update Notifier ✅ ✅
bStats Metrics ✅ ✅
Folia Scheduler Safety ✅ N/A
Proxy-Level Ban Enforcement ❌ ✅
Limbo Kick Prevention ❌ ✅
Transparent Backend Command Forwarding ❌ ✅

功能

跨平台核心

  • 共享数据库: Paper 和 Velocity 版本均读取和写入同一个处罚数据库(SQLite 或 MySQL),从而实现无缝的全网络管理。
  • 共享配置: config.yml 和 messages.yml 通过 Okaeri 配置框架在两个平台上使用相同的格式。
  • 统一迁移引擎: 可从任一平台导入来自 7 种以上插件的处罚记录。

Folia 安全(Paper 版)

  • 异步生命周期: 所有命令、数据库事务和数据包操作均在符合 Folia 的区域调度器或异步调度器上运行。
  • Folia 传送安全: 标准传送被替换为安全、非阻塞的 teleportAsync 未来任务,完全防止线程崩溃。
  • 隔离的数据包循环: 视觉切换功能(如隐身隐藏/显示数据包)安排在每个接收者特定的区域线程上,确保线程安全。

代理网关执行(Velocity 版)

  • 登录前封禁检查: 在代理级别拦截登录尝试,并在被封禁的玩家到达任何后端服务器之前就拒绝其连接。
  • 全网络静音过滤器: 阻止所有已连接服务器上的静音玩家的聊天消息。
  • IP 封禁网关: 在代理网关处执行 IP 封禁,防止被封禁的 IP 连接到网络中的任何服务器。

隐身(仅限 Paper)

  • 完全隐形: 将玩家从在线计数、玩家延迟列表、Tab 补全和可见列表中完全移除。
  • 物理交互绕过: 隐身的管理员完全绕过物理压力板和绊线触发器。
  • 无声容器: 允许无声打开箱子、熔炉和桶界面,而不会触发容器动画或音频。
  • 潜行抑制: 在激活时防止怪物锁定目标、拾取物品,并完全抑制加入/离开消息。
  • 视觉动作栏指示器: 通过安全的异步重复任务实时显示隐身状态 HUD。

管理(两个平台通用)

  • 综合操作:集成了 /ban、/tempban、/ip-ban、/tempip-ban、/mute、/tempmute 和 /warn。
  • 警告档案:通过 /warns <player> [list/clear] 追踪个人警告日志。
  • 动态时间解析:支持复杂单位(如 1d、12h、45m)和无限持续时间映射(perm)的高级时间解析器。
  • 关系型存储:由高性能数据库管理器提供支持,支持本地 SQLite 数据库和远程 MySQL 服务器,并通过轻量级、线程安全的 HikariCP 连接池进行管理。
  • 关联账号副号检测:玩家登录时,自动扫描、记录并广播共享 IP 地址的替代账号,并对活跃(绿色)和封禁(红色)档案进行着色标记。
  • 动态命令与历史记录一致性:多线程支持的 /history <player>、/staffhistory <staff> 和 /staffrollback <staff> 命令,辅以基于动态数据库的名称标签补全功能。
  • 警告升级阶梯:根据当前警告等级动态调整处罚(例如临时静音升级为永久封禁)。命令分发在各平台的原生调度程序上安全执行。
  • 非阻塞 Discord Webhook 日志:使用现代非阻塞 Java 21 HttpClient 接口实时嵌入记录所有静音、封禁和警告分发操作,对区域刻数无任何影响。
  • 管理员覆盖层级保护:自定义员工权重等级 (staff.hierarchy.weight.<number>) 阻止低级员工覆盖、停用或移除高级管理员或控制台(Integer.MAX_VALUE)施加的处罚。
  • IP 封禁豁免绕过:将特定账号列入白名单(/staffallow),使其能够连接并绕过活跃的 IP 封禁,而无需为其他共享该 IP 的账号解除 IP 封禁。

处罚导入器与迁移(双平台支持)

  • 7 种支持的平台:无缝导入静音、封禁、警告和 IP 封禁,来源包括:
    • Vanilla Minecraft:直接从服务器根目录下的 banned-players.json 和 banned-ips.json 导入。
    • Essentials / EssentialsX:自动扫描 plugins/Essentials/userdata/*.yml 下用户配置文件中的静音和封禁记录。
    • LiteBans:从 H2/SQLite/MySQL 数据库迁移封禁、静音和警告。支持自动检测 litebans.mv.db H2 文件或手动配置 JDBC 参数。
    • AdvancedBan:集成并规范化来自 SQLite 或 MySQL 的传统 SQL Punishments 表。
    • MaxBans:从 SQLite 或 MySQL 迁移封禁、IP 封禁、静音和警告。
    • BanManager:集成具有可配置表前缀的历史玩家封禁、静音和警告。
    • BungeeAdminTools (BAT):从数据库表 bat_ban 和 bat_mute 导入条目。
  • 动态自动扫描:在命令触发时扫描服务器上的活动文件,提取 SQLite 路径或远程 SQL 数据库凭据,实现零配置迁移。
  • 批量操作:使用批量插入在单个事务中提交导入的记录,瞬间迁移数千条记录。
  • 非阻塞 Future:在 non-blocking 线程池上完全异步运行连接设置、配置解码和数据库提交。

观察者跟随(仅限 Paper)

  • 电影式摄像机追踪:将处于观察者模式的员工传送至目标身后以实现无缝跟随。
  • 速度预测跟随:计算目标移动和速度向量 (target.getVelocity()),将摄像机定位在目标前方稍许位置,消除卡顿和橡皮筋效应。
  • 节流传送:自动更新以节流的 4 刻(200ms)间隔运行,并带有 400ms 冷却时间,给予客户端预测运动和 Paper 的异步传送 Future 足够时间完全解析。
  • 可配置边界束缚:允许员工在 10 格半径内环绕或自由移动。超出边界时,摄像机会柔和地被拉回偏移位置。

物品栏检查器(仅限 Paper)

  • 54 槽位实时 GUI:查看并编辑目标玩家的主物品栏(0-35)、护甲槽(头盔、胸甲、护腿、靴子)、副手物品以及状态统计。
  • 实时统计与快捷方式:
    • 金苹果:动态显示生命值、饥饿值和经验值。
    • 药水瓶:显示活跃药水效果及其持续时间的实时列表。
    • 末影箱:快速访问快捷物品,直接检查其末影箱。
  • 无与伦比的 Folia 安全性:完全避免异步方块状态读取(在其他区域的基于方块的物品栏上查询 .getOpenInventory().getTopInventory().getHolder() 时会导致 Folia 崩溃)。相反,它实现了线程安全的自定义会话注册表,干净地跟踪活跃的检查视图并在区域内传播更新。

快捷指令(仅限 Paper)

  • 即时游戏模式切换:快速执行包括创造模式 (/gmc)、生存模式 (/gms)、观察者模式 (/gmsp) 和冒险模式 (/gma) 的命令。
  • 飞行模式:通过 /fly 无缝切换飞行模式。

命令与权限

网络级命令(Paper & Velocity)

命令 描述 用法 权限节点
/ban 将玩家封禁出服务器。 /ban <player> [reason] staff.ban
/tempban 暂时封禁一名玩家。 /tempban <player> <duration> [reason] staff.tempban
/unban 解除玩家的封禁。 /unban <player> staff.unban
/ip-ban 封禁玩家的 IP 地址。 /ip-ban <player> [reason] staff.ipban
/tempip-ban 暂时封禁玩家的 IP 地址。 /tempip-ban <player> <duration> [reason] staff.tempipban
/unip-ban 解除 IP 地址或玩家的封禁。 /unip-ban <player/IP> staff.unipban
/mute 在聊天中静音一名玩家。 /mute <player> [reason] staff.mute
/tempmute 暂时静音一名玩家。 /tempmute <player> <duration> [reason] staff.tempmute
/unmute 解除玩家的静音。 /unmute <player> staff.unmute
/warn 警告一名玩家。 /warn <player> [reason] staff.warn
/warns 查看或清除警告记录。 /warns <player> [list/clear] staff.warns
/history 查看玩家的完整处罚日志(活跃/非活跃)。 /history <player> staff.history
/staffhistory 查看某名工作人员发出的所有处罚。 /staffhistory <staff> staff.staffhistory
/staffrollback 回滚某名工作人员放置的所有活跃处罚。 /staffrollback <staff> [confirm] staff.staffrollback
/staffallow 豁免某玩家/UUID 免受活跃 IP 封禁。 /staffallow <player> [remove] staff.staffallow
/staffimport 从其他插件导入处罚记录。 /staffimport <source> [params...] staff.import
/bans 查看最近的服务器封禁记录(GUI / Geyser 表单 / 聊天)。 /bans [page] [--chat] staff.bans
/bansleaderboard 按发出的封禁数量查看工作人员排行榜。 /bansleaderboard [--chat] staff.bansleaderboard
/kick 踢出在线玩家,并验证权限层级。 /kick <player> [reason] staff.kick
/unwarn 移除玩家最新或特定的警告。 /unwarn <player> [id] staff.unwarn
/checkban 审计玩家或 IP 的活跃封禁/IP 封禁状态。 /checkban <player/IP> staff.checkban
/staff reload 无需重启即可实时重新加载配置文件。 /staff reload staff.staff.reload

Paper-Only Commands

命令 描述 用法 权限节点
/vanish 切换完全隐身状态。 /vanish staff.vanish
/invsee 实时检查玩家的物品栏。 /invsee <player> staff.invsee
/monitor 旁观并平滑跟随一名玩家。 /monitor <player/leave> staff.monitor
/fly 切换玩家飞行模式。 /fly [player] staff.fly
/gmc 切换到创造模式。 /gmc [player] staff.gmc
/gms 切换到生存模式。 /gms [player] staff.gms
/gmsp 切换到旁观者模式。 /gmsp [player] staff.gmsp
/gma 切换到冒险模式。 /gma [player] staff.gma

管理员通配符:权限节点 staff.admin 默认授予该插件的所有功能访问权限。 绕过节点:拥有 staff.vanish.see 权限的玩家可以在游戏内、标签列表和命令中看到隐身的玩家。


Installation

Paper Edition (Paper / Purpur / Folia)

  1. 从 Modrinth 或 GitHub Releases 下载 StaffPlus-Paper-1.2.3.jar。
  2. 将 JAR 文件放入服务器的 plugins/ 文件夹中。
  3. 重启服务器。
  4. 根据需要编辑 plugins/Staff/config.yml 和 plugins/Staff/messages.yml。

Velocity Edition (Proxy)

  1. 从 Modrinth 或 GitHub Releases 下载 StaffPlus-Velocity-1.2.3.jar。
  2. 将 JAR 文件放入 Velocity 代理的 plugins/ 文件夹中。
  3. 重启代理。
  4. 根据需要编辑 plugins/staffplus/config.yml 和 plugins/staffplus/messages.yml。
  5. Permissions & Backend Forwarding:
    • 如果你在 Velocity 上使用 LuckPerms,请授予工作人员 staff.admin 权限(/lpv user <name> permission set staff.admin true)。
    • 如果你仅在后端 Paper 服务器上管理权限和 OP 状态,Staff+ 会自动将在 Velocity 上执行的命令转发到玩家连接的 Paper 服务器(velocity-forward-to-backend: true),从而让 Paper 无缝评估 LuckPerms 和 OP 状态!

Shared Database (Network Mode)

要在整个网络中共享处罚记录,请配置 两个版本 使用相同的 MySQL 或 MariaDB 数据库:

# config.yml (Paper 和 Velocity 上相同)
storage-type: "mysql" # 或 "mariadb"
mysql-host: "your-db-host"
mysql-port: 3306
mysql-database: "staffplus"
mysql-username: "your-user"
mysql-password: "your-password"

Configuration

该插件使用 Okaeri Config 来生成、验证和自动更新整洁的 YAML 配置结构。两个平台共享相同的配置格式。

config.yml

# 存储类型:SQLITE, MYSQL, 或 MARIADB
storage-type: "sqlite"

# MySQL / MariaDB 连接详情(仅当 storage-type 为 MYSQL 或 MARIADB 时使用)
mysql-host: "localhost"
mysql-port: 3306
mysql-database: "minecraft"
mysql-username: "root"
mysql-password: "password"
mysql-pool-size: 10
mysql-use-ssl: false

# Vanish 设置(仅限 Paper — 在 Velocity 上被忽略)
vanish-silent-container-clicks: true
vanish-ignore-pressure-plates: true
vanish-disable-mob-targeting: true
vanish-disable-item-pickup: true

# 警告升级阶梯设置
warning-ladder-enabled: true

# 当玩家达到特定数量的活跃警告时执行的操作
warning-ladder-actions:
  1: "tempmute {player} 1h [Warning Ladder] First warning"
  2: "tempmute {player} 12h [Warning Ladder] Second warning"
  3: "tempban {player} 3d [Warning Ladder] Reached 3 warnings"
  4: "ban {player} [Warning Ladder] Reached 4 warnings"

# Discord Webhook 日志记录设置
discord-webhook-enabled: false
discord-webhook-url: ""
discord-webhook-username: "Staff+ Moderation"
discord-webhook-avatar-url: "https://i.imgur.com/8Qp49X0.png"

# Webhook 嵌入的十六进制颜色代码(不含 #)
discord-webhook-color-ban: "FF5555"
discord-webhook-color-mute: "FFAA00"
discord-webhook-color-warn: "FFFF55"

# 更新检查器设置 (Modrinth)
update-checker-enabled: true
update-checker-notify-admins: true

# 员工封禁排行榜设置
bans-leaderboard-enabled: true

# Velocity 代理设置 (仅限 Velocity)
velocity-proxy-commands: true
velocity-forward-to-backend: true
velocity-disconnect-on-kick: true

messages.yml

完全支持 Adventure MiniMessage,启用华丽的原生文本样式、十六进制颜色和渐变(例如 <gradient:#FF5F6D:#FFC371>Text</gradient>)。

# 所有插件消息的前缀
prefix: "<color:#A0A0A0>[<color:#00E262>Staff+<color:#A0A0A0>] "

no-permission: "<color:#E20000>You do not have permission to execute this command."
player-only: "<color:#E20000>This command can only be executed by a player."
cannot-overwrite-punishment: "<color:#E20000>You cannot override a punishment placed by a higher-ranking staff member ({staff})."
player-allowed: "<color:#00E262>You have allowed {player} to bypass IP bans."
player-allowed-broadcast: "<color:#00E262>{player} has been exempted from IP bans by {sender}."
player-unallowed: "<color:#00E262>You have removed IP ban exemption for {player}."
player-unallowed-broadcast: "<color:#00E262>{player} is no longer exempted from IP bans."
player-not-found: "<color:#E20000>Player '{player}' has not been found or registered."
invalid-duration: "<color:#E20000>Invalid duration format! Use e.g. 1d, 12h, 30m or perm."

# 静音
player-muted: "<color:#00E262>You have muted {player} for {time}. Reason: {reason}"
player-muted-broadcast: "<color:#E2B700>{player} has been muted by {sender} for {time}. Reason: {reason}"
you-are-muted: "<color:#E20000>You are muted! Remaining time: {time}. Reason: {reason}"

# 封禁
player-banned: "<color:#00E262>You have banned {player} for {time}. Reason: {reason}"
player-banned-broadcast: "<color:#E20000>{player} has been banned by {sender} for {time}. Reason: {reason}"
ban-kick-message: "<color:#E20000>You have been banned from the server!\n\nReason: {reason}\nExpiry: {time}"

# 隐身 (仅限 Paper)
vanish-enabled: "<color:#00E262>You are now vanished."
vanish-disabled: "<color:#00E262>You are no longer vanished."
vanish-action-bar: "<color:#00E262>★ YOU ARE VANISHED ★"

构建与编译

Staff+ 是一个多模块 Gradle 项目,生成两个独立的阴影 JAR 文件。

要求

  • Java 21 或更高版本
  • Gradle (已安装或通过包装器使用)

构建命令

编译并构建两个平台 JAR 文件:

./gradlew clean build

编译后的插件将位于以下位置:

staff-paper/build/libs/StaffPlus-Paper-1.0.0.jar    # Paper/Purpur/Folia 服务器
staff-velocity/build/libs/StaffPlus-Velocity-1.0.0.jar  # Velocity 代理

项目结构

StaffPlus/
├── staff-core/          # 共享的平台无关库
│   └── src/main/java/   # 数据库、惩罚模型、配置、迁移、工具
├── staff-paper/         # Paper/Folia 后端插件
│   └── src/main/java/   # Paper 命令、监听器、隐身、监控、物品查看
├── staff-velocity/       # Velocity 代理插件
│   └── src/main/java/   # Velocity 命令、登录/聊天监听器
├── build.gradle          # 根配置
└── settings.gradle       # 多模块声明

注意:Gradle shadow 配置会自动将 eu.okaeri、com.zaxxer.hikari、org.h2 和 org.xerial 库重定位到私有命名空间 (me.ayosynk.staff.libs.*),以防止与类路径上的任何其他插件发生冲突。


持续集成

Staff+ 通过 GitHub Actions 实现了完全自动化的 CI/CD 管道,用于编译、验证和分发两个平台的工件。

开发版本

  • 频率: 每当向 master 或 main 分支推送代码时自动构建。
  • 发布目标: 发布在 GitHub 上滚动更新的 dev-latest 预发布标签下。
  • 滚动策略: 管道会在每次构建时自动覆盖之前的 dev-latest 标签,保持发布页面整洁。
  • 工件: 每个发布中都包含 StaffPlus-Paper 和 StaffPlus-Velocity JAR 文件。

稳定版本

  • 频率: 每当向仓库推送匹配 v* 语义化 Git 版本标签(例如 v1.0.0)时生成。
  • 发布目标: 作为专用的生产版本发布,包含正式的发行说明和两个平台就绪的阴影 JAR 资产。

bStats 指标

Staff+ 的两个版本都集成了 bStats 以收集匿名使用统计信息。这有助于我们了解插件的使用情况并指导未来的开发。

  • Paper 版本: 使用 bstats-bukkit 进行服务器端指标收集。
  • Velocity 版本: 使用 bstats-velocity (插件 ID: 31693) 进行代理端指标收集。

如果您希望退出匿名指标收集,可以通过导航到服务器或代理上的 plugins/bStats/config.yml 文件并将 enabled 设置为 false 来禁用它。


开发者备注

对于查看 Staff+ 源代码的开发者,以下是架构摘要:

多模块架构

  1. staff-core:跨平台共享库,包含数据库层、惩罚模型、配置系统、迁移引擎和工具类。使用 ForkJoinPool.commonPool() 处理异步操作——不依赖任何特定平台的调度器。
  2. staff-paper:实现 StaffPlatform 接口的 Paper/Folia 插件。包含所有 Paper 特有的命令、监听器、隐身(vanish)、监控(monitor)、查看物品栏(invsee)和游戏模式快捷方式。使用符合 Folia 安全标准的区域调度器。
  3. staff-velocity:实现 StaffPlatform 接口的 Velocity 代理插件。包含代理级别的命令以及用于全网络强制执行的登录/聊天事件监听器。

Folia 线程规则 (Paper)

  1. 异步传送:切勿在 Folia 上调用 Player#teleport()。始终使用 Player#teleportAsync(),并使用 .thenRun() 或 .thenAccept() 队列化依赖操作。
  2. 接收者线程安全:动作更新(如 recipient.hidePlayer() 或 recipient.showPlayer())必须在接收者的区域线程上下文中执行。将这些调用包装在 SchedulerUtils.runEntity(plugin, recipient, ...) 中以确保数据包发送。
  3. 避免跨区块状态读取:在其他区域打开的基于区块的物品栏上调用 open.getHolder() 会引发线程异常。相反,应维护一个内存中的、线程安全的 InvseeSession 对象注册表。
  4. 电影式跟随阻尼:使用间隔检查(≥4 tick)、速度外推和任务冷却来保持平滑的跟随视角。

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源