diff --git a/README.md b/README.md index c271329..a94d3e6 100644 --- a/README.md +++ b/README.md @@ -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 条） | --- diff --git a/docs/PROJECT_SUMMARY.md b/docs/PROJECT_SUMMARY.md index 2ac7de4..3541d85 100644 --- a/docs/PROJECT_SUMMARY.md +++ b/docs/PROJECT_SUMMARY.md @@ -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`** (告警数据模型) diff --git a/docs/USER_MANUAL.md b/docs/USER_MANUAL.md index a73da36..b0c1686 100644 --- a/docs/USER_MANUAL.md +++ b/docs/USER_MANUAL.md @@ -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" +``` + --- ## 配置说明