docs: update README, PROJECT_SUMMARY, USER_MANUAL for new features

- README: add notification package, HealthService, health/webhook/report APIs - README: update web console features (sparklines, auto-refresh, health panel) - PROJECT_SUMMARY: add notification module and web infrastructure sections - USER_MANUAL: add health check, webhook, and attack report API docs
2026-05-10 16:12:23 +08:00
parent 4c08566022
commit 5e1ab0c1c7
3 changed files with 137 additions and 5 deletions
@@ -801,9 +801,11 @@ serverguard

 | 类 | 功能 |
 |----|------|
-| `DashboardController` | REST API（`/api/*`），提供状态查询、命令执行、备份管理等接口 |
+| `DashboardController` | REST API（`/api/*`），提供状态查询、命令执行、备份管理、健康检查、攻击报告等接口 |
 | `OperationsConsoleController` | 运营控制台 API（`/api/console/*`），总览数据、Shield 控制、快捷操作 |
 | `ConsoleStreamController` | SSE 流推送（`/api/console/stream/overview`） |
+| `HealthService` | 组件级健康检查（RCON/AI/邮件/安全/自愈），系统资源信息汇总 |
+| `RequestLoggingFilter` | HTTP 请求日志过滤器，慢请求和 500 错误自动告警 |

 ### 辅助功能模块

@@ -822,6 +824,7 @@ serverguard
 | `com.aluer.schedule` | `ScheduledTaskService` | 计划任务引擎（定时重启/备份/清 lag/公告） |
 | `com.aluer.export` | `DataExportService` | 安全数据导出（审计日志/攻击记录/性能报告） |
 | `com.aluer.command` | `AdminCommands` / `TestCommands` | Spring Shell 管理命令和测试命令 |
+| `com.aluer.notification` | `WebhookService` / `AttackReportService` | Discord/Slack Webhook 告警通知；HTML 攻击报告自动生成与导出 |

 ### 数据模型 (`com.aluer.model`)

@@ -944,6 +947,53 @@ curl -X POST "http://localhost:8080/api/security/network/quarantine" \
 3. **会话超时**：默认 30 分钟无活动自动断开
 4. **审计同步**：所有 SSH 操作自动记录到 `SecurityAuditService`

+### 健康检查 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/api/health` | 完整健康报告（组件状态 + 系统资源） |
+| `GET` | `/api/health/live` | 存活探针（K8s liveness probe） |
+| `GET` | `/api/health/ready` | 就绪探针（K8s readiness probe） |
+
+**示例响应 (`/api/health`)**：
+
+```json
+{
+  "status": "HEALTHY",
+  "uptimeSeconds": 86400,
+  "components": {
+    "rcon": {"status": "UP", "host": "localhost:25575"},
+    "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, "usagePercent": 7.8},
+    "heapUsedMB": 180,
+    "systemCpuLoad": 12.5
+  }
+}
+```
+
+### 通知与报告 API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/api/attacks/recent?limit=20` | 最近攻击记录 |
+| `POST` | `/api/attacks/report` | 生成 HTML 攻击报告 |
+| `POST` | `/api/webhook/test` | 测试 Discord/Slack Webhook |
+
+**Webhook 配置**（`application.yml`）：
+
+```yaml
+serverguard:
+  webhook:
+    enabled: false
+    discord-url: ${ALUER_WEBHOOK_DISCORD:}
+    slack-url: ${ALUER_WEBHOOK_SLACK:}
+```
+
 ### 备份管理 API

 | 方法 | 路径 | 说明 |
@@ -1004,15 +1054,18 @@ Aluer 内置 React 19 + Vite 6 构建的单页应用控制台（Nebula Console
                  setInterval 轮询 /api/console/overview
 ```

-### 角色功能
+### 功能清单

 | 功能 | 说明 |
 |------|------|
 | Shield 控制 | 一键切换 FORTIFY / MIRAGE / SHELTER / RECOVERY 模式 |
+| 性能走势 | TPS / CPU / Memory / 在线玩家 SparkBar 实时可视化 |
+| 自动刷新 | 可切换开关 + 可选间隔（3s / 6s / 10s / 30s） |
+| 健康检查面板 | 可折叠，显示 RCON/AI/邮件/安全/自愈 组件 UP/DOWN 状态 |
 | SSH 远程终端 | 连接远程节点，执行命令，带命令守卫审查 |
 | 模块监控 | 9 个模块的状态、信号值实时显示 |
-| 威胁视图 | 高风险 IP 列表，score + riskLevel + 详情 |
-| 审计筛选 | 实时筛选审计事件、网络事件、Shield 状态变迁 |
+| 威胁视图 | 高风险 IP 列表，score + riskLevel + 详情（最多 10 条） |
+| 审计筛选 | 实时筛选审计事件、网络事件、Shield 状态变迁（最多 24 条） |

 ---

@@ -110,7 +110,30 @@ AluerIII 是一个专为 Minecraft (PaperMC) 服务器设计的高级安全防

 ---

-## 7. 数据模型与配置管理 (`com.aluer.model` / `com.aluer.config`)
+## 6.5. 通知与报告模块 (`com.aluer.notification`)
+- **`WebhookService`** (Webhook 通知服务)
+  - 支持 Discord 和 Slack 双通道 Webhook 推送。
+  - 安全告警发生时自动发送 Embed 消息，包含告警类型、严重程度、置信度。
+  - 支持自定义消息推送，含颜色编码（critical=红色 / warning=橙色 / info=绿色）。
+- **`AttackReportService`** (攻击报告服务)
+  - 记录最近 500 条攻击事件到内存环形缓冲区。
+  - 一键生成 HTML 格式安全事件报告，含时间线、攻击类型、来源 IP、置信度。
+  - 报告自动保存到可配置目录，文件名含时间戳。
+
+---
+
+## 7. Web 基础设施层 (`com.aluer.web` / `com.aluer.config`)
+- **`HealthService`** (健康检查服务)
+  - 组件级健康探针：逐一检查 RCON 连接、DeepSeek API、邮件服务、安全引擎、自愈编排。
+  - 系统资源信息汇总：JVM 内存使用、堆内存、CPU 负载、运行时间。
+  - 兼容 Kubernetes liveness / readiness probe 格式。
+- **`RequestLoggingFilter`** (请求日志过滤器)
+  - 拦截所有 HTTP 请求，记录慢请求（>1s）和服务器错误（5xx）。
+  - 不影响正常请求性能（debug 级别日志）。
+- **`CorsConfig`** (跨域配置)
+  - 允许 `/api/**` 路径的跨域请求，支持所有 Origin、常用 HTTP 方法和预检缓存。
+
+## 8. 数据模型与配置管理 (`com.aluer.model` / `com.aluer.config`)
 - **`ServerGuardConfig`** (全局参数配置)
  - 映射 `application.yml` 中的参数，包括：各类安全触发阈值、DeepSeek API 密钥、数据库连接及告警邮箱配置等。
 - **`AlertEvent`** (告警数据模型)
@@ -23,6 +23,9 @@ Aluer 是一款专为 Minecraft PaperMC 服务器设计的安全防护系统，
 - 📧 **邮件预警** - 实时告警通知管理员
 - 🔄 **自动备份** - 定时自动备份服务器数据
 - 💬 **聊天过滤** - 智能过滤违规内容和广告
+- 🔔 **Webhook 通知** - Discord / Slack 实时推送安全告警
+- 📊 **攻击报告** - 自动生成 HTML 安全事件报告
+- ❤️ **健康检查** - 组件级健康探针，兼容 K8s 部署

 ---

@@ -332,6 +335,59 @@ Aluer 内置了轻量级的 Web Dashboard 和 RESTful API，方便与 Pterodacty

 *(提示：在生产环境中，请务必通过反向代理并配置鉴权，以保护 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"
+```
+
 ---

 ## 配置说明