ZAdmin
适用于 Paper 1.21.x 服务器的现代化、模块化、高性能游戏内管理平台。
ZAdmin 是一个独立的管理面板,可在任何 Paper 服务器上开箱即用,无需依赖任何私有或第三方插件。每个主要功能都是独立的模块,可以在运行时启用、禁用和重载;清晰的公共 API 允许其他开发者扩展面板,且 ZAdmin 永远不会依赖他们的插件。
功能
| 区域 |
获得的功能 |
| 仪表盘 |
一个可配置的库存 GUI 枢纽(/admin),支持 MiniMessage 文本、可配置的图标/槽位、音效、装饰边框和分页。 |
| 玩家管理 |
在线玩家列表 → 玩家检查器,显示用户名、UUID、延迟、生命值、饥饿值、饱和度、经验值、游戏模式、世界、坐标、旋转角度、余额(Vault)、前缀/后缀 & 组(LuckPerms),以及可选的 IP 地址。 |
| 玩家操作 |
传送、治疗、喂食、清空物品栏、查看物品栏 / 末影箱、冻结、上帝模式、隐身、踢出、封禁、警告、静音、发送消息、员工备注、账号检测、物品快照、复制 UUID。 |
| 物品快照 |
破坏性操作(例如清空物品栏)会先捕获一个可恢复的快照。浏览玩家的快照历史,点击右键即可一键回滚。 |
| 账号检测 |
可选择标记共享最后已知 IP 的账号。默认关闭(存储/比较 IP —— 这是一个涉及隐私的功能)。 |
| 聊天过滤 |
可选的反垃圾邮件(速率限制 + 重复抑制)和正则表达式单词/链接黑名单,违规升级可配置。拥有 zadmin.chat.bypass 权限者可绕过。 |
| 处罚升级 |
可配置的阶梯式处罚(例如:警告 → 静音:1小时 → 封禁:7天 → 永久封禁),根据违规次数应用,并附带一键原因预设。 |
| 跨服务器同步 |
通过共享的 MySQL/MariaDB 数据存储,在网络中传播封禁/静音和员工广播。默认关闭;对 SQLite 无影响。 |
| 指标统计 |
通过 bStats 收集匿名聚合使用统计数据。尊重 ZAdmin 的 metrics.enabled 设置以及全局 bStats 退出选项。 |
| 冻结系统 |
被冻结的玩家无法移动、破坏/放置方块、攻击、交互、掉落物品或(可选地)执行命令。如果冻结的玩家断开连接,员工将收到警报。 |
| 员工备注 |
支持无限数量的玩家备注,包含分类/标题/内容,支持分页、添加和删除,基于数据库存储。 |
| 举报 |
待处理 / 已认领 / 已关闭队列,支持认领、关闭、传送至目标玩家和历史记录查看。 |
| 处罚记录 |
警告、踢出、静音、临时静音、封禁、临时封禁、黑名单 —— 包含历史记录、持续时间、永久存储以及在 GUI 中撤销的功能。 |
| 经济监控 |
跟踪存款/取款,标记可疑(大额)交易,提供筛选和历史记录。在没有 Vault 的情况下优雅禁用。 |
| 日志记录 |
异步、批处理的审计日志,涵盖命令、加入/离开、处罚、经济、传送、员工操作、死亡等更多数据 —— 支持类别筛选、分页和导出。 |
| 调度器 |
用于广播、命令、保存、备份和重启的 GUI 编辑器,支持按间隔或每日/每周/每月计划执行。 |
| 开发者工具 |
插件列表及版本、世界/区块检查器、性能监控器(TPS/MSPT/RAM/线程)、占位符测试器、PDC/元数据/权限检查器。不涉及 NMS。 |
| 服务器仪表盘 |
实时 TPS、MSPT、RAM、CPU 负载、世界、区块、实体、方块实体、玩家、插件 —— 自动刷新。 |
| 模块管理 |
在运行时启用/禁用/重载所有功能;状态持久化到配置文件。 |
| 通知 |
游戏内弹窗(TPS 下降、新举报、冻结玩家离线、备份完成、处罚),支持可配置的音效,并提供外部提供商的 API。 |
| 挂钩集成 |
自动检测 Vault、PlaceholderAPI、LuckPerms 和 Geyser/Floodgate;缺失的插件只会禁用其相关功能,不会产生错误。 |
要求
- Java 21+
- Paper 1.21.x(仅使用 Bukkit Inventory API —— 无外部 GUI 框架)
可选软依赖:Vault、PlaceholderAPI、LuckPerms、Geyser/Floodgate。
命令与权限
| 命令 |
别名 |
描述 |
/admin |
/zadmin, /adm |
打开仪表盘 |
/admin reload |
|
重载配置和模块 (zadmin.settings.edit) |
/admin module <enable|disable|list> [id] |
|
管理模块 (zadmin.modules.manage) |
/admin backup |
|
运行手动备份 (zadmin.settings.edit) |
/admin version |
|
显示版本 |
基础权限:zadmin.use。每个操作都有各自的权限节点(例如 zadmin.player.freeze、zadmin.reports.claim、zadmin.logs.export、zadmin.developer.view)。授予 zadmin.* 可获得完全访问权限。完整列表请参阅 plugin.yml。
配置
所有文件位于 plugins/ZAdmin/ 目录下,并通过 /admin reload 热重载:
config.yml — 行为开关、日志、经济、通知、冻结、备份、聊天过滤、升级策略、账号检测、跨服务器同步、指标统计、模块标志
messages.yml — 所有面向用户的字符串(MiniMessage 格式)
gui.yml — 仪表盘图标、槽位、名称和描述
database.yml — SQLite(默认)或 MySQL/MariaDB 连接配置
数据库
SQLite 是默认选项,无需额外设置。对于 MySQL/MariaDB,请在 database.yml 中设置 type: mysql 并填写连接详情。所有数据库访问均为异步进行,并通过 HikariCP 进行连接池管理;服务器线程绝不会因 I/O 操作而被阻塞。
公共 API
ZAdmin 提供了一个稳定的、通用的 API —— 它不包含对任何特定插件的引用。
在你的 plugin.yml 中将 ZAdmin 添加为 softdepend,然后:
import com.zadmin.api.*;
import com.zadmin.gui.Button;
import com.zadmin.util.ItemBuilder;
import org.bukkit.Material;
ZAdminProvider api = ZAdminAPI.get();
```java
// 1. 向仪表盘添加一个按钮
api.registerDashboardButton(DashboardButton.of(31, "myplugin.use",
Button.of(ItemBuilder.of(Material.NETHER_STAR).name("<gold>My Feature").build(),
ctx -> ctx.player().performCommand("myplugin open"))));
// 2. 向玩家检查器添加一个标签页
api.registerPlayerInspectorTab(new PlayerInspectorTab() {
public String id() { return "myplugin_homes"; }
public String permission() { return "myplugin.homes"; }
public Button build(Player viewer, UUID target) {
return Button.of(ItemBuilder.of(Material.RED_BED).name("<aqua>Homes").build(),
ctx -> { /* 为目标打开你的家园 GUI */ });
}
});
// 3. 注册一个命名操作
api.registerAction(new AdminAction() {
public String id() { return "myplugin:reset"; }
public String permission() { return "myplugin.reset"; }
public void execute(Player staff, UUID target) { /* ... */ }
});
// 4. 注册模块(由 ZAdmin 启用/禁用/重新加载)
api.registerModule(myModule);
// 5. 接收通知(转发到 Discord、Web 面板等)
api.registerNotificationProvider(n ->
getLogger().info("[" + n.severity() + "] " + n.type() + ": " + n.title()));
建议从您自己的 onEnable(或更晚阶段)访问 API,以确保其可用性。使用
ZAdminAPI.isAvailable() / ZAdminAPI.getOrNull() 进行空安全访问。该 API 也通过 Bukkit 的
ServicesManager 注册为 com.zadmin.api.ZAdminProvider。
PlaceholderAPI
当安装 PlaceholderAPI 时,ZAdmin 会注册 zadmin 扩展:
%zadmin_tps%、%zadmin_mspt%、%zadmin_memory_used%、%zadmin_memory_max%、
%zadmin_frozen%、%zadmin_vanished%、%zadmin_god%、%zadmin_muted%。
架构
com.zadmin
├── api 公共扩展点(通用、插件无关)
├── command /admin 命令及 Tab 补全
├── config YAML 加载、消息服务
├── database 数据库抽象(SQLite / MySQL via HikariCP)、模式
├── gui 菜单框架(仅 Bukkit Inventory API)+ 内置菜单
├── hook 软集成(Vault、PlaceholderAPI、LuckPerms、Floodgate)
├── listener 全局事件监听器(连接、冻结、状态、经济)
├── model 不可变领域记录 + 枚举
├── module 模块框架 + 内置模块
├── placeholder PlaceholderAPI 扩展
├── scheduler 异步任务执行器(主线程封送)
├── service 业务逻辑(异步、缓存、线程安全)
├── storage DAOs(纯 JDBC、异步安全)
└── util 文本/MiniMessage、ItemBuilder、TimeUtil、冷却时间
设计原则: SOLID、显式组合根(ZAdminPlugin 中的依赖注入)、
无重复逻辑、线程安全的服务、完全异步的数据库与日志、智能
缓存,以及在禁用时彻底清理资源。旨在舒适地支持 300+ 并发玩家。
隐私
有两个功能因处理玩家 IP 地址而默认禁用:
- 小号检测 (
alt-detection.enabled) 存储并比较玩家的最后已知 IP。
- 跨服务器同步 (
sync.enabled) 在共用数据库上共享惩罚数据。
如果您启用了它们,您需要负责向玩家披露此做法,并遵守适用的数据保护法(例如 GDPR)。除非单独启用了 player.show-ip,否则 ZAdmin 不会通过小号检测 UI 显示原始 IP(仅显示结果账号名)。
匿名使用指标默认发送至 bStats。若要退出,请在 config.yml 中设置
metrics.enabled: false,或在 plugins/bStats/config.yml 中全局禁用 bStats。
许可证
公开发布供使用。欢迎署名。
ZAdmin
A modern, modular, high-performance in-game administration platform for Paper 1.21.x servers.
ZAdmin is a standalone administration panel that works out of the box on any Paper server with
no dependency on private or third-party plugins. Every major feature is an independent module
that can be enabled, disabled and reloaded at runtime, and a clean public API lets other developers
extend the panel without ZAdmin ever depending on their plugins.
Features
| Area |
What you get |
| Dashboard |
A configurable inventory GUI hub (/admin) with MiniMessage text, configurable icons/slots, sounds, decorative panes and pagination. |
| Player Manager |
Online player list → Player Inspector showing username, UUID, ping, health, hunger, saturation, XP, gamemode, world, coordinates, rotation, balance (Vault), prefix/suffix & group (LuckPerms), and optional IP. |
| Player Actions |
Teleport, heal, feed, clear inventory, view inventory / ender chest, freeze, god mode, vanish, kick, ban, warn, mute, message, staff notes, alt detection, inventory snapshots, copy UUID. |
| Inventory Snapshots |
Destructive actions (e.g. clear inventory) capture a restorable snapshot first. Browse a player's snapshot history and shift-click to roll back with one click. |
| Alt Detection |
Optionally flags accounts sharing a last-known IP. Off by default (stores/compares IPs — a privacy-sensitive feature). |
| Chat Filter |
Optional anti-spam (rate limit + duplicate suppression) and regex word/link blocklist, with configurable violation escalation. Bypassed by zadmin.chat.bypass. |
| Punishment Escalation |
Configurable ladder (e.g. WARN → MUTE:1h → BAN:7d → BAN:perm) applied by offence count, plus one-click reason presets. |
| Cross-Server Sync |
Over a shared MySQL/MariaDB datastore, propagates bans/mutes and staff broadcasts across a network. Off by default; no effect on SQLite. |
| Metrics |
Anonymous, aggregate usage stats via bStats. Honors both ZAdmin's metrics.enabled and the global bStats opt-out. |
| Freeze System |
Frozen players cannot move, break/place blocks, attack, interact, drop items or (optionally) run commands. Staff are alerted if a frozen player disconnects. |
| Staff Notes |
Unlimited per-player notes with category/title/content, pagination, add & delete, database-backed. |
| Reports |
Pending / Claimed / Closed queues with claim, close, teleport-to-target and history. |
| Punishments |
Warn, kick, mute, tempmute, ban, tempban, blacklist — with history, durations, permanent storage and in-GUI revocation. |
| Economy Monitor |
Tracks deposits/withdrawals, flags suspicious (large) transactions, filters & history. Gracefully disabled without Vault. |
| Logging |
Async, batched audit log across commands, joins/quits, punishments, economy, teleports, staff actions, deaths and more — with category filters, pagination and export. |
| Scheduler |
GUI editor for broadcasts, commands, saves, backups and restarts on interval or daily/weekly/monthly schedules. |
| Developer Tools |
Plugin list & versions, world/chunk inspector, performance monitors (TPS/MSPT/RAM/threads), placeholder tester, PDC/metadata/permission inspector. No NMS. |
| Server Dashboard |
Live TPS, MSPT, RAM, CPU load, worlds, chunks, entities, tile entities, players, plugins — auto-refreshing. |
| Modules |
Enable/disable/reload every feature at runtime; state persists to config. |
| Notifications |
In-game popups (TPS drops, new reports, frozen leavers, backups completed, punishments) with configurable sounds, plus an API for external providers. |
| Hooks |
Auto-detects Vault, PlaceholderAPI, LuckPerms and Geyser/Floodgate; missing plugins simply disable their related functionality with no errors. |
Requirements
- Java 21+
- Paper 1.21.x (Bukkit Inventory API only — no external GUI framework)
Optional soft-dependencies: Vault, PlaceholderAPI, LuckPerms, Geyser/Floodgate.
Commands & Permissions
| Command |
Aliases |
Description |
/admin |
/zadmin, /adm |
Open the dashboard |
/admin reload |
|
Reload config & modules (zadmin.settings.edit) |
/admin module <enable|disable|list> [id] |
|
Manage modules (zadmin.modules.manage) |
/admin backup |
|
Run a manual backup (zadmin.settings.edit) |
/admin version |
|
Show version |
Base permission: zadmin.use. Every action has its own node (e.g. zadmin.player.freeze,
zadmin.reports.claim, zadmin.logs.export, zadmin.developer.view). Grant zadmin.* for full
access. See plugin.yml for the complete list.
Configuration
All files live in plugins/ZAdmin/ and hot-reload with /admin reload:
config.yml — behaviour toggles, logging, economy, notifications, freeze, backups, chat filter, escalation, alt detection, cross-server sync, metrics, module flags
messages.yml — every user-facing string (MiniMessage)
gui.yml — dashboard icons, slots, names and lore
database.yml — SQLite (default) or MySQL/MariaDB connection
Database
SQLite is the default and requires no setup. For MySQL/MariaDB, set type: mysql in database.yml
and fill in the connection details. All database access is asynchronous and connection-pooled via
HikariCP; the server thread is never blocked on I/O.
Public API
ZAdmin exposes a stable, generic API — it contains no references to any specific plugin.
Add ZAdmin as a softdepend in your plugin.yml, then:
import com.zadmin.api.*;
import com.zadmin.gui.Button;
import com.zadmin.util.ItemBuilder;
import org.bukkit.Material;
ZAdminProvider api = ZAdminAPI.get();
// 1. Add a button to the dashboard
api.registerDashboardButton(DashboardButton.of(31, "myplugin.use",
Button.of(ItemBuilder.of(Material.NETHER_STAR).name("<gold>My Feature").build(),
ctx -> ctx.player().performCommand("myplugin open"))));
// 2. Add a tab to the Player Inspector
api.registerPlayerInspectorTab(new PlayerInspectorTab() {
public String id() { return "myplugin_homes"; }
public String permission() { return "myplugin.homes"; }
public Button build(Player viewer, UUID target) {
return Button.of(ItemBuilder.of(Material.RED_BED).name("<aqua>Homes").build(),
ctx -> { /* open your homes GUI for target */ });
}
});
// 3. Register a named action
api.registerAction(new AdminAction() {
public String id() { return "myplugin:reset"; }
public String permission() { return "myplugin.reset"; }
public void execute(Player staff, UUID target) { /* ... */ }
});
// 4. Register a module (enabled/disabled/reloaded by ZAdmin)
api.registerModule(myModule);
// 5. Receive notifications (forward to Discord, a web panel, etc.)
api.registerNotificationProvider(n ->
getLogger().info("[" + n.severity() + "] " + n.type() + ": " + n.title()));
Prefer accessing the API from your own onEnable (or later) to guarantee availability. Use
ZAdminAPI.isAvailable() / ZAdminAPI.getOrNull() for null-safe access. The API is also registered
with Bukkit's ServicesManager as com.zadmin.api.ZAdminProvider.
PlaceholderAPI
When PlaceholderAPI is installed, ZAdmin registers the zadmin expansion:
%zadmin_tps%, %zadmin_mspt%, %zadmin_memory_used%, %zadmin_memory_max%,
%zadmin_frozen%, %zadmin_vanished%, %zadmin_god%, %zadmin_muted%.
Architecture
com.zadmin
├── api Public extension points (generic, plugin-agnostic)
├── command /admin command + tab completion
├── config YAML loading, message service
├── database Database abstraction (SQLite / MySQL via HikariCP), schema
├── gui Menu framework (Bukkit Inventory API only) + built-in menus
├── hook Soft integrations (Vault, PlaceholderAPI, LuckPerms, Floodgate)
├── listener Global event listeners (connection, freeze, state, economy)
├── model Immutable domain records + enums
├── module Module framework + built-in modules
├── placeholder PlaceholderAPI expansion
├── scheduler Async task executor (main-thread marshalling)
├── service Business logic (async, cached, thread-safe)
├── storage DAOs (pure JDBC, async-safe)
└── util Text/MiniMessage, ItemBuilder, TimeUtil, cooldowns
Design principles: SOLID, explicit composition root (dependency injection in ZAdminPlugin),
no duplicated logic, thread-safe services, fully asynchronous database & logging, intelligent
caching, and clean resource cleanup on disable. Built to comfortably serve 300+ concurrent players.
Privacy
Two features are disabled by default because they process player IP addresses:
- Alt detection (
alt-detection.enabled) stores and compares players' last-known IPs.
- Cross-server sync (
sync.enabled) shares punishment data across servers on a common database.
If you enable them, you are responsible for disclosing the practice to your players and for
complying with applicable data-protection law (e.g. GDPR). ZAdmin never shows raw IPs through the
alt-detection UI (only the resulting account names) unless player.show-ip is separately enabled.
Anonymous usage metrics are sent to bStats by default. To opt out, set
metrics.enabled: false in config.yml, or disable bStats globally in plugins/bStats/config.yml.
License
Released for public use. Attribution appreciated.
评论 0
登录后参与评分
还没有评论,来抢沙发吧