# WeGuardian - 高级 Minecraft 惩罚系统
[](https://openjdk.java.net/projects/jdk/21/)
[](https://papermc.io/)
[](https://papermc.io/software/folia)
[](LICENSE.txt)
[](https://bstats.org/plugin/bukkit/WeGuardian/27046)
[](https://discord.gg/aSWKs3k4XA)
[](https://github.com/WeThink25/WeGuardian)
WeGuardian 是一个全面的、专业的 Minecraft 惩罚系统插件，专为现代 Paper/Bukkit 和 Folia 服务器设计。它提供了一套完整的管理工具，具有基于 GUI 的界面、高级惩罚模板、跨服务器同步和 MySQL 支持。
## ✨ 关键特性
### 🎯 核心惩罚系统
- **基于 GUI 的界面**: `/punish <玩家>` 命令打开全面的惩罚中心
- **完整的惩罚类型**: Ban、Tempban、Mute、Tempmute、Kick、Warn、Unban、Unmute、Notes
- **基于 IP 的惩罚**: IP ban、IP mute，并自动关联玩家
- **智能模板**: 高级惩罚升级系统，具有自动递增
- **静默惩罚**: 使用 `-s` 标志执行惩罚，不广播
- **高级验证**: 防止重复惩罚和权限层级检查
### 🚀 高级特性
- **惩罚模板**: 具有可配置违规级别的自动化升级系统
- **高级命令**: `/banlist`、`/mutelist`、`/alts`、`/blame`、`/warns`、`/unwarn`
- **IP 关联**: 高级小号检测，通过共享 IP 分析
- **惩罚历史**: 带有可点击惩罚 ID 的完整审计跟踪
- **模板集成**: 基于玩家历史的智能惩罚进度
- **丰富的格式化**: 使用 Adventure API 和悬停工具提示和可点击元素
### 🗄️ 数据库 & 存储
- **YAML 存储**: 主要存储系统，具有单独的玩家文件
- **MySQL 支持**: 具有 HikariCP 连接池的全方位跨服务器 MySQL 支持
- **跨服务器同步**: 实时在多个服务器之间同步惩罚
- **异步操作**: 所有数据库操作都是异步的，以实现最佳性能
- **数据完整性**: 全面的备份系统和数据验证
### 🎨 高级 GUI 系统
- **全面的主菜单**: 所有在一体的惩罚界面，可直接执行
- **预配置操作**: 常见的惩罚场景和预定义的理由/时长
- **模板集成**: 从 GUI 访问智能惩罚模板
- **玩家信息**: 快速访问历史、禁言状态和备注
- **专业的布局**: 54 个槽位有组织的界面，带有颜色编码的严重程度级别
- **菜单验证**: 自动验证和自动修复菜单配置
### ⚡ 性能 & 兼容性
- **Folia 支持**: 完全支持 Folia，通过 FoliaLib 进行区域感知调度
- **FoliaLib 集成**: 现代调度器 API，用于跨平台兼容性
- **线程池优化**: 可配置的异步操作和性能调整
- **平台检测**: 自动优化 Paper/Spigot 与 Folia 服务器
- **性能监控**: 内置指标和缓存统计
- **bStats 指标**: 插件使用分析和性能监控
## 📋 命令概述
### 核心惩罚命令
| 命令 | 描述 | 权限 |
|---------|-------------|------------|
| `/punish <玩家>` | 打开惩罚 GUI | `weguardian.punish` |
| `/ban <玩家> <原因> [-s] [-t 模板]` | 永久封禁玩家 | `weguardian.ban` |
| `/tempban <玩家> <时间> <原因> [-s] [-t 模板]` | 临时封禁玩家 | `weguardian.tempban` |
| `/mute <玩家> <原因> [-s] [-t 模板] [--ip]` | 永久静音玩家 | `weguardian.mute` |
| `/tempmute <玩家> <时间> <原因> [-s] [-t 模板] [--ip]` | 临时静音玩家 | `weguardian.tempmute` |
| `/kick <玩家> <原因> [-s] [-t 模板] [--ip]` | 踢出玩家 | `weguardian.kick` |
| `/warn <玩家> <原因> [-s] [-t 模板]` | 警告玩家 | `weguardian.warn` |
| `/unban <玩家>` | 解除封禁玩家 | `weguardian.unban` |
| `/unmute <玩家>` | 解除静音玩家 | `weguardian.unmute` |
### 基于 IP 的惩罚命令
| 命令 | 描述 | 权限 |
|---------|-------------|------------|
| `/ipban ` | 封禁 IP 地址 | `weguardian.ipban` |
| `/ipmute ` | 静音 IP 地址 | `weguardian.ipmute` |
| `/unbanip ` | 解除封禁 IP 地址 | `weguardian.unbanip` |
| `/unmuteip ` | 解除静音 IP 地址 | `weguardian.unmuteip` |
### 高级命令
| 命令 | 描述 | 权限 |
|---------|-------------|------------|
| `/banlist [--ip] [--filter]` | 分页列出所有封禁 | `weguardian.banlist` |
| `/mutelist [--ip] [--filter]` | 分页列出所有静音 | `weguardian.mutelist` |
| `/alts <玩家> [--strict] [--punished]` | 查找小号 | `weguardian.alts` |
| `/blame ` | 显示惩罚详情 | `weguardian.blame` |
| `/warns <玩家>` | 显示玩家警告 | `weguardian.warns` |
| `/unwarn <原因>` | 移除特定警告 | `weguardian.unwarn` |
### 信息 & 历史命令
| 命令 | 描述 | 权限 |
|---------|-------------|------------|
| `/history <玩家>` | 查看惩罚历史 | `weguardian.history` |
| `/checkban <玩家>` | 检查封禁/静音状态 | `weguardian.checkban` |
| `/notes <玩家>` | 查看工作人员备注 | `weguardian.notes` |
| `/staffstatus <工作人员>` | 查看工作人员统计 | `weguardian.staffstatus` |
| `/stats` | 查看全局统计 | `weguardian.stats` |
### 管理员 & 管理命令
| 命令 | 描述 | 权限 |
|---------|-------------|------------|
| `/rollback [原因]` | 根据 ID 回滚惩罚 | `weguardian.rollback` |
| `/banwave ` | 管理封禁波队列 | `weguardian.banwave` |
| `/weguardian ` | 插件管理 | `weguardian.admin` |
### GUI 导航命令
| 命令 | 描述 | 权限 |
|---------|-------------|------------|
| `/banmenu <玩家>` | 直接打开禁言 GUI | `weguardian.gui.ban` |
| `/tempbanmenu <玩家>` | 直接打开临时禁言 GUI | `weguardian.gui.tempban` |
| `/mutemenu <玩家>` | 直接打开静音 GUI | `weguardian.gui.mute` |
| `/tempmutemenu <玩家>` | 直接打开临时静音 GUI | `weguardian.gui.tempmute` |
| `/warnmenu <玩家>` | 直接打开警告 GUI | `weguardian.gui.warn` |
| `/kickmenu <玩家>` | 直接打开踢出 GUI | `weguardian.gui.kick` |
| `/notesmenu <玩家>` | 直接打开备注 GUI | `weguardian.gui.notes` |
| `/unbanmenu <玩家>` | 直接打开解除封禁 GUI | `weguardian.gui.unban` |
| `/unmutemenu <玩家>` | 直接打开解除静音 GUI | `weguardian.gui.unmute` |
## 🛠️ 安装
### 要求
- **Java 21** 或更高版本
- **Paper/Bukkit 1.21.1** 或兼容版本
- **Folia 支持**: 配合 FoliaLib 完全支持
- **PlaceholderAPI** (推荐)
### 设置步骤
1. **下载 & 安装**
```bash
wget https://github.com/WeThink25/WeGuardian/releases/latest/download/WeGuardian.jar
```
2. **首次运行**
```bash
# 启动您的服务器以生成默认配置
# 插件将自动创建 config.yml、messages.yml、templates.yml 和 GUI 文件
```
3. **配置数据库**
```yaml
database:
type: "yaml" # 或 "mysql"
mysql:
enabled: true
host: "localhost"
port: 3306
database: "weguardian"
username: "root"
password: "你的密码"
```
4. **设置权限**
```yaml
groups:
moderator:
permissions:
- weguardian.punish
- weguardian.tempban
- weguardian.tempmute
- weguardian.kick
- weguardian.warn
- weguardian.history
- weguardian.checkban
- weguardian.gui.*
admin:
permissions:
- weguardian.*
- weguardian.bypass.override
```
## 🔐 权限系统
### 核心权限
```yaml
weguardian.punish # 访问 /punish 命令
weguardian.ban # 永久封禁权限
weguardian.tempban # 临时封禁权限
weguardian.mute # 永久静音权限
weguardian.tempmute # 临时静音权限
weguardian.kick # 踢出权限
weguardian.warn # 警告权限
weguardian.unban # 解除封禁权限
weguardian.unmute # 解除静音权限
weguardian.ipban # IP 封禁权限
weguardian.ipmute # IP 静音权限
weguardian.unbanip # IP 解除封禁权限
weguardian.unmuteip # IP 解除静音权限
weguardian.banlist # 查看封禁列表
weguardian.mutelist # 查看静音列表
weguardian.alts # 小号检测
weguardian.blame # 查看惩罚详情
weguardian.warns # 查看警告
weguardian.unwarn # 移除警告
weguardian.history # 查看惩罚历史
weguardian.checkban # 检查封禁/静音状态
weguardian.notes # 查看工作人员备注
weguardian.staffstatus # 查看工作人员统计
weguardian.stats # 查看全局统计
weguardian.rollback # 回滚惩罚
weguardian.banwave # 管理封禁波系统
weguardian.admin # 插件管理
weguardian.gui.* # 所有 GUI 访问
weguardian.gui.ban # 封禁 GUI 访问
weguardian.gui.tempban # 临时封禁 GUI 访问
weguardian.gui.mute # 静音 GUI 访问
weguardian.gui.tempmute # 临时静音 GUI 访问
weguardian.gui.warn # 警告 GUI 访问
weguardian.gui.kick # 踢出 GUI 访问
weguardian.gui.notes # 备注 GUI 访问
weguardian.gui.unban # 解除封禁 GUI 访问
weguardian.gui.unmute # 解除静音 GUI 访问
weguardian.bypass.override # 绕过惩罚保护
weguardian.silent # 使用静默惩罚标志
weguardian.templates # 使用惩罚模板
```
## 🎯 惩罚模板
### 模板系统
WeGuardian 包含一个全面的惩罚模板系统:
```yaml
templates:
spam:
category: "chat"
auto-escalate: true
track-offenses: true
levels:
1:
type: "TEMPMUTE"
duration: "30m"
reason: "Spam - First Offense"
2:
type: "TEMPMUTE"
duration: "2h"
reason: "Spam - Second Offense"
3:
type: "TEMPBAN"
duration: "1d"
reason: "Spam - Final Warning"
```
### 可用模板
- **聊天违规**: spam, toxicity, harassment, advertising
- **游戏玩法**: griefing, stealing, pvp_abuse, building_violations
- **作弊**: hacking, xray, fly, speed, killaura
- **行为**: disrespect, inappropriate_language, trolling
- **规避**: ban_evasion, mute_evasion, alt_abuse
## 🌐 跨服务器同步
### 配置
```yaml
cross_server:
enabled: true
sync_interval: 30
sync_punishments: true
sync_player_data: true
sync_banwave: true
broadcast_punishments: true
require_authentication: false
authentication_key: "your-secret-key-here"
servers:
- name: "lobby"
host: "localhost"
port: 25565
enabled: true
- name: "survival"
host: "localhost"
port: 25566
enabled: true
```
### 特性
- **实时同步**: 所有服务器之间即时同步惩罚
- **HTTP API**: 用于服务器通信的 RESTful API 端点
- **身份验证**: 可选的 API 密钥身份验证以确保安全
- **健康检查**: 自动验证服务器连接
- **错误处理**: 优雅地处理网络故障
## 🎨 菜单系统
### 菜单验证
WeGuardian 包含全面的菜单验证:
```yaml
menus:
validation:
enabled: true
check_menu_links: true
check_item_materials: true
check_action_formats: true
auto_fix_issues: false
performance:
cache_menu_configs: true
preload_common_menus: true
async_menu_loading: true
```
### 可用菜单
- **main**: 主要惩罚中心
- **ban**: 永久封禁界面
- **tempban**: 临时封禁界面
- **mute**: 永久静音界面
- **tempmute**: 临时静音界面
- **kick**: 踢出界面
- **warn**: 警告界面
- **notes**: 工作人员备注界面
- **unban**: 解除封禁界面
- **unmute**: 解除静音界面
## 🔧 配置
### 性能设置
```yaml
performance:
thread_pool_size: 4
max_concurrent_operations: 50
operation_timeout: 30
cache:
enabled: true
cleanup_interval: 300
max_cache_size: 10000
expire_after_access: 1800
expire_after_write: 3600
database:
batch_size: 100
connection_pool_size: 10
prepared_statement_cache_size: 250
query_timeout: 15
```
### 调试设置
```yaml
debug:
enabled: false
log_level: "INFO"
log_sql_queries: false
log_performance_metrics: false
log_cache_statistics: false
```
## 🚀 开发
### 从源代码构建
```bash
git clone https://github.com/WeThink25/WeGuardian.git
cd WeGuardian
mvn clean package
```
### API 使用
#### 基本惩罚 API
```java
WeGuardian plugin = (WeGuardian) Bukkit.getPluginManager().getPlugin("WeGuardian");
PunishmentService service = plugin.getPunishmentService();
// 执行封禁
service.ban("玩家名", "工作人员名", "破坏", null)
.thenAccept(success -> {
if (success) {
// 封禁成功执行
}
});
// 执行模板惩罚
service.executeTemplate(
staffUuid,
staffName,
targetName,
"spam"
).thenAccept(success -> {
if (success) {
// 自动升级的模板惩罚执行
}
});
```
#### 跨服务器同步 API
```java
CrossServerSyncService syncService = plugin.getCrossServerSyncService();
// 将惩罚广播到所有服务器
syncService.broadcastPunishment(punishment);
// 验证服务器连接
syncService.validateServerConnections();
// 检查是否启用同步
if (syncService.isEnabled()) {
// 跨服务器同步处于活动状态
}
```
#### 菜单验证 API
```java
MenuValidationService validationService = plugin.getMenuValidationService();
// 验证所有菜单
validationService.validateAllMenus();
// 验证菜单性能
validationService.validateMenuPerformance();
// 检查是否启用验证
if (validationService.isValidationEnabled()) {
// 菜单验证处于活动状态
}
```
#### 数据库 API
```java
DatabaseManager database = plugin.getDatabaseManager();
// 获取玩家数据
database.getPlayerData(playerUuid)
.thenAccept(playerData -> {
if (playerData != null) {
// 玩家数据检索
}
});
// 添加惩罚
database.addPunishment(punishment)
.thenAccept(punishmentId -> {
if (punishmentId > 0) {
// 惩罚添加成功
}
});
// 获取惩罚历史
database.getPunishmentHistory(playerUuid)
.thenAccept(punishments -> {
// 处理惩罚历史
});
```
#### FoliaLib 集成
```java
FoliaLib foliaLib = plugin.getFoliaLib();
// 检查是否运行在 Folia 上
if (foliaLib.isFolia()) {
// Folia 特定优化
}
// 安排异步任务
foliaLib.getScheduler().runTimerAsync(() -> {
// 异步任务
}, 20L, 20L);
// 安排针对实体的任务
foliaLib.getScheduler().runAtEntity(player, task -> {
// 针对实体的任务
});
```
### 事件集成
```java
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
Player player = event.getPlayer();
// 检查玩家是否被封禁
plugin.getDatabaseManager().isPlayerBanned(player.getUniqueId())
.thenAccept(isBanned -> {
if (isBanned) {
// 处理被封禁的玩家
}
});
}
```
## 📊 性能监控
### 内置指标
- **缓存统计**: 监控缓存命中率和性能
- **数据库性能**: 跟踪查询执行时间
- **线程池使用**: 监控异步操作负载
- **跨服务器同步**: 跟踪同步成功率
- **菜单性能**: 监控 GUI 加载时间
### 调试信息
启用调试模式以获取详细的日志记录:
```yaml
debug:
enabled: true
log_performance_metrics: true
log_cache_statistics: true
log_sql_queries: true
```
### 版本更新
- **自动配置更新**: 在版本之间无缝配置迁移
- **数据库模式更新**: 自动数据库结构更新
- **向后兼容**: 保持与先前版本的兼容
## 🆘 支持 & 贡献
### 获取帮助
- **Discord**: [加入我们的 Discord](https://discord.gg/aSWKs3k4XA)
- **问题**: [GitHub Issues](https://github.com/WeThink25/WeGuardian/issues)
- **Wiki**: [文档 Wiki](https://github.com/WeThink25/WeGuardian/wiki)
- **bStats**: [插件统计](https://bstats.org/plugin/bukkit/WeGuardian/27046)
### 贡献
1. Fork 仓库
2. 创建功能分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求
### 开发指南
- 遵循 Java 编码标准
- 添加全面的调试日志记录
- 包括适当的错误处理
- 在 Paper 和 Folia 上进行测试
- 更新新功能的文档
## 📜 许可
本项目使用 **开源贡献许可 (MIT + 非商业)** 授权。
请参阅 [LICENSE.txt](LICENSE.txt) 文件以获取完整的法律文本。
### 🔎 TL;DR
- ✅ 免费使用、共享和修改。
- 🚫 不允许用于商业用途 (禁止销售、禁止创建付费分支、禁止捆绑在付费产品中)。
- 🔄 如果您更改或改进了一些东西，您必须在相同条款下贡献您的更改 (例如通过拉取请求或补丁)。
- 📝 保持所有副本中的版权和许可通知。
- ⚠️ 无任何担保。
## 🙏 致谢
- **Paper 团队** - 优秀的服务器软件
- **Folia 团队** - 下一代服务器架构
- **FoliaLib** - 跨平台兼容性
- **PlaceholderAPI** - 占位符集成
- **Adventure API** - 现代文本组件
- **HikariCP** - 高性能数据库连接池
---
**WeGuardian** - 现代服务器的专业 Minecraft 惩罚系统。
*用 ❤️ 为 Minecraft 社区打造*