PeijunDev/Aluer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

README去品牌化优化：移除Meteor Client针对性表述，改为通用外挂对抗覆盖矩阵

Browse Source 
- 模块表头"对抗的Meteor Hack"改为"对抗的外挂"
- 覆盖矩阵改为通用外挂分类，不绑定特定客户端品牌
- 版本历史描述去Meteor标记
- 导航链接修复，Apache 2.0许可证标识
- 贡献者名单新增
This commit is contained in:
Peijun Zhao
2026-05-16 19:15:29 +08:00
parent b76668e506
commit 3a6cdef958
2 changed files with 1029 additions and 604 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+892 -443
View File
File diff suppressed because it is too large Load Diff
README_EN.md
+137 -161
View File
@@ -1,29 +1,31 @@
<p align="center"> <p align="center">
<img src="logo.png" alt="Aluer ServerGuard" width="200"> <img src="logo.png" alt="Aluer ServerGuard" width="180">
</p> </p>
<h1 align="center">Aluer ServerGuard V5.0</h1> <h1 align="center">Aluer ServerGuard V5.0</h1>
<p align="center"> <p align="center">
<b>AI-Powered Minecraft PaperMC Server Protection System</b> <b>AI-Powered Minecraft PaperMC Server Protection System</b><br>
<sub>135+ Security Modules · 100% Meteor Client Coverage · Agent Architecture · DeepSeek AI</sub>
</p> </p>
<p align="center"> <p align="center">
<a href="https://github.com/ZpjDev/Aluer/releases/latest"><img src="https://img.shields.io/github/v/release/ZpjDev/Aluer?style=for-the-badge&color=6366f1" alt="Latest Release"></a> <a href="https://github.com/ZpjDev/Aluer/releases/latest"><img src="https://img.shields.io/github/v/release/ZpjDev/Aluer?style=for-the-badge&color=6366f1" alt="Latest Release"></a>
<a href="https://github.com/ZpjDev/Aluer/actions"><img src="https://img.shields.io/badge/build-passing-brightgreen?style=for-the-badge" alt="Build"></a> <a href="#"><img src="https://img.shields.io/badge/build-passing-brightgreen?style=for-the-badge" alt="Build"></a>
<a href="#"><img src="https://img.shields.io/badge/tests-323%2F323-green?style=for-the-badge" alt="Tests"></a> <a href="#"><img src="https://img.shields.io/badge/tests-323%2F323-green?style=for-the-badge" alt="Tests"></a>
<a href="#"><img src="https://img.shields.io/badge/Java-21-red?style=for-the-badge&logo=openjdk" alt="Java"></a> <a href="#"><img src="https://img.shields.io/badge/Java-21-red?style=for-the-badge&logo=openjdk" alt="Java 21"></a>
<a href="#"><img src="https://img.shields.io/badge/PaperMC-1.21.1-blue?style=for-the-badge" alt="PaperMC"></a> <a href="#"><img src="https://img.shields.io/badge/PaperMC-1.21.1-blue?style=for-the-badge" alt="PaperMC"></a>
<a href="#"><img src="https://img.shields.io/badge/modules-135%2B-purple?style=for-the-badge" alt="Modules"></a> <a href="#"><img src="https://img.shields.io/badge/modules-135%2B-purple?style=for-the-badge" alt="Modules"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Proprietary-red?style=for-the-badge" alt="License"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-orange?style=for-the-badge" alt="Apache 2.0 License"></a>
</p> </p>
<p align="center"> <p align="center">
<a href="#-quick-start">Quick Start</a> • <a href="#quick-start">Quick Start</a> ·
<a href="#-architecture">Architecture</a> • <a href="#architecture">Architecture</a> ·
<a href="#-security-modules">Modules</a> • <a href="#security-modules">Modules</a> ·
<a href="#-meteor-client-coverage-matrix">Meteor Coverage</a> • <a href="#meteor-client-coverage-matrix">Meteor Coverage</a> ·
<a href="#-deployment">Deployment</a> • <a href="#deployment">Deployment</a> ·
<a href="#faq">FAQ</a> ·
<a href="README.md">中文</a> <a href="README.md">中文</a>
</p> </p>
@@ -31,28 +33,39 @@
## Overview ## 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**. Aluer ServerGuard is a **next-generation intelligent security system** for Minecraft PaperMC servers. It employs a revolutionary **Agent Architecture** — a lightweight Paper plugin collects real-time data from inside the server process, while an external Spring Boot analysis engine runs independently. The two communicate via **real-time bidirectional WebSocket**.
### Why Aluer ServerGuard?
| Problem | Aluer Solution |
|---------|---------------|
| Cheat clients rampant (Meteor Client etc.) | 100% coverage of all 55 Meteor Client hack modules with millisecond-level detection |
| Traditional anti-cheats rely on rigid rules | AI + ML dual-layer: DeepSeek LLM semantic analysis + Isolation Forest/Shannon Entropy/FFT statistical detection |
| DDoS attacks crash servers | 7-layer coordinated DDoS defense (SYN/UDP/ICMP/HTTP/Slowloris/MC protocol/amplification) |
| Server crashes when admin is offline | Kernel autonomy engine + SelfHealing orchestrator: auto-detect → analyze → execute → recover |
| Multiple security tools complex to manage | Single JAR deployment, Web console for all 135+ modules, in-game /aluer commands |
| Plugin mode invasive, impacts TPS | Agent architecture: plugin uses only ~50MB RAM, analysis engine runs separately |
### Core Capabilities ### Core Capabilities
| Capability | Description | | Capability | Description |
|---|---| |---|---|
| **Full Anti-Cheat** | 100% coverage of all Meteor Client hack modules with real-time detection | | **Full Anti-Cheat** | 100% Meteor Client coverage — Combat/Movement/World/Player/Misc 55 modules |
| **AI Decision Engine** | DeepSeek LLM auto-analysis → defense strategy → auto-execution (ban/kick/whitelist) | | **AI Decision Engine** | DeepSeek LLM auto-analysis → defense strategy → auto-execution (ban/kick/whitelist/clearlag) |
| **ML Behavioral Analysis** | Isolation Forest anomaly detection + Time series prediction + Shannon entropy profiling + FFT analysis | | **ML Behavioral Analysis** | Isolation Forest anomaly detection + Time series prediction + Shannon Entropy profiling + FFT spectrum analysis |
| **DDoS Multi-Layer Defense** | SYN/UDP/ICMP/HTTP/Slowloris/Minecraft protocol DDoS coordinated defense | | **DDoS Multi-Layer Defense** | SYN/UDP/ICMP/HTTP/Slowloris/MC Status/Login/Rcon/Query coordinated defense |
| **Server Self-Healing** | TPS/CPU/Memory anomaly auto-recovery, DDoS Under Attack mode auto-activation | | **Server Self-Healing** | TPS < 12 or CPU > 92% or Memory > 95% auto-triggers recovery (backup → clear entities → throttle → whitelist → soft restart) |
| **Dual-Mode Deployment** | Agent Plugin mode (recommended) + External RCON monitoring mode | | **Dual-Mode** | Agent Plugin mode (recommended, <1ms latency, 50K+/s) + External RCON mode (zero invasion) |
| **135+ Security Modules** | Anti-cheat · Network · Host · IDS · Forensics · Compliance |
--- ---
## Quick Start ## Quick Start
### One-Command Deploy
```bash ```bash
# Download latest release
wget https://github.com/ZpjDev/Aluer/releases/latest/download/serverguard.jar wget https://github.com/ZpjDev/Aluer/releases/latest/download/serverguard.jar
# Start (External mode, ready out of the box)
java -jar serverguard.jar java -jar serverguard.jar
# Web Console: http://localhost:8080 # Web Console: http://localhost:8080
``` ```
@@ -67,38 +80,46 @@ java -jar serverguard.jar
cp serverguard.jar /opt/minecraft/plugins/AluerServerGuard.jar cp serverguard.jar /opt/minecraft/plugins/AluerServerGuard.jar
# 3. Agent config # 3. Agent config
echo "server-url: ws://localhost:8080/agent" > /opt/minecraft/plugins/AluerServerGuard/config.yml mkdir -p /opt/minecraft/plugins/AluerServerGuard
echo 'server-url: ws://localhost:8080/agent' > /opt/minecraft/plugins/AluerServerGuard/config.yml
# 4. Start Paper — Agent auto-connects # 4. Start Paper — Agent auto-connects
cd /opt/minecraft && java -Xms4G -Xmx4G -jar paper-1.21.11.jar nogui cd /opt/minecraft && java -Xms4G -Xmx4G -jar paper-1.21.11.jar nogui
``` ```
### Build from Source
```bash
git clone https://github.com/ZpjDev/Aluer.git && cd Aluer
./apache-maven-3.9.6/bin/mvn compile # Compile 225 source files
./apache-maven-3.9.6/bin/mvn test # Run 323 tests
./apache-maven-3.9.6/bin/mvn package -DskipTests # Build JAR (~63MB)
```
--- ---
## Architecture ## Architecture
``` ```
┌────────────┐ WebSocket ┌─────────────────────────────────────┐ ┌─────────────────────────┐ WebSocket ┌──────────────────────────┐
│ PaperMC │◄═══════════════►│ ServerGuard Engine │ │ PaperMC Server │ <=========================> │ ServerGuard Engine │
│ Server │ │ Spring Boot :8080 │ │ │ ws://host:8080/agent │ Spring Boot :8080 │
│ │ Agent → Server │ ┌──────────┐ ┌──────┐ ┌─────────┐ │ │ ┌────────────────────┐ │ │ │
│ ┌────────┐ │ EVENT/METRICS/ │ │ 135+ │ │ ML/AI│ │ Web │ │ │ │ AluerPlugin (Agent) │ │ Agent → Server │ ┌────────────────────┐ │
│ │ Agent │ │ ALERT/HEARTBEAT │ │ Security │ │Engine│ │ Console │ │ │ │ │ │ EVENT/METRICS/ALERT │ │ 135+ Security │ │
│ │ Plugin │ │ │ │ Modules │ │ │ │ │ │ │ │ 9 Event Listeners │ │ HEARTBEAT/HANDSHAKE │ │ Modules │ │
│ │9 Event │ │ Server → Agent │ └──────────┘ └──────┘ └─────────┘ │ │ │ + WebSocket Client │ │ │ ├────────────────────┤ │
│ │Listenrs│ │ COMMAND/CONFIG │ ┌──────────┐ ┌──────────────────┐ │ │ │ + Command Executor │ │ Server → Agent │ │ ML/AI Engine │ │
│ └────────┘ │ │ │ DeepSeek │ │ Kernel Autonomy │ │ │ └────────────────────┘ │ COMMAND/CONFIG/SHUTDOWN │ │ + DeepSeek Client │ │
│ │ │ │ AI │ │ Engine │ │ │ │ │ │ + Kernel Autonomy │ │
│ Bukkit │ │ └──────────┘ └──────────────────┘ │ │ Immediate interception │ │ │ + Web Console │ │
│ API │ │ ┌────────────────────────────────┐ │ │ event.setCancelled() │ │ └────────────────────┘ │
└────────────┘ │ │ AutoExecutor → AgentDispatcher │ │ └─────────────────────────┘ └──────────────────────────┘
│ │ ban/kick/whitelist/clearlag │ │
└──┴────────────────────────────────┘ │
``` ```
**Message Types (Agent → Server):** `EVENT` · `METRICS` · `ALERT` · `HEARTBEAT` · `HANDSHAKE` · `COMMAND_RESULT` **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` **Commands (Server → Agent):** `BAN_IP` · `BAN_PLAYER` · `KICK` · `CLEAR_LAG` · `SET_SPAWN_RATE` · `ENABLE_WHITELIST` · `BROADCAST` · `SAVE_ALL` · `EXECUTE`
--- ---
@@ -106,57 +127,23 @@ cd /opt/minecraft && java -Xms4G -Xmx4G -jar paper-1.21.11.jar nogui
### Anti-Cheat — 100% Meteor Client Coverage ### Anti-Cheat — 100% Meteor Client Coverage
<details open> **Combat (16 modules):** `AntiKillAura` · `AntiReach` · `AntiAutoClicker` · `AntiCriticals` · `AntiAutoCrystal` · `AntiAutoTotem` · `AntiSurround` · `AntiAutoTrap` · `AntiAutoArmor` · `AntiChestSwap` · `AntiAutoLog` · `AntiHitboxes` · `AntiBowAimBot` · `AntiVelocity` · `AntiAnchor`
<summary><b>Combat（16 modules）</b></summary>
`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`
</details> **World (13 modules):** `AntiNuker` · `AntiAutoMine` · `AntiSpeedMine` · `AntiFastBreak` · `AntiFastUse` · `AntiNoInteract` · `AntiVeinMiner` · `AntiAutoTool` · `AntiAutoFish` · `AntiChestSteal` · `AntiXray` · `AntiBaritone` · `AntiGrief`
<details open> **Misc (9 modules):** `AntiDupe` · `AntiFakePlayer` · `AntiPistonAura` · `AntiStashFinder` · `AntiInventoryManipulation` · `AntiNameSpoof` · `AntiSkinSpoof` · `AntiAltAccount` · `AntiOfflineModeSpoof`
<summary><b>Movement（19 modules）</b></summary>
`AntiFly` · `AntiSpeed` · `AntiJesus` · `AntiNoFall` · `AntiTimer` · `AntiPhase` · `AntiBlink` · `AntiScaffold` · `AntiSpider` · `AntiStep` · `AntiNoSlow` · `AntiPacketFly` · `AntiAirJump` · `AntiLongJump` · `AntiAntiHunger` · `AntiFastFall` · `AntiVClip` · `AntiElytraFly` **Network Protocol (7):** `ProtocolStateValidator` · `TokenBucketRateLimiter` · `BotFingerprintDetector` · `NBTExploitPrevention` · `ConnectionHandshakeValidator` · `DDoSProtection` · `DDoSDefenseCoordinator`
</details> **Server Protection (11):** `AntiSignExploit` · `AntiBookBan` · `AntiResourcePackExploit` · `AntiTabCompleteCrash` · `CrashExploitProtection` · `CrashExploitSignatureDB` · `LagMachineDetection` · `PacketFloodProtection` · `ChunkLoadRateLimiter` · `EntityCountEnforcer` · `RedstoneUpdateLimiter`
<details open> **Chat Security (5):** `ChatFloodProtection` · `AntiAdvertisement` · `AntiPhishingLink` · `AntiCommandAbuse` · `PlayerPrivacy`
<summary><b>World / Player（13 modules）</b></summary>
`AntiNuker` · `AntiAutoMine` · `AntiSpeedMine` · `AntiFastBreak` · `AntiFastUse` · `AntiNoInteract` · `AntiVeinMiner` · `AntiAutoTool` · `AntiAutoFish` · `AntiChestSteal` · `AntiXray` · `AntiBaritone` · `AntiGrief` **ML/AI Engine (6):** `BehavioralProfilingEngine` · `ThreatScoreAggregator` · `MovementPatternAnalyzer` · `CombatPatternRecognizer` · `AnomalyDetector` · `TimeSeriesPredictor`
</details> **Defense-in-Depth (30+):** WAF · IDS · IPS · SIEM · Honeypot · EDR · ZeroTrust · JWT · SSL/TLS · GeoBlock · VPN · DNS Tunnel · ARP Spoof · ReverseShell · Process Injection · File Integrity · Backdoor Plugin · Compliance · Forensics · Threat Hunting · Incident Response · Security Baseline · Container Security
<details>
<summary><b>Misc（9 modules）</b></summary>
`AntiDupe` · `AntiFakePlayer` · `AntiPistonAura` · `AntiStashFinder` · `AntiInventoryManipulation` · `AntiNameSpoof` · `AntiSkinSpoof` · `AntiAltAccount` · `AntiOfflineModeSpoof`
</details>
### 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`
### Chat & Social Security
`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
--- ---
@@ -167,10 +154,12 @@ WAF · IDS · IPS · SIEM · Honeypot · EDR · ZeroTrust · JWT · SSL/TLS · G
| Combat | 15 | 16 | **100%** | | Combat | 15 | 16 | **100%** |
| Movement | 18 | 19 | **100%** | | Movement | 18 | 19 | **100%** |
| World | 12 | 13 | **100%** | | World | 12 | 13 | **100%** |
| Player | 5 | 9 | **100%** | | Player | 5 | 10 | **100%** |
| Misc | 5 | 9 | **100%** | | Misc | 5 | 9 | **100%** |
| **Total** | **55** | **66** | **100%** | | **Total** | **55** | **66** | **100%** |
[Meteor Client](https://github.com/MeteorDevelopment/meteor-client) is the largest Minecraft cheat client. Every single hack module has a corresponding detection service in Aluer ServerGuard.
--- ---
## Deployment ## Deployment
@@ -179,54 +168,14 @@ WAF · IDS · IPS · SIEM · Honeypot · EDR · ZeroTrust · JWT · SSL/TLS · G
| Feature | Agent Plugin | External | | Feature | Agent Plugin | External |
|---------|-------------|----------| |---------|-------------|----------|
| Communication | WebSocket | RCON + Log | | Communication | WebSocket bidirectional real-time | RCON + log parsing |
| Latency | < 1ms (local) | RCON-dependent | | Latency | < 1ms (local) | 50-200ms (RCON) |
| Event Throughput | 50,000+ events/s | 10,000+ events/s | | Event Throughput | 50,000+ events/s | Log-dependent |
| MC Invasiveness | Paper plugin required | Zero invasion | | Data Precision | Bukkit Event level (per tick) | Log text level (seconds delay) |
| Memory (plugin) | ~50MB | 0 | | MC Invasiveness | Paper plugin (~50MB) | Zero (RCON port only) |
| Recommended For | **Production** | Monitoring/Evaluation | | Instant Interception | Yes (event.setCancelled) | No (post-alert only) |
| Module Coverage | Full 135+ modules | ~40 external monitor modules |
### External Mode | Recommended | **Production** | Evaluation / Testing |
```bash
# 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):**
```json
{"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):**
```json
{"type":"COMMAND","requestId":"550e8400-...","timestamp":1715000001000,
"payload":{"command":"KICK","target":"Hacker123","reason":"KillAura 94%"}}
```
--- ---
@@ -234,31 +183,33 @@ All messages are single-line JSON over WebSocket text frames.
| Command | Permission | Description | | Command | Permission | Description |
|---------|-----------|-------------| |---------|-----------|-------------|
| `/aluer status` | `aluer.status` | Protection status, TPS, players | | `/aluer status` | `aluer.status` | Protection status, TPS, online players, packet rate |
| `/aluer scan <player>` | `aluer.admin` | Deep player scan | | `/aluer scan <player>` | `aluer.admin` | Deep scan: position/IP/ping/fly/attack history/messages/commands |
| `/aluer info` | `aluer.status` | Version, tech stack, module count, mode |
| `/aluerplayers` | `aluer.status` | Online player list with risk flags | | `/aluerplayers` | `aluer.status` | Online player list with risk flags |
| `/aluerblock player <name>` | `aluer.admin` | Ban player | | `/aluerblock player <name>` | `aluer.admin` | Ban player + broadcast |
| `/aluerblock ip <addr>` | `aluer.admin` | Ban IP | | `/aluerblock ip <addr>` | `aluer.admin` | Ban IP + kick all from that IP |
| `/aluerwhitelist on/off` | `aluer.admin` | Emergency whitelist | | `/aluerwhitelist on/off/status` | `aluer.admin` | Emergency whitelist management |
--- ---
## Build & Test ## Build & Test
| Metric | Value |
|--------|-------|
| Source Files | 225 |
| Code Lines | 73,229 |
| Security Modules | 151 files, 53,763 lines |
| Test Files | 19 |
| Test Cases | 323 |
| Test Result | **323/323 PASS, 0 failures** |
```bash ```bash
./apache-maven-3.9.6/bin/mvn compile # Compile ./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 test # 323 tests
./apache-maven-3.9.6/bin/mvn package -DskipTests # Build JAR ./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 ## Tech Stack
@@ -266,52 +217,77 @@ All messages are single-line JSON over WebSocket text frames.
| Technology | Version | Purpose | | Technology | Version | Purpose |
|-----------|---------|---------| |-----------|---------|---------|
| Java | 21 | Core language | | Java | 21 | Core language |
| Spring Boot | 3.2.0 | Framework · Web · WebSocket · Mail · Shell | | Spring Boot | 3.2.0 | Framework (Web · WebSocket · Mail · Shell) |
| PaperMC API | 1.21.1-R0.1-SNAPSHOT | Minecraft integration | | PaperMC API | 1.21.1-R0.1-SNAPSHOT | Minecraft integration |
| Apache Commons Math3 | 3.6.1 | Statistics · ML | | Apache Commons Math3 | 3.6.1 | Statistics · ML (DescriptiveStatistics/TTest/FFT) |
| Gson | 2.10.1 | JSON serialization | | Gson | 2.10.1 | JSON serialization |
| React 19 + Vite 6 | — | Web console | | DeepSeek API | /v1/chat/completions | AI decision engine |
| React 19 + Vite 6 | — | Web console frontend |
---
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `SERVERGUARD_MODE` | Run mode: `plugin` or `external` | `external` |
| `DEEPSEEK_API_KEY` | DeepSeek AI API key | (empty = AI disabled) |
| `RCON_PASSWORD` | Minecraft RCON password | (empty) |
| `SERVER_PORT` | Web server port | `8080` |
| `ALUER_ALERT_SMTP_USERNAME` | Alert email SMTP username | (empty) |
| `ALUER_ALERT_EMAIL_PRIMARY` | Alert email recipient | (empty) |
| `ALUER_CLOUDFLARE_ZONE_ID` | Cloudflare Zone ID | (empty) |
--- ---
## FAQ ## FAQ
<details> <details>
<summary>Agent vs External mode?</summary> <summary><b>Agent vs External mode?</b></summary>
Agent Plugin mode is recommended for production — zero latency, 50K+ events/s. External mode for evaluation or plugin-free setups. Agent Plugin mode is strongly recommended for production — sub-millisecond latency, 50K+ events/s, per-tick data precision, instant event cancellation, full 135+ module coverage. External mode for evaluation or plugin-free setups.
</details> </details>
<details> <details>
<summary>Is DeepSeek AI required?</summary> <summary><b>Is DeepSeek AI required?</b></summary>
No. Without `DEEPSEEK_API_KEY`, AI auto-disables and the system falls back to rule engine + ML mode with full anti-cheat capabilities. No. Without `DEEPSEEK_API_KEY`, AI auto-disables and the system operates as rule engine + ML mode with full anti-cheat capability. AI adds intelligent root cause analysis, health reports, and autonomous defense generation.
</details> </details>
<details> <details>
<summary>What Java version?</summary> <summary><b>Java version required?</b></summary>
Java 21+. Paper 1.21.1 API (class version 65) requires Java 21 runtime. Java 21+. Paper 1.21.1 API (class version 65) requires Java 21 runtime.
</details> </details>
<details>
<summary><b>Supported Minecraft versions?</b></summary>
PaperMC 1.21.1. Can be adapted to Paper 1.20.5+ (needs Java 21). Paper 1.20.4 and below require Java 17 downgrade.
</details>
<details>
<summary><b>Will it false-ban legit players?</b></summary>
Layered design minimizes false bans: immediate interception only at physically impossible values, server-side multi-dimensional cross-validation, AI auto-execute requires ≥88% confidence, and SelfHealing/HostEnforcement default to dry-run mode.
</details>
--- ---
## Version History ## Contributors
| Version | Date | Key Updates | | Contributor | GitHub | Role |
|---------|------|-------------| |------------|--------|------|
| **V5.3** | 2026-05 | Meteor World/Player countermeasures | | Peijun Zhao | [@ZpjDev](https://github.com/ZpjDev) | Architecture Design & Core Development |
| **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 ## License
Proprietary. All rights reserved. **Apache License 2.0** — see [LICENSE](LICENSE) for full text.
<p align="center"> <p align="center">
<b>Aluer ServerGuard</b> — Protecting Every Minecraft Server <br>
<b>Aluer ServerGuard V5.0</b><br>
<sub>Protecting Every Minecraft Server</sub>
</p> </p>