Aluer/docs/USER_MANUAL.md

# Aluer 服务器安全防护系统 - 用户手册

## 目录
1. [系统简介](#系统简介)
2. [功能特性](#功能特性)
3. [安装部署](#安装部署)
4. [快速开始](#快速开始)
5. [AI协作终端](#ai协作终端)
6. [命令参考](#命令参考)
7. [配置说明](#配置说明)
8. [预警系统](#预警系统)
9. [常见问题](#常见问题)

---

## 系统简介

Aluer 是一款专为 Minecraft PaperMC 服务器设计的安全防护系统，集成了 AI 智能决策、DDoS 防护、入侵检测等多种安全功能。系统采用 Java + Spring Boot 开发，支持通过终端命令行或自然语言与系统交互。

### 核心特性
- 🤖 **AI 智能决策** - 基于 DeepSeek API 的智能威胁分析
- 🛡️ **多层防御** - DDoS防护、防火墙、入侵检测、VPN检测
- 📧 **邮件预警** - 实时告警通知管理员
- 🔄 **自动备份** - 定时自动备份服务器数据
- 💬 **聊天过滤** - 智能过滤违规内容和广告
- 🔔 **Webhook 通知** - Discord / Slack 实时推送安全告警
- 📊 **攻击报告** - 自动生成 HTML 安全事件报告
- ❤️ **健康检查** - 组件级健康探针，兼容 K8s 部署

---

## 功能特性

### 安全防护模块
| 模块 | 功能说明 |
|------|----------|
| DDoS防护 | 流量清洗、IP封禁、连接限制 |
| 防火墙 | 灵活规则配置、黑白名单 |
| 入侵检测 (IDS/IPS) | 异常行为识别、自动防御拦截 |
| 端口扫描检测 | 防护恶意扫描 |
| IP信誉查询 | 评估IP风险等级 |
| VPN/代理检测 | 识别并封禁VPN用户 |
| 流量分析 | 实时监控网络流量 |
| 数据包检查 (DPI) | 深度包检测与特征匹配 |

### 高级进阶防护
| 模块 | 功能说明 |
|------|----------|
| WAF防火墙 | 针对Web面板和API的恶意请求防护 |
| 蜜罐系统 (Honeypot) | 诱导并捕获恶意攻击者 |
| 零信任架构 (ZTA) | 强制身份验证、严格的权限控制 |
| Cloudflare 集成 | 自动同步真实玩家IP，联动CDN防御 |
| 反作弊集成 | 自动联动服务端反作弊插件，智能判定 |
| 威胁情报中心 | 全局恶意IP库共享与实时更新 |

### AI 自主防御
- 自动威胁检测与分类
- 智能防御策略选择
- 预测性维护建议
- 自动执行防御动作

### 服务器管理
- 定时自动备份（世界、插件、配置）
- 玩家管理（踢出、封禁、解封）
- 世界管理（动态加载、卸载）
- 高级性能监控与分析 (Profiler)
- 安全审计与数据导出 (Data Export)

---

## 安装部署

### 环境要求
- Java 17 或更高版本
- Ubuntu/Debian 服务器
- 2GB+ 可用内存
- 10GB+ 可用磁盘空间

### 安装步骤

#### 1. 上传文件到服务器
```bash
# 在本地打包
cd /path/to/AluerIII
./apache-maven-3.9.6/bin/mvn package -DskipTests

# 上传 jar 包和配置到服务器
scp target/AluerServerGuard-V4.0.jar user@your-server:/opt/aluer/
scp start.sh user@your-server:/opt/aluer/
```

#### 2. 配置系统服务
```bash
# 创建 systemd 服务文件
sudo nano /etc/systemd/system/aluer.service
```

写入以下内容：
```ini
[Unit]
Description=Aluer ServerGuard
After=network.target

[Service]
Type=simple
User=minecraft
WorkingDirectory=/opt/aluer
ExecStart=/usr/bin/java -jar /opt/aluer/AluerServerGuard-V4.0.jar
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
```

#### 3. 启动服务
```bash
sudo systemctl daemon-reload
sudo systemctl enable aluer
sudo systemctl start aluer

# 查看状态
sudo systemctl status aluer
```

---

## 快速开始

### 启动系统
```bash
# 方式1: 直接运行
java -jar AluerServerGuard-V4.0.jar

# 方式2: 使用启动脚本
./start.sh

# 方式3: 使用系统服务
sudo systemctl start aluer
```

### 首次使用
系统启动后会进入交互式终端：

```
╔══════════════════════════════════════════════════╗
║       欢迎使用 Aluer 服务器安全防护系统          ║
╠══════════════════════════════════════════════════╣
║  输入 help 查看可用命令                          ║
║  输入 ai <命令> 使用AI智能助手                   ║
╚══════════════════════════════════════════════════╝
aluer>
```

---

## AI协作终端

Aluer 的核心特性是可以用自然语言与系统对话。

### 使用方式
在终端输入 `ai` 后跟你的需求：

```
aluer> ai 测试一下服务器
```
系统会自动执行完整服务器测试。

```
aluer> ai 开启防御
```
系统会开启AI自主防御模式。

### 常用对话示例
| 你说 | 系统执行 |
|------|----------|
| 测试一下服务器 | 执行完整测试 |
| 开启防御 | 开启AI防御 |
| 查看安全状态 | 显示安全概览 |
| 帮我备份 | 查看备份记录 |
| 查看世界 | 列出所有世界 |
| 发送预警邮件 | 手动触发预警 |

---

## 命令参考

### 基础命令

#### help - 帮助
```
aluer> help
```
显示所有可用命令。

#### status - 服务器状态
```
aluer> status
```
显示服务器整体状态，包括CPU、内存、连接数等。

#### test - 测试服务器
```
aluer> test                    # 完整测试
aluer> test cpu               # 仅CPU测试
aluer> test memory            # 仅内存测试
aluer> test network           # 仅网络测试
aluer> test security          # 仅安全测试
```

### 安全命令

#### security - 安全状态
```
aluer> security               # 安全总览
aluer> security ddos         # DDoS防护状态
aluer> security firewall      # 防火墙状态
aluer> security intrusion    # 入侵检测状态
aluer> security threats      # AI威胁检测
aluer> security vpn          # VPN检测状态
aluer> security chat         # 聊天过滤状态
```

#### defense - 防御管理
```
aluer> defense                # 查看防御状态
aluer> defense on            # 开启AI防御
aluer> defense off           # 关闭AI防御
aluer> defense list          # 查看防御策略
aluer> defense level high     # 设置防御等级
```

### 管理命令

#### backup - 备份管理
```
aluer> backup                 # 查看备份记录
aluer> backup create         # 创建新备份
aluer> backup status         # 备份服务状态
aluer> backup start          # 启动定时备份
```

#### kick - 踢出玩家
```
aluer> kick PlayerName
```

#### ban - 封禁玩家
```
aluer> ban PlayerName        # 封禁玩家
aluer> ban PlayerName 作弊原因  # 带原因封禁
```

#### unban - 解封玩家
```
aluer> unban PlayerName
```

### 世界管理

#### world - 世界管理
```
aluer> world                 # 查看世界列表
aluer> world load world_nether  # 加载世界
aluer> world unload world_nether # 卸载世界
```

### 网络分析

#### network - 网络分析
```
aluer> network               # 网络统计
aluer> network geoip 1.2.3.4  # IP地理位置
aluer> network reputation 1.2.3.4  # IP信誉查询
aluer> network ports         # 端口扫描检测
```

### 预警系统

#### alert - 邮件预警
```
aluer> alert                 # 查看预警状态
aluer> alert test            # 发送测试邮件
aluer> alert send 服务器异常   # 手动发送告警
```

### 监控命令

#### metrics - 性能指标
```
aluer> metrics               # 指标摘要
aluer> metrics counters      # 查看计数器
aluer> metrics gauges       # 查看计量器
```

#### audit - 安全审计
```
aluer> audit                 # 最近审计事件
aluer> audit recent 20       # 查看最近20条
aluer> audit summary         # 审计摘要
```

#### tasks - 计划任务
```
aluer> tasks                 # 查看任务列表
aluer> tasks start           # 启动任务服务
```

### AI 命令

#### ask - 向AI提问
```
aluer> ask 如何提高服务器安全性?
```

---

## Web 控制面板与 API

Aluer 内置了轻量级的 Web Dashboard 和 RESTful API，方便与 Pterodactyl 等第三方服务器面板集成，或通过网页端实时查看状态。

### 访问方式
启动系统后，可通过 HTTP 协议访问系统 API 服务。

### 常用 API 接口
| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/status` | GET | 获取系统运行状态及时间戳 |
| `/api/server/info` | GET | 获取 Minecraft 服务器名称与版本信息 |
| `/api/performance` | GET | 获取性能指标（TPS, CPU, 内存） |
| `/api/command/execute` | POST | 远程执行 RCON 命令 (参数: `command`) |
| `/api/backup/list` | GET | 获取所有服务器备份列表 |
| `/api/backup/create` | POST | 触发创建新备份 (参数: `name`) |
| `/api/punishment/list` | GET | 获取封禁与禁言记录统计 |

*(提示：在生产环境中，请务必通过反向代理并配置鉴权，以保护 API 接口安全)*

### 系统健康检查 API（新增）

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/health` | GET | 完整健康报告（组件状态 + JVM 内存 + CPU 负载） |
| `/api/health/live` | GET | 存活探针，返回 `{"status":"UP"}` |
| `/api/health/ready` | GET | 就绪探针，检查 RCON 可用性 |

**健康检查响应示例**：
```json
{
  "status": "HEALTHY",
  "uptimeSeconds": 86400,
  "components": {
    "rcon": {"status": "UP"},
    "deepseek-ai": {"status": "UP", "model": "deepseek-chat"},
    "email-alert": {"status": "UP"},
    "security": {"status": "UP", "kernelEnabled": true},
    "self-healing": {"status": "UP", "dryRun": true}
  },
  "system": {
    "memory": {"usedMB": 320, "maxMB": 4096},
    "heapUsedMB": 180,
    "systemCpuLoad": 12.5
  }
}
```

### 通知与攻击报告 API（新增）

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/attacks/recent?limit=20` | GET | 最近攻击记录列表 |
| `/api/attacks/report` | POST | 生成并保存 HTML 攻击报告到 `./reports/` 目录 |
| `/api/webhook/test` | POST | 向已配置的 Discord/Slack 发送测试消息 |

**Webhook 配置**（`application.yml`）：
```yaml
serverguard:
  webhook:
    enabled: false                     # 设为 true 启用
    discord-url: ${ALUER_WEBHOOK_DISCORD:}   # Discord Webhook URL
    slack-url: ${ALUER_WEBHOOK_SLACK:}       # Slack Webhook URL
  report:
    dir: ./reports                     # 攻击报告输出目录
```

**环境变量**：
```bash
export ALUER_WEBHOOK_DISCORD="https://discord.com/api/webhooks/xxx/yyy"
export ALUER_WEBHOOK_SLACK="https://hooks.slack.com/services/xxx/yyy/zzz"
```

### 高级扩展安全模块 API（V4.0 完整版）

#### 身份认证与访问控制

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/auth/status` | GET | JWT 认证状态（活跃Token数、已吊销Token数） |
| `/api/security/brute-force/status` | GET | 暴力破解防护状态（锁定账号、检测统计） |

#### Minecraft 专项防护

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/anti-bot/status` | GET | 反机器人检测状态（被拦截IP、Bot分数） |
| `/api/security/anti-grief/status` | GET | 反破坏检测状态（被标记玩家、方块破坏率） |

#### 网络攻击监控

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/reverse-shell/status` | GET | 反向Shell检测状态 |
| `/api/security/arp-spoof/status` | GET | ARP欺骗检测状态（MAC变更记录） |
| `/api/security/dns-tunnel/status` | GET | DNS隧道检测状态 |
| `/api/security/exploit-signature/status` | GET | 漏洞签名检测统计 |
| `/api/security/exploit-signature/scan` | POST | 扫描内容中的漏洞签名 (参数: `content`, `source`) |

#### Web与应用安全

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/ssrf/status` | GET | SSRF防护状态 |
| `/api/security/xxe/status` | GET | XXE防护状态 |
| `/api/security/csp/status` | GET | CSP违规统计 |
| `/api/security/csp/headers` | GET | 获取推荐的安全响应头 |
| `/api/security/database-firewall/status` | GET | 数据库防火墙状态 |
| `/api/security/dlp/status` | GET | 数据防泄漏检测统计 |

#### 系统保护

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/memory/status` | GET | JVM内存保护状态（堆使用率、GC统计） |
| `/api/security/process-injection/status` | GET | 进程注入检测状态 |
| `/api/security/secure-delete/status` | GET | 安全文件删除统计 |

#### 安全运维

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/forensics/status` | GET | 取证案件列表与证据统计 |
| `/api/security/incident-response/status` | GET | 事件响应状态（活跃事件、剧本列表） |
| `/api/security/threat-hunting/status` | GET | 威胁狩猎状态（最近狩猎结果） |
| `/api/security/compliance/status` | GET | 合规扫描结果（评分、通过/失败项） |

#### Minecraft 专属安全（V4.0）

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/anti-xray/status` | GET | X-ray透视检测状态（可疑玩家、钻石/石头比） |
| `/api/security/anti-fly/status` | GET | 飞行/速度外挂检测状态 |
| `/api/security/anti-dupe/status` | GET | 物品复制检测状态（堆叠异常、高价值物品暴涨） |
| `/api/security/crash-exploit/status` | GET | 崩溃漏洞防护状态（超大包、NBT炸弹、书与笔攻击） |
| `/api/security/lag-machine/status` | GET | 卡服机检测状态（Observer链、TNT堆、红石密度） |

#### V4.0 新增安全 API

| 接口路径 | 方法 | 说明 |
|----------|------|------|
| `/api/security/geo-block/status` | GET | 地理IP封锁状态（拦截计数、黑白名单大小） |
| `/api/security/session-validation/status` | GET | 玩家会话验证状态（UUID检测、重放攻击计数） |
| `/api/security/plugin-verification/status` | GET | 插件完整性校验状态（已验证、失败、恶意检测） |
| `/api/security/connection-throttle/status` | GET | 连接速率限制状态（活跃IP、已拦截、已延迟） |
| `/api/security/backup-integrity/status` | GET | 备份完整性验证状态（通过/失败/损坏计数） |
| `/api/security/anti-skin-spoof/status` | GET | 皮肤伪造检测状态（冒充者、可疑URL、变更频率） |

---

## 配置说明

### 配置文件位置
主配置文件: `src/main/resources/application.yml`

### 核心配置项

#### DeepSeek AI 配置
```yaml
deepseek:
  api-key: sk-your-api-key    # API密钥
  enabled: true               # 是否启用
  model: deepseek-chat        # 模型名称
```

#### RCON 配置（用于连接Minecraft服务器）
```yaml
rcon:
  enabled: true
  host: localhost
  port: 25575
  password: your-password
```

#### 邮件预警配置
```yaml
alert:
  email:
    enabled: true
    smtp-host: smtp.qq.com
    smtp-port: 587
    username: your-email@qq.com
    password: your-auth-code
    from: your-email@qq.com
    to:
      - admin@example.com
      - backup@example.com
```

#### 安全模块配置
```yaml
security:
  ddos:
    enabled: true
    threshold: 1000      # 连接数阈值
  firewall:
    enabled: true
  intrusion:
    enabled: true
    alert-level: MEDIUM
```

#### 备份配置
```yaml
backup:
  enabled: true
  interval-hours: 6      # 备份间隔（小时）
  backup-dir: ./backups
  world-dir: /path/to/server/world
  backup-plugins: true
  backup-config: true
```

#### 高级扩展安全模块开关（V4.0）

以下 31 个高级扩展安全模块均可通过 `application.yml` 中的 `serverguard.security.super-evolution` 节点独立控制开关。设为 `false` 即可关闭该模块，相关检测逻辑将被跳过，不消耗额外性能。

```yaml
serverguard:
  security:
    super-evolution:
      # === V4.0 高级扩展安全模块（20个） ===
      jwt-auth: true                    # JWT身份认证与令牌管理
      brute-force: true                 # 暴力破解防护（多时间窗口检测）
      anti-bot: true                    # 反机器人检测（Bot名称/加入速率/IP关联）
      reverse-shell: true               # 反向Shell检测（50+ shell模式匹配）
      arp-spoof: true                   # ARP欺骗检测（MAC变更/网关伪造）
      dns-tunnel: true                  # DNS隧道检测（熵值/Base32编码/可疑TLD）
      exploit-signature: true           # 漏洞签名检测（Log4Shell/SQLi/RCE等15种）
      ssrf: true                        # SSRF防护（内网IP/云元数据/协议限制）
      xxe: true                         # XXE防护（实体注入/Billion Laughs检测）
      csp: true                         # CSP安全头强制执行（8种响应头）
      database-firewall: true           # 数据库防火墙（SQL注入/联合查询/时间盲注）
      dlp: true                         # 数据防泄漏（12种敏感信息规则+自动脱敏）
      memory-protection: true           # JVM内存保护（堆/GC/内存泄漏检测）
      process-injection: true           # 进程注入检测（/proc扫描/线程异常）
      secure-delete: true               # 安全文件删除（多道覆写DoD标准）
      forensics: true                   # 取证收集（进程/网络/日志快照）
      incident-response: true           # 事件响应（5种预定义响应剧本）
      threat-hunting: true              # 威胁狩猎（10种狩猎定义/5个类别）
      compliance: true                  # 合规扫描（7类20+检查项）
      anti-grief: true                  # 反破坏检测（方块破坏率/TNT/纵火/偷箱）
      # === Minecraft 专属防护模块（5个） ===
      anti-xray: true                   # X-ray透视检测（钻石比/直线挖掘/暗处精准）
      anti-fly: true                    # 飞行外挂检测（垂直/水平速度/悬空时间）
      anti-dupe: true                   # 物品复制检测（堆叠异常/高价值暴涨/9种复制法）
      crash-exploit: true               # 崩溃漏洞防护（超大包/NBT炸弹/书与笔攻击）
      lag-machine: true                 # 卡服机检测（Observer链/TNT堆/红石密度）
      # === V4.0 新增模块（6个） ===
      geo-block: true                   # 地理IP封锁（按国家/地区拦截）
      session-validation: true          # 玩家会话验证（UUID伪造/正版/离线检测）
      plugin-verification: true         # 插件完整性校验（Hash对比/未授权修改）
      connection-throttle: true         # 连接速率限制（IP/时间窗口/递增延迟）
      backup-integrity: true            # 备份完整性校验（SHA-256/文件计数/大小对比）
      anti-skin-spoof: true             # 皮肤伪造检测（模型数据异常/皮肤URL检测）
```

**开关说明：**
- 所有模块默认 `true`（开启），可根据需要设为 `false` 关闭
- 关闭模块后，对应的 API 端点仍可访问但返回空数据
- 关闭不需要的模块可以降低 CPU/内存开销
- 修改配置后需重启服务生效

---

## 预警系统

### 预警类型
系统会自动检测并发送预警：
- ⚠️ 服务器进程停止
- ⚠️ TPS过低
- ⚠️ CPU使用率过高
- ⚠️ 内存使用率过高
- ⚠️ 连接数异常（DDoS攻击）
- ⚠️ 日志中发现攻击行为
- ⚠️ 备份失败

### 手动触发预警
```bash
aluer> alert send 服务器可能遭受攻击
```

### 测试邮件系统
```bash
aluer> alert test
```

---

## 常见问题

### Q: 如何查看AI是否正常工作？
```bash
aluer> ask 你好
```
如果返回AI回答，说明配置正确。

### Q: 收不到邮件预警怎么办？
1. 检查 `application.yml` 中的邮箱配置
2. 确保使用的是授权码而非登录密码
3. 检查垃圾邮件文件夹

### Q: 如何完全停止系统？
```bash
sudo systemctl stop aluer
```

### Q: 如何查看运行日志？
```bash
# Systemd 日志
sudo journalctl -u aluer -f

# 应用日志
tail -f logs/aluer.log
```

### Q: AI防御模式有什么用？
AI防御模式开启后，系统会自动：
- 分析日志中的威胁
- 检测异常流量
- 预测服务器问题
- 自动执行防御动作

### Q: 如何更新系统？
```bash
# 停止服务
sudo systemctl stop aluer

# 备份数据
cp -r /opt/aluer/backups /backup/

# 替换jar包
cp target/AluerServerGuard-V4.0.jar /opt/aluer/

# 重启服务
sudo systemctl start aluer
```

---

## 技术支持

- 问题反馈: https://github.com/ZpjDev/Aluer/issues
- 文档更新: https://docs.aluer.com

---

*Aluer v1.0.0 - 保护您的 Minecraft 服务器*