Files

T

Peijun Zhao b76668e506 README 全面 GitHub 优化：badges、logo、目录、快速开始、折叠面板、FAQ

- 新增 GitHub badges（Release/Test/Java/PaperMC/模块数/License）
- logo 居中展示 + 导航目录链接
- 快速开始置顶（一键部署 + Agent Plugin 模式）
- 安全模块改用折叠面板，简洁可读
- Meteor Client 100% 覆盖矩阵
- 新增 FAQ（Agent vs External、AI 是否必需、Java 版本）
- 中英文 README 同步完整更新

2026-05-16 18:41:25 +08:00

12 KiB

Raw Blame History

Aluer ServerGuard V5.0

AI-Powered Minecraft PaperMC Server Protection System

Quick Start • Architecture • Modules • Meteor Coverage • Deployment • 中文

Overview

Aluer ServerGuard is a next-generation intelligent security system for Minecraft PaperMC servers. It employs a revolutionary Agent Architecture — a lightweight Paper plugin collects data from inside the server process, while an external Spring Boot analysis engine runs independently. The two communicate via real-time bidirectional WebSocket.

Core Capabilities

Capability	Description
Full Anti-Cheat	100% coverage of all Meteor Client hack modules with real-time detection
AI Decision Engine	DeepSeek LLM auto-analysis → defense strategy → auto-execution (ban/kick/whitelist)
ML Behavioral Analysis	Isolation Forest anomaly detection + Time series prediction + Shannon entropy profiling + FFT analysis
DDoS Multi-Layer Defense	SYN/UDP/ICMP/HTTP/Slowloris/Minecraft protocol DDoS coordinated defense
Server Self-Healing	TPS/CPU/Memory anomaly auto-recovery, DDoS Under Attack mode auto-activation
Dual-Mode Deployment	Agent Plugin mode (recommended) + External RCON monitoring mode
135+ Security Modules	Anti-cheat · Network · Host · IDS · Forensics · Compliance

Quick Start

One-Command Deploy

wget https://github.com/ZpjDev/Aluer/releases/latest/download/serverguard.jar
java -jar serverguard.jar
# Web Console: http://localhost:8080

Agent Plugin Mode (Production)

# 1. Start ServerGuard engine
java -jar serverguard.jar

# 2. Copy JAR to Paper plugins/
cp serverguard.jar /opt/minecraft/plugins/AluerServerGuard.jar

# 3. Agent config
echo "server-url: ws://localhost:8080/agent" > /opt/minecraft/plugins/AluerServerGuard/config.yml

# 4. Start Paper — Agent auto-connects
cd /opt/minecraft && java -Xms4G -Xmx4G -jar paper-1.21.11.jar nogui

Architecture

  ┌────────────┐    WebSocket     ┌─────────────────────────────────────┐
  │  PaperMC   │◄═══════════════►│        ServerGuard Engine            │
  │  Server    │                  │      Spring Boot :8080               │
  │            │  Agent → Server  │  ┌──────────┐ ┌──────┐ ┌─────────┐ │
  │ ┌────────┐ │  EVENT/METRICS/  │  │ 135+     │ │ ML/AI│ │ Web     │ │
  │ │ Agent  │ │  ALERT/HEARTBEAT │  │ Security │ │Engine│ │ Console │ │
  │ │ Plugin │ │                  │  │ Modules  │ │      │ │         │ │
  │ │9 Event │ │  Server → Agent  │  └──────────┘ └──────┘ └─────────┘ │
  │ │Listenrs│ │  COMMAND/CONFIG  │  ┌──────────┐ ┌──────────────────┐ │
  │ └────────┘ │                  │  │ DeepSeek │ │ Kernel Autonomy  │ │
  │            │                  │  │ AI       │ │ Engine           │ │
  │  Bukkit    │                  │  └──────────┘ └──────────────────┘ │
  │  API       │                  │  ┌────────────────────────────────┐ │
  └────────────┘                  │  │ AutoExecutor → AgentDispatcher │ │
                                  │  │ ban/kick/whitelist/clearlag    │ │
                                  └──┴────────────────────────────────┘ │

Message Types (Agent → Server): EVENT · METRICS · ALERT · HEARTBEAT · HANDSHAKE · COMMAND_RESULT

Command Types (Server → Agent): BAN_IP · BAN_PLAYER · KICK · CLEAR_LAG · SET_SPAWN_RATE · ENABLE_WHITELIST · BROADCAST · SAVE_ALL · EXECUTE

Security Modules

Anti-Cheat — 100% Meteor Client Coverage

Combat（16 modules）

AntiKillAura · AntiReach · AntiAutoClicker · AntiCriticals · AntiAutoCrystal · AntiAutoTotem · AntiSurround · AntiAutoTrap · AntiAutoArmor · AntiChestSwap · AntiAutoLog · AntiHitboxes · AntiBowAimBot · AntiVelocity · AntiAnchor

Movement（19 modules）

AntiFly · AntiSpeed · AntiJesus · AntiNoFall · AntiTimer · AntiPhase · AntiBlink · AntiScaffold · AntiSpider · AntiStep · AntiNoSlow · AntiPacketFly · AntiAirJump · AntiLongJump · AntiAntiHunger · AntiFastFall · AntiVClip · AntiElytraFly

World / Player（13 modules）

AntiNuker · AntiAutoMine · AntiSpeedMine · AntiFastBreak · AntiFastUse · AntiNoInteract · AntiVeinMiner · AntiAutoTool · AntiAutoFish · AntiChestSteal · AntiXray · AntiBaritone · AntiGrief

Misc（9 modules）

AntiDupe · AntiFakePlayer · AntiPistonAura · AntiStashFinder · AntiInventoryManipulation · AntiNameSpoof · AntiSkinSpoof · AntiAltAccount · AntiOfflineModeSpoof

Server Exploit Protection

AntiSignExploit · AntiBookBan · AntiResourcePackExploit · AntiTabCompleteCrash · CrashExploitProtection · CrashExploitSignatureDB · LagMachineDetection · PacketFloodProtection

Network Protocol Security

ProtocolStateValidator · TokenBucketRateLimiter · BotFingerprintDetector · NBTExploitPrevention · ConnectionHandshakeValidator · DDoSProtection · DDoSDefenseCoordinator

Server Performance Protection

ChunkLoadRateLimiter · EntityCountEnforcer · RedstoneUpdateLimiter

ChatFloodProtection · AntiAdvertisement · AntiPhishingLink · AntiCommandAbuse · PlayerPrivacy

ML/AI Behavioral Analysis

BehavioralProfilingEngine (5D features · Shannon entropy · Z-score · 6 profiles) · ThreatScoreAggregator (exponential decay · 4-tier escalation · EMA) · MovementPatternAnalyzer (FFT · rotation smoothness · saccadic analysis) · CombatPatternRecognizer (CPS variance · multi-target entropy · hit ratio) · AnomalyDetector (Isolation Forest) · TimeSeriesPredictor

Defense-in-Depth & Host Security (30+ modules)

WAF · IDS · IPS · SIEM · Honeypot · EDR · ZeroTrust · JWT · SSL/TLS · GeoBlock · VPN Detection · DNS Tunnel · ARP Spoof · ReverseShell · Process Injection · File Integrity · Backdoor Plugin Scanner · Compliance · Forensics · Threat Hunting · Incident Response · Security Baseline · Container Security

Meteor Client Coverage Matrix

Category	Meteor Hacks	Aluer Counter-Modules	Coverage
Combat	15	16	100%
Movement	18	19	100%
World	12	13	100%
Player	5	9	100%
Misc	5	9	100%
Total	55	66	100%

Deployment

Mode Comparison

Feature	Agent Plugin	External
Communication	WebSocket	RCON + Log
Latency	< 1ms (local)	RCON-dependent
Event Throughput	50,000+ events/s	10,000+ events/s
MC Invasiveness	Paper plugin required	Zero invasion
Memory (plugin)	~50MB	0
Recommended For	Production	Monitoring/Evaluation

External Mode

# Enable RCON in server.properties
enable-rcon=true
rcon.port=25575
rcon.password=STRONG_PASSWORD

# Start ServerGuard
java -jar serverguard.jar

Environment Variables

Variable	Description	Default
`SERVERGUARD_MODE`	Run mode (plugin/external)	`external`
`DEEPSEEK_API_KEY`	DeepSeek AI API key	(empty = disabled)
`DEEPSEEK_BASE_URL`	DeepSeek API URL	`https://api.deepseek.com`
`DEEPSEEK_MODEL`	DeepSeek model name	`deepseek-chat`
`RCON_PASSWORD`	Minecraft RCON password	(empty)

WebSocket Protocol

All messages are single-line JSON over WebSocket text frames.

Agent → Server (event):

{"type":"EVENT","agentId":"survival-01","timestamp":1715000000000,
 "payload":{"eventType":"PLAYER_MOVE","playerName":"Steve","x":100.5,"y":64.0,"z":200.3}}

Server → Agent (command):

{"type":"COMMAND","requestId":"550e8400-...","timestamp":1715000001000,
 "payload":{"command":"KICK","target":"Hacker123","reason":"KillAura 94%"}}

In-Game Commands

Command	Permission	Description
`/aluer status`	`aluer.status`	Protection status, TPS, players
`/aluer scan <player>`	`aluer.admin`	Deep player scan
`/aluerplayers`	`aluer.status`	Online player list with risk flags
`/aluerblock player <name>`	`aluer.admin`	Ban player
`/aluerblock ip <addr>`	`aluer.admin`	Ban IP
`/aluerwhitelist on/off`	`aluer.admin`	Emergency whitelist

Build & Test

./apache-maven-3.9.6/bin/mvn compile          # Compile
./apache-maven-3.9.6/bin/mvn test             # 323 tests
./apache-maven-3.9.6/bin/mvn package -DskipTests  # Build JAR

Metric	Value
Source Files	225
Code Lines	73,229
Test Files	19
Test Cases	323
Test Result	323/323 PASS, 0 failures

Tech Stack

Technology	Version	Purpose
Java	21	Core language
Spring Boot	3.2.0	Framework · Web · WebSocket · Mail · Shell
PaperMC API	1.21.1-R0.1-SNAPSHOT	Minecraft integration
Apache Commons Math3	3.6.1	Statistics · ML
Gson	2.10.1	JSON serialization
React 19 + Vite 6	—	Web console

FAQ

Agent vs External mode?

Agent Plugin mode is recommended for production — zero latency, 50K+ events/s. External mode for evaluation or plugin-free setups.

Is DeepSeek AI required?

No. Without DEEPSEEK_API_KEY, AI auto-disables and the system falls back to rule engine + ML mode with full anti-cheat capabilities.

What Java version?

Java 21+. Paper 1.21.1 API (class version 65) requires Java 21 runtime.

Version History

Version	Date	Key Updates
V5.3	2026-05	Meteor World/Player countermeasures
V5.2	2026-05	Meteor Movement countermeasures
V5.1	2026-05	Meteor Combat countermeasures
V5.0	2026-04	Agent WebSocket architecture · AI/ML engine
V4.0	2026-03	Core anti-cheat modules

License

Aluer ServerGuard — Protecting Every Minecraft Server

12 KiB Raw Blame History Unescape Escape