Peijun Zhao
c8a1037f9e
- README.md/EN: 架构图、模块清单、双模式部署、WebSocket协议、75种告警类型 - docs/DEVELOPER.md: 五核心设计模式、七步添加新模块模板、事件监听器、Agent协议 - docs/PROJECT_SUMMARY.md: 模块统计、100% Meteor Client覆盖矩阵、竞品对比 - docs/USER_MANUAL.md: 安装、配置详解、CLI命令、Web控制台、性能调优、故障排查
36 KiB
36 KiB
Aluer ServerGuard V5.0 -- 开发者参考手册
版本信息
| 项目 | 内容 |
|---|---|
| 版本号 | V5.0 (含 V5.1/V5.2/V5.3 子版本) |
| 更新日期 | 2026-05-16 |
| Java 版本 | 21 |
| Spring Boot | 3.2.0 |
| 构建工具 | Apache Maven 3.9.6 (bundled) |
| PaperMC API | 1.21.1-R0.1-SNAPSHOT |
目录
系统架构
整体架构
+------------------------------------------------------------------+
| Aluer ServerGuard V5.0 |
| |
| 部署模式一：Plugin 内嵌模式（推荐） |
| ┌─────────────────────────────────────────────────────────────┐ |
| │ Minecraft PaperMC JVM │ |
| │ ┌──────────────┐ WebSocket ┌──────────────────┐ │ |
| │ │ AluerPlugin │ ◄═══════════════► │ ServerGuard │ │ |
| │ │ (Paper插件) │ ws://:8080/agent │ Spring Boot App │ │ |
| │ │ │ │ │ │ |
| │ │ Bukkit事件 → │ ──EVENT/METRICS──► │ 安全分析引擎 │ │ |
| │ │ 监听器 │ │ ML/AI模块 │ │ |
| │ │ │ ◄──COMMAND/CONFIG─ │ DeepSeek集成 │ │ |
| │ │ 命令执行器 ← │ │ Web Dashboard │ │ |
| │ └──────────────┘ └──────────────────┘ │ |
| └─────────────────────────────────────────────────────────────┘ |
| |
| 部署模式二：External 外部监控模式 |
| ┌──────────────────┐ RCON + 日志监控 ┌──────────────┐ |
| │ PaperMC Server │ ◄═══════════════════► │ ServerGuard │ |
| │ (独立JVM) │ │ (独立JVM) │ |
| └──────────────────┘ └──────────────┘ |
+------------------------------------------------------------------+
数据流向
Bukkit Events
│
▼
┌─────────────┐ AgentMessage.buildMessage() ┌──────────────┐
│ Event │ ─────────────────────────────────► │ Security │
│ Listeners │ JSON via WebSocket │ Modules │
│ (9个监听器) │ │ (123个模块) │
└─────────────┘ │ │
│ ┌─────────┐ │
│ │ ML/AI │ │
│ │ Engine │ │
│ └────┬────┘ │
│ │ │
│ ┌────▼────┐ │
│ │DeepSeek │ │
│ │Analysis │ │
│ └────┬────┘ │
│ │ │
│ ┌────▼────┐ │
│ │Autonomy │ │
│ │/Shield │ │
│ └────┬────┘ │
└──────│───────┘
│
AgentMessage.buildCommand()
│
▼
┌──────────────┐
│ AluerPlugin │
│ Command │
│ Executor │
│ (Bukkit API) │
└──────────────┘
项目结构
src/main/java/com/aluer/
│
├── ServerGuardApplication.java # Spring Boot 主入口
│
├── config/
│ └── ServerGuardConfig.java # 完整配置类（1273行）
│ ├── MinecraftConfig # Minecraft 进程配置
│ ├── MonitorConfig # 监控阈值配置
│ ├── AlertConfig # 告警（邮件）配置
│ ├── AiConfig # AI/ML 配置
│ │ └── DeepSeekConfig # DeepSeek 大模型配置
│ │ └── AutoExecuteConfig # 自动执行配置
│ ├── SecurityConfig # 安全总配置
│ │ ├── MinecraftDefenseConfig # Minecraft 协议层防御
│ │ ├── DDoSDefenseConfig # DDoS 防御阈值
│ │ ├── AntiIntrusionConfig # 入侵检测配置
│ │ ├── HostEnforcementConfig # 主机层强制
│ │ ├── CloudEdgeConfig # Cloudflare 边缘
│ │ ├── ThreatFeedsConfig # 威胁情报源
│ │ ├── OrchestrationConfig # 多层编排
│ │ ├── AutomationConfig # 自动化调度
│ │ ├── AutonomyConfig # 自主决策
│ │ ├── ShieldConfig # 护盾配置
│ │ ├── KernelConfig # 内核/脉冲配置
│ │ ├── TaskBusConfig # 任务总线
│ │ ├── SelfHealingConfig # 自愈配置
│ │ └── SuperEvolutionConfig # 全部模块开关（70+开关）
│ ├── DashboardConfig # Web 控制台
│ ├── AnnouncementConfig # 公告
│ ├── AfkConfig # AFK 管理
│ ├── ChatFilterConfig # 聊天过滤
│ ├── BackupConfig # 备份配置
│ └── ScheduleConfig # 定时任务
│
├── model/
│ └── AlertType.java # 告警类型枚举（75种）
│
├── agent/
│ └── AgentMessage.java # Agent 通信协议
│ # 常量：TYPE_EVENT, TYPE_METRICS, TYPE_ALERT,
│ # TYPE_HEARTBEAT, TYPE_HANDSHAKE, TYPE_COMMAND_RESULT,
│ # TYPE_COMMAND, TYPE_CONFIG, TYPE_SHUTDOWN
│ # 命令：CMD_BAN_IP, CMD_BAN_PLAYER, CMD_KICK,
│ # CMD_CLEAR_LAG, CMD_SET_SPAWN_RATE, ...
│ # 事件：EVENT_PLAYER_JOIN, EVENT_PLAYER_MOVE,
│ # EVENT_COMBAT_ATTACK, EVENT_BLOCK_BREAK, ...
│
├── security/ # 安全模块（123个Java文件）
│ ├── AntiKillAuraService.java # 杀戮光环检测
│ ├── AntiReachService.java # 超距攻击检测
│ ├── AntiSpeedService.java # 速度异常检测
│ ├── AntiCriticalsService.java # 暴击检测
│ ├── AntiAutoCrystalService.java # 水晶自动检测
│ ├── ... # 120+ more
│ └── ZeroTrustArchitectureService.java
│
├── ml/ # ML/AI 模块（4个文件）
│ ├── BehavioralProfilingEngine.java # 行为画像
│ ├── CombatPatternRecognizer.java # 战斗模式识别
│ ├── MovementPatternAnalyzer.java # 移动模式分析
│ └── ThreatScoreAggregator.java # 威胁评分聚合
│
├── plugin/ # Paper 插件实现
│ ├── AluerPlugin.java # 插件主类 (extends JavaPlugin)
│ ├── AluerCommandExecutor.java # 命令注册器
│ ├── bridge/
│ │ ├── AgentWebSocketClient.java # WebSocket 客户端
│ │ ├── DataBridge.java # 数据格式转换
│ │ └── InternalCommandExecutor.java # Bukkit API命令执行
│ └── listener/ # Bukkit 事件监听器
│ ├── BlockEventListener.java # 方块事件
│ ├── ChatEventListener.java # 聊天事件
│ ├── CombatEventListener.java # 战斗事件
│ ├── CommandEventListener.java # 命令事件
│ ├── EntityEventListener.java # 实体事件
│ ├── InventoryEventListener.java # 背包事件
│ ├── PacketEventListener.java # 原始包事件
│ ├── PlayerEventListener.java # 玩家事件
│ └── WorldEventListener.java # 世界事件
│
├── websocket/ # WebSocket 服务端
└── controller/
└── TestController.java # 测试端点
核心设计模式
1. 双构造函数模式
每个安全模块 Service 类同时提供两个构造函数，确保测试友好性和生产注入兼容性：
@Service
public class AntiKillAuraService {
private final ServerGuardConfig config;
/** 无参构造函数：用于单元测试，使用默认配置 */
public AntiKillAuraService() {
this.config = new ServerGuardConfig();
}
/** @Autowired 构造函数：用于生产环境，Spring 自动注入 */
@Autowired
public AntiKillAuraService(ServerGuardConfig config) {
this.config = config;
}
// ... 检测逻辑
}
2. 静态工厂方法模式
检测结果使用内部静态类 + 静态工厂方法构建，避免直接 new：
public static class DetectionResult {
public enum Status { CLEAN, BLOCKED, FLAGGED }
private final Status status;
private final String reason;
private final double confidence;
private DetectionResult(Status status, String reason, double confidence) {
this.status = status;
this.reason = reason;
this.confidence = confidence;
}
public static DetectionResult clean() {
return new DetectionResult(Status.CLEAN, null, 0.0);
}
public static DetectionResult blocked(String reason, double confidence) {
return new DetectionResult(Status.BLOCKED, reason, confidence);
}
public static DetectionResult flagged(String reason, double confidence) {
return new DetectionResult(Status.FLAGGED, reason, confidence);
}
// getters...
}
3. ConcurrentHashMap 玩家追踪
所有安全模块使用 ConcurrentHashMap<String, ...> 以玩家名称为键追踪行为数据，确保线程安全：
private final Map<String, List<AttackRecord>> playerAttackHistory = new ConcurrentHashMap<>();
private final Map<String, List<Double>> playerAngleHistory = new ConcurrentHashMap<>();
4. AtomicLong 统计计数
使用 AtomicLong 进行线程安全的统计计数：
private final AtomicLong totalChecks = new AtomicLong(0);
private final AtomicLong flaggedCount = new AtomicLong(0);
5. 配置驱动开关
每个模块通过 SuperEvolutionConfig 中的独立开关控制启用/禁用：
if (!config.getSecurity().getSuperEvolution().isAntiKillAura()) {
return DetectionResult.clean(); // 模块已禁用，跳过检测
}
添加新反作弊模块
完整步骤
第一步：确认反作弊 Hack 类型
查阅 Meteor Client 的 hack 分类（Combat/Movement/World/Player/Misc/Render），确定你要对抗的 hack 名称和类型。
第二步：创建 Service 类
在 src/main/java/com/aluer/security/ 下创建新类，遵循命名规范 Anti{Xxx}Service.java：
package com.aluer.security;
import com.aluer.config.ServerGuardConfig;
import org.springframework.stereotype.Service;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;
/**
* {Hack名称}检测服务 — V5.X 反作弊模块
*
* 检测原理：
* 1. {原理1的详细说明}
* 2. {原理2的详细说明}
*
* 配置开关：serverguard.security.super-evolution.anti-{xxx}
*/
@Service
public class AntiNewHackService {
private final ServerGuardConfig config;
/** 追踪每个玩家的行为数据 */
private final Map<String, List<BehaviorRecord>> playerHistory = new ConcurrentHashMap<>();
private final AtomicLong totalChecks = new AtomicLong(0);
private final AtomicLong flaggedCount = new AtomicLong(0);
// 常量定义
private static final int ANALYSIS_WINDOW_MS = 3000;
private static final double FLAG_THRESHOLD = 0.85;
/** 无参构造函数（测试用） */
public AntiNewHackService() {
this.config = new ServerGuardConfig();
}
/** @Autowired 构造函数（生产用） */
public AntiNewHackService(ServerGuardConfig config) {
this.config = config;
}
/**
* 分析玩家行为，检测是否存在 {hack名称} 作弊
*
* @param playerName 玩家名称
* @param eventData 事件数据（根据 hack 类型确定参数）
* @return 检测结果（CLEAN/FLAGGED/BLOCKED）
*/
public DetectionResult analyze(String playerName, EventData eventData) {
// 1. 检查模块是否启用
if (!config.getSecurity().getSuperEvolution().isAntiNewHack()) {
return DetectionResult.clean();
}
totalChecks.incrementAndGet();
// 2. 更新玩家行为历史
List<BehaviorRecord> history = playerHistory.computeIfAbsent(
playerName, k -> Collections.synchronizedList(new ArrayList<>())
);
history.add(new BehaviorRecord(eventData, System.currentTimeMillis()));
// 3. 清理过期记录（超出分析窗口）
long cutoff = System.currentTimeMillis() - ANALYSIS_WINDOW_MS;
history.removeIf(r -> r.timestamp < cutoff);
// 4. 分析行为模式
double anomalyScore = computeAnomalyScore(history);
// 5. 返回结果
if (anomalyScore > FLAG_THRESHOLD) {
flaggedCount.incrementAndGet();
return DetectionResult.flagged(
String.format("NewHack detected: anomaly score %.2f", anomalyScore),
anomalyScore
);
}
return DetectionResult.clean();
}
private double computeAnomalyScore(List<BehaviorRecord> history) {
// 实现具体的异常检测算法
// ...
return 0.0;
}
/** 行为记录内部类 */
private static class BehaviorRecord {
final EventData data;
final long timestamp;
BehaviorRecord(EventData data, long timestamp) {
this.data = data;
this.timestamp = timestamp;
}
}
/** 检测结果（静态工厂） */
public static class DetectionResult {
public enum Status { CLEAN, BLOCKED, FLAGGED }
private final Status status;
private final String reason;
private final double confidence;
private DetectionResult(Status status, String reason, double confidence) {
this.status = status;
this.reason = reason;
this.confidence = confidence;
}
public static DetectionResult clean() {
return new DetectionResult(Status.CLEAN, null, 0.0);
}
public static DetectionResult blocked(String reason, double confidence) {
return new DetectionResult(Status.BLOCKED, reason, confidence);
}
public static DetectionResult flagged(String reason, double confidence) {
return new DetectionResult(Status.FLAGGED, reason, confidence);
}
public Status getStatus() { return status; }
public String getReason() { return reason; }
public double getConfidence() { return confidence; }
public boolean isClean() { return status == Status.CLEAN; }
public boolean isBlocked() { return status == Status.BLOCKED; }
public boolean isFlagged() { return status == Status.FLAGGED; }
}
}
第三步：添加告警类型
在 AlertType.java 中新增枚举值：
// 在对应分类区域添加
SECURITY_NEW_HACK("NewHack", "Description of this hack detection"),
第四步：添加配置开关
在 ServerGuardConfig.SuperEvolutionConfig 中新增：
// 属性声明
private boolean antiNewHack = true;
// Getter
public boolean isAntiNewHack() { return antiNewHack; }
// Setter
public void setAntiNewHack(boolean antiNewHack) { this.antiNewHack = antiNewHack; }
第五步：添加 application.yml 配置
# 在 super-evolution 节中添加
anti-new-hack: true # 新Hack检测说明
第六步：编写单元测试
在 src/test/java/com/aluer/security/ 下创建测试类：
package com.aluer.security;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;
class AntiNewHackServiceTest {
private final AntiNewHackService service = new AntiNewHackService();
@Test
void testCleanBehavior() {
// 正常玩家行为应该返回 CLEAN
// ...
}
@Test
void testFlaggedBehavior() {
// 异常行为应该返回 FLAGGED
// ...
}
@Test
void testModuleDisabled() {
// 模块关闭时应返回 CLEAN
// ...
}
}
第七步：全量测试
./apache-maven-3.9.6/bin/mvn test
确保所有现有测试和新测试全部通过。
事件监听器模式
监听器基类结构
所有 Bukkit 事件监听器位于 com.aluer.plugin.listener 包下，每个监听器负责一类事件：
package com.aluer.plugin.listener;
import com.aluer.plugin.bridge.DataBridge;
import org.bukkit.event.Listener;
/**
* {事件类别}监听器 — 拦截 Bukkit 事件并转发至 ServerGuard 引擎
*/
public class XxxEventListener implements Listener {
private final DataBridge dataBridge;
public XxxEventListener(DataBridge dataBridge) {
this.dataBridge = dataBridge;
}
@EventHandler(priority = EventPriority.MONITOR)
public void onXxxEvent(XxxEvent event) {
// 1. 提取事件数据
// 2. 通过 DataBridge 转换为 AgentMessage
// 3. 通过 WebSocket 发送至 ServerGuard
dataBridge.sendEvent("EVENT_TYPE", eventData);
}
}
九大监听器及其监听事件
| 监听器 | 主要监听事件 | 数据类型 |
|---|---|---|
| BlockEventListener | BlockBreakEvent, BlockPlaceEvent | 方块坐标、类型、玩家、工具 |
| ChatEventListener | AsyncPlayerChatEvent | 消息内容、发送时间 |
| CombatEventListener | EntityDamageByEntityEvent, PlayerDeathEvent | 攻击者、目标、伤害量、武器 |
| CommandEventListener | PlayerCommandPreprocessEvent | 命令文本、执行时间 |
| EntityEventListener | EntitySpawnEvent, EntityDeathEvent | 实体类型、坐标、原因 |
| InventoryEventListener | InventoryClickEvent, InventoryOpenEvent | 槽位、物品类型、容器位置 |
| PacketEventListener | PacketEvent (ProtocolLib) | 原始数据包内容 |
| PlayerEventListener | PlayerJoinEvent, PlayerQuitEvent, PlayerMoveEvent | 玩家信息、坐标、移动向量 |
| WorldEventListener | ChunkLoadEvent, ChunkUnloadEvent | 区块坐标、加载原因 |
DataBridge 数据转换
DataBridge 负责将 Bukkit 事件数据转换为 AgentMessage JSON 格式：
public class DataBridge {
private final AgentWebSocketClient wsClient;
public void sendEvent(String eventType, JsonObject eventData) {
JsonObject payload = new JsonObject();
payload.addProperty("eventType", eventType);
// 添加通用字段
payload.add("data", eventData);
String message = AgentMessage.buildMessage(
AgentMessage.TYPE_EVENT,
agentId,
payload
);
wsClient.send(message);
}
}
Agent 通信协议详解
协议设计
通信基于 WebSocket (RFC 6455)，所有消息为单行 JSON 文本帧。
消息类型枚举
定义在 AgentMessage.java 中：
Agent → Server:
| 常量 | 值 | 说明 |
|---|---|---|
| TYPE_EVENT | "EVENT" | Bukkit 事件上报 |
| TYPE_METRICS | "METRICS" | 服务器性能指标 |
| TYPE_ALERT | "ALERT" | 安全告警上报 |
| TYPE_HEARTBEAT | "HEARTBEAT" | 心跳保活（间隔由Kernel配置） |
| TYPE_HANDSHAKE | "HANDSHAKE" | 初始连接握手 |
| TYPE_COMMAND_RESULT | "COMMAND_RESULT" | 命令执行结果回执 |
Server → Agent:
| 常量 | 值 | 说明 |
|---|---|---|
| TYPE_COMMAND | "COMMAND" | 防御指令下发 |
| TYPE_CONFIG | "CONFIG" | 动态配置更新 |
| TYPE_SHUTDOWN | "SHUTDOWN" | 连接关闭通知 |
命令类型
| 常量 | 值 | 对应 Bukkit 操作 |
|---|---|---|
| CMD_BAN_IP | "BAN_IP" | Bukkit.banIP() |
| CMD_BAN_PLAYER | "BAN_PLAYER" | Bukkit.getBanList().addBan() |
| CMD_KICK | "KICK" | Player.kickPlayer() |
| CMD_CLEAR_LAG | "CLEAR_LAG" | World.getEntities().clear() |
| CMD_SET_SPAWN_RATE | "SET_SPAWN_RATE" | 调整 spawn-limits |
| CMD_ENABLE_WHITELIST | "ENABLE_WHITELIST" | Bukkit.setWhitelist(true) |
| CMD_DISABLE_WHITELIST | "DISABLE_WHITELIST" | Bukkit.setWhitelist(false) |
| CMD_BROADCAST | "BROADCAST" | Bukkit.broadcastMessage() |
| CMD_SAVE_ALL | "SAVE_ALL" | Bukkit.savePlayers() + World.save() |
| CMD_EXECUTE | "EXECUTE" | Bukkit.dispatchCommand() |
事件类型
| 常量 | 值 | 关联 Bukkit 事件 |
|---|---|---|
| EVENT_PLAYER_JOIN | "PLAYER_JOIN" | PlayerJoinEvent |
| EVENT_PLAYER_QUIT | "PLAYER_QUIT" | PlayerQuitEvent |
| EVENT_PLAYER_MOVE | "PLAYER_MOVE" | PlayerMoveEvent |
| EVENT_PLAYER_TELEPORT | "PLAYER_TELEPORT" | PlayerTeleportEvent |
| EVENT_PLAYER_CHAT | "PLAYER_CHAT" | AsyncPlayerChatEvent |
| EVENT_PLAYER_COMMAND | "PLAYER_COMMAND" | PlayerCommandPreprocessEvent |
| EVENT_PLAYER_DAMAGE | "PLAYER_DAMAGE" | EntityDamageEvent |
| EVENT_COMBAT_ATTACK | "COMBAT_ATTACK" | EntityDamageByEntityEvent |
| EVENT_COMBAT_DEATH | "COMBAT_DEATH" | PlayerDeathEvent |
| EVENT_BLOCK_BREAK | "BLOCK_BREAK" | BlockBreakEvent |
| EVENT_BLOCK_PLACE | "BLOCK_PLACE" | BlockPlaceEvent |
| EVENT_INVENTORY_CLICK | "INVENTORY_CLICK" | InventoryClickEvent |
| EVENT_ENTITY_SPAWN | "ENTITY_SPAWN" | EntitySpawnEvent |
| EVENT_CHUNK_LOAD | "CHUNK_LOAD" | ChunkLoadEvent |
消息格式规范
// Agent → Server: 构建消息
public static String buildMessage(String type, String agentId, JsonObject payload) {
JsonObject msg = new JsonObject();
msg.addProperty("type", type);
msg.addProperty("agentId", agentId);
msg.addProperty("timestamp", Instant.now().toEpochMilli());
msg.add("payload", payload);
return gson.toJson(msg);
}
// Server → Agent: 构建命令
public static String buildCommand(String commandType, String target, String reason) {
JsonObject payload = new JsonObject();
payload.addProperty("command", commandType);
payload.addProperty("target", target != null ? target : "");
payload.addProperty("reason", reason != null ? reason : "");
JsonObject msg = new JsonObject();
msg.addProperty("type", TYPE_COMMAND);
msg.addProperty("requestId", UUID.randomUUID().toString());
msg.addProperty("timestamp", Instant.now().toEpochMilli());
msg.add("payload", payload);
return gson.toJson(msg);
}
// 解析工具方法
public static String getType(String message) { /* 解析 type 字段 */ }
public static JsonObject getPayload(String message) { /* 解析 payload 对象 */ }
public static String getAgentId(String message) { /* 解析 agentId 字段 */ }
配置系统
配置层次结构
application.yml
└── serverguard.* # 所有配置的前缀
├── mode # 运行模式：plugin | external
├── minecraft.* # Minecraft 进程管理
├── monitor.* # 监控阈值
├── alert.* # 告警配置
│ └── email.* # 邮件配置
├── ai.* # AI/ML 配置
│ └── deepseek.* # DeepSeek 集成
│ └── auto-execute.* # 自动执行
├── security.* # 安全配置
│ ├── minecraft-defense.* # 协议层防御
│ ├── ddos-defense.* # DDoS 防御
│ ├── anti-intrusion.* # 入侵检测
│ │ └── file-integrity.* # 文件完整性
│ ├── host-enforcement.* # 主机强制
│ ├── cloud-edge.* # 云端边缘
│ ├── threat-feeds.* # 威胁情报
│ ├── orchestration.* # 编排
│ ├── automation.* # 自动化
│ ├── autonomy.* # 自主决策
│ ├── shield.* # 护盾
│ ├── kernel.* # 内核
│ ├── task-bus.* # 任务总线
│ ├── self-healing.* # 自愈
│ └── super-evolution.* # 模块开关（70+个）
├── dashboard.* # Web 控制台
│ └── ssh-gateway.* # SSH 网关
├── announcement.* # 公告
├── afk.* # AFK 管理
├── chat-filter.* # 聊天过滤
├── backup.* # 备份
└── schedule.* # 定时任务
配置类映射关系
ServerGuardConfig 使用 @ConfigurationProperties(prefix = "serverguard") 注解，Spring Boot 自动将 YAML 配置绑定到对应的嵌套静态内部类。
命名转换规则：
- YAML 中
kebab-case（如tps-threshold） - Java 中
camelCase（如tpsThreshold） - Spring Boot 自动完成转换
环境变量覆盖
配置值可以使用 ${ENV_VAR:default} 语法通过环境变量覆盖，示例如下：
serverguard:
mode: ${SERVERGUARD_MODE:external}
ai:
deepseek:
api-key: ${DEEPSEEK_API_KEY:}
model: ${DEEPSEEK_MODEL:deepseek-chat}
alert:
email:
username: ${ALUER_ALERT_SMTP_USERNAME:}
password: ${ALUER_ALERT_SMTP_PASSWORD:}
ML/AI 集成
四大 ML 模块
| 模块 | 功能 | 算法 |
|---|---|---|
| BehavioralProfilingEngine | 基于统计特征建立玩家行为基线，检测偏离 | Isolation Forest, Statistical Profiling |
| CombatPatternRecognizer | 识别异常战斗序列（多目标切换、异常连击模式） | Pattern Matching, Sequence Analysis |
| MovementPatternAnalyzer | 分析移动轨迹异常（路径熵值、加速度模式） | Trajectory Analysis, Entropy Calculation |
| ThreatScoreAggregator | 融合多维度检测结果，生成统一威胁评分 | Weighted Aggregation, Escalation Logic |
AI 配置参数
ai:
enabled: true
use-isolation-forest: true # 启用隔离森林
use-prediction: true # 启用时间序列预测
sliding-window-size: 100 # 滑动窗口数据点数
anomaly-threshold: 0.7 # 异常判定阈值 (0.0-1.0)
prediction-horizon-minutes: 60 # 预测未来时间范围
DeepSeek 集成
ai:
deepseek:
enabled: true
api-key: ${DEEPSEEK_API_KEY:}
base-url: https://api.deepseek.com
model: deepseek-chat
max-tokens: 1000
temperature: 0.35 # 低温度获得稳定分析
auto-analyze-alerts: true # 自动分析所有告警
analysis-interval-seconds: 45 # 分析间隔
auto-execute:
enabled: true
ban-ip: true
kill-entity: true
clear-lag: true
set-spawn-rate: true
kick-player: true
whitelist: true
min-confidence: 88 # 低于此置信度不自动执行
测试规范
测试原则
- 打靶试验 — 测试必须模拟真实 Minecraft 服务器环境，不允许使用假数据
- 生产对齐 — 测试数据和行为必须与实际生产环境对齐
- 全量验证 — 修改代码前后必须跑全量 278 项测试，一个不能挂
- 双构造函数模式 — 每个 Service 必须提供无参构造函数用于测试
测试类命名规范
src/test/java/com/aluer/
├── security/
│ ├── AntiKillAuraServiceTest.java
│ ├── AntiReachServiceTest.java
│ └── ...
├── ml/
│ ├── BehavioralProfilingEngineTest.java
│ └── ...
└── plugin/
└── ...
测试方法命名
@Test
void testCleanBehavior() { } // 正常行为 → CLEAN
@Test
void testFlaggedBehavior() { } // 可疑行为 → FLAGGED
@Test
void testBlockedBehavior() { } // 明确作弊 → BLOCKED
@Test
void testModuleDisabled() { } // 模块关闭 → CLEAN
@Test
void testEdgeCase() { } // 边界条件
@Test
void testPerformance() { } // 性能测试
运行测试
# 全量测试
./apache-maven-3.9.6/bin/mvn test
# 运行特定测试类
./apache-maven-3.9.6/bin/mvn test -Dtest=AntiKillAuraServiceTest
# 运行特定测试方法
./apache-maven-3.9.6/bin/mvn test -Dtest=AntiKillAuraServiceTest#testFlaggedBehavior
代码风格指南
命名规范
| 元素 | 规范 | 示例 |
|---|---|---|
| 包名 | 全小写 | com.aluer.security |
| 类名 | PascalCase | AntiKillAuraService |
| 方法名 | camelCase | analyzePlayerBehavior() |
| 常量 | UPPER_SNAKE_CASE | MAX_ATTACK_DISTANCE |
| 配置属性 | camelCase (Java) / kebab-case (YAML) | tpsThreshold / tps-threshold |
| 枚举值 | UPPER_SNAKE_CASE | SECURITY_KILL_AURA |
注释规范
- 类级别：必须有 JavaDoc 注释，说明模块功能、检测原理、配置开关
- 方法级别：必须有 JavaDoc 注释，说明参数、返回值、算法思路
- 关键逻辑：行内注释解释 WHY 而非 WHAT
- 语言：使用中文注释
/**
* 杀戮光环（KillAura）检测服务 — V4.0 反作弊扩展模块
*
* 检测原理：
* 1. 攻击目标切换频率检测 — 追踪每个玩家的攻击目标列表，如果在3秒窗口内切换超过3个不同目标
* 2. 攻击角度一致性检测 — 连续攻击的角度偏差小于5度时，表明存在自动瞄准（Aimbot）
*
* 配置开关：serverguard.security.super-evolution.anti-kill-aura
*/
@Service
public class AntiKillAuraService {
// ...
}
代码组织
// 1. Package 声明
// 2. Import 语句（按字母排序，静态导入在后）
// 3. 类 JavaDoc
// 4. @Service 或其他注解
// 5. 类声明
// 6. 常量字段
// 7. 配置注入字段
// 8. 数据追踪字段（ConcurrentHashMap, AtomicLong）
// 9. 构造函数（无参 + @Autowired）
// 10. 公共分析方法
// 11. 私有辅助方法
// 12. 内部类（BehaviorRecord, DetectionResult）
Git 提交规范
- 使用中文 commit message
- 格式：
{类型}: {简短描述} - 类型：新增、修复、重构、文档、测试、优化
- 频繁提交，每个有意义的改动单独提交
示例：
新增: AntiAutoCrystal 末影水晶自动化检测模块
修复: Reach 检测误判穿墙攻击时的距离计算错误
重构: 统一所有安全模块的 DetectionResult 返回类型
构建系统
Maven 配置
项目使用 Apache Maven 3.9.6（bundled），配置文件 pom.xml。
关键依赖
<dependencies>
<!-- Spring Boot 核心 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-websocket</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-mail</artifactId>
</dependency>
<!-- Spring Shell CLI -->
<dependency>
<groupId>org.springframework.shell</groupId>
<artifactId>spring-shell-starter</artifactId>
<version>3.1.3</version>
</dependency>
<!-- PaperMC API -->
<dependency>
<groupId>io.papermc.paper</groupId>
<artifactId>paper-api</artifactId>
<version>1.21.1-R0.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
<!-- 机器学习 -->
<dependency>
<groupId>com.github.haifengl</groupId>
<artifactId>smile-core</artifactId>
<version>2.6.0</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-math3</artifactId>
<version>3.6.1</version>
</dependency>
<!-- YAML 配置 -->
<dependency>
<groupId>org.yaml</groupId>
<artifactId>snakeyaml</artifactId>
<version>2.2</version>
</dependency>
<!-- JSON (内嵌) -->
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
</dependency>
</dependencies>
构建命令速查
# 编译（不运行测试）
./apache-maven-3.9.6/bin/mvn compile
# 编译 + 运行全量测试
./apache-maven-3.9.6/bin/mvn test
# 打包（跳过测试）
./apache-maven-3.9.6/bin/mvn package -DskipTests
# 打包 + 运行测试
./apache-maven-3.9.6/bin/mvn package
# 清理构建产物
./apache-maven-3.9.6/bin/mvn clean
# 清理 + 完整重新构建
./apache-maven-3.9.6/bin/mvn clean package
构建产物
target/
├── serverguard-4.0.0.jar # 可执行 JAR（Spring Boot Fat JAR）
├── classes/ # 编译后的 .class 文件
├── test-classes/ # 测试编译产物
├── generated-sources/ # 注解处理器生成
└── surefire-reports/ # 测试报告
部署产物说明
serverguard-4.0.0.jar是 Spring Boot 可执行 JAR，包含所有依赖- 同时作为 Paper 插件使用（复制到
plugins/目录） - Plugin 模式下，AluerPlugin 作为 Paper 插件启动，但不启动嵌入的 Spring Boot（由外部引擎独立运行）