# 🌐 Web 监控配置管理指南

Runtime Security Guard 提供完整的 Web 监控和配置管理界面。

---

## 🚀 快速启动

### 启动 Web 服务器

```bash
# 默认端口 3000
npm run web

# 指定端口
npm run web:start 8080

# 或直接用 Node 运行
node scripts/start-web.ts 3000 127.0.0.1
```

### 访问界面

打开浏览器访问：
```
http://localhost:3000
```

---

## 📊 监控界面功能

### 1️⃣ 概览卡片

显示关键指标：
- 📊 总告警数
- 🚨 CRITICAL 级别告警数
- ⚠️  HIGH 级别告警数
- ⏱️  平均检测延迟
- 💾 缓存命中率
- ✅ 健康状态

### 2️⃣ 告警类型分布

可视化展示各类告警数量：
- PROMPT_INJECTION
- DATA_EXFILTRATION
- COMMAND_EXECUTION
- SENSITIVE_DATA
- SOCIAL_ENGINEERING
- SUPPLY_CHAIN
- ZERO_DAY
- APT
- INSIDER_THREAT

### 3️⃣ 严重程度分布

按严重程度分类统计：
- CRITICAL（紧急）
- HIGH（高）
- MEDIUM（中）
- LOW（低）

### 4️⃣ 最近告警列表

显示最近 20 条告警详情：
- 时间戳
- 事件 ID
- 告警类型
- 严重程度
- 处理操作（ALLOWED/REDACTED/BLOCKED）

### 5️⃣ 性能指标

实时性能监控：
- P95 延迟
- P99 延迟
- 最大延迟
- 内存使用

### 6️⃣ 配置管理

在线修改配置：
- 检测阈值（0.0-1.0）
- 缓存 TTL（秒）

---

## 🔌 API 接口

### 获取统计信息

```bash
curl http://localhost:3000/api/stats
```

**响应示例：**
```json
{
  "total": 156,
  "byType": {
    "PROMPT_INJECTION": 45,
    "DATA_EXFILTRATION": 32
  },
  "bySeverity": {
    "CRITICAL": 12,
    "HIGH": 54,
    "MEDIUM": 67,
    "LOW": 23
  },
  "byAction": {
    "ALLOWED": 1234,
    "REDACTED": 89,
    "BLOCKED": 67
  },
  "timeRange": {
    "start": "2026-03-07T12:00:00.000Z",
    "end": "2026-03-07T13:30:00.000Z"
  }
}
```

---

### 获取告警列表

```bash
curl http://localhost:3000/api/alerts?limit=50
```

**响应示例：**
```json
[
  {
    "timestamp": "2026-03-07T13:30:00.000Z",
    "eventId": "file:/test/malicious.txt",
    "action": "BLOCKED",
    "result": {
      "riskScore": 0.8,
      "risks": [
        {
          "type": "COMMAND_EXECUTION",
          "severity": "CRITICAL"
        }
      ]
    }
  }
]
```

---

### 获取性能指标

```bash
curl http://localhost:3000/api/performance
```

**响应示例：**
```json
{
  "detectionLatency": {
    "avg": 15.23,
    "min": 0.5,
    "max": 45.8,
    "p95": 35.2,
    "p99": 42.1
  },
  "cachePerformance": {
    "hitRate": 85.3,
    "size": 234,
    "evictions": 12
  },
  "resourceUsage": {
    "memoryMB": 78.5,
    "cpuPercent": 0
  }
}
```

---

### 健康检查

```bash
curl http://localhost:3000/api/health
```

**响应示例：**
```json
{
  "healthy": true,
  "errors": [],
  "uptime": 3600
}
```

---

## 🔧 配置管理

### 通过 Web 界面配置

1. 访问 http://localhost:3000
2. 滚动到"配置管理"部分
3. 修改参数
4. 点击"保存配置"

### 通过 API 配置

```bash
curl -X POST http://localhost:3000/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 0.7,
    "cacheTtl": 120
  }'
```

---

## 📱 实时监控

### 自动刷新

Web 界面每 5 秒自动刷新数据，无需手动刷新。

### 停止自动刷新

关闭浏览器标签页即可停止。

---

## 🔐 安全配置

### 启用认证（计划中）

```typescript
// 未来版本支持
const server = new WebMonitorServer(guard, alerter, perfMonitor, {
  port: 3000,
  host: '0.0.0.0',
  enableAuth: true,
  authToken: 'your-secret-token',
});
```

### 限制访问 IP

```bash
# 只允许本地访问
npm run web:start 3000 127.0.0.1

# 允许所有 IP（不推荐）
npm run web:start 3000 0.0.0.0
```

---

## 🎨 界面预览

### 颜色说明

| 颜色 | 含义 |
|------|------|
| 🔴 红色 | CRITICAL 级别 |
| 🟠 橙色 | HIGH 级别 |
| 🟡 黄色 | MEDIUM 级别 |
| 🟢 绿色 | LOW 级别 / 健康 |
| 🔵 蓝色 | 信息 |

---

## 🚨 告警处理建议

### CRITICAL 级别

**响应时间：** 立即  
**操作：**
1. 立即阻止相关操作
2. 人工审查告警详情
3. 调查根本原因
4. 更新防护规则

### HIGH 级别

**响应时间：** < 1 小时  
**操作：**
1. 自动阻止或脱敏
2. 尽快人工审查
3. 记录告警详情

### MEDIUM 级别

**响应时间：** < 24 小时  
**操作：**
1. 自动脱敏处理
2. 定期审查
3. 分析趋势

### LOW 级别

**响应时间：** < 1 周  
**操作：**
1. 记录日志
2. 可选审查
3. 用于统计分析

---

## 📊 集成到监控系统

### Prometheus 指标导出

```typescript
import { Registry, Counter } from 'prom-client';

const register = new Registry();

// 安全告警指标
const securityAlerts = new Counter({
  name: 'security_alerts_total',
  help: 'Total number of security alerts',
  labelNames: ['type', 'severity', 'action'],
  registers: [register],
});

// 在告警时记录
viewer.startMonitoring((alert) => {
  for (const risk of alert.result?.risks || []) {
    securityAlerts.inc({
      type: risk.type,
      severity: risk.severity,
      action: alert.action,
    });
  }
});

// 暴露指标端点
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});
```

### Grafana 仪表盘

导入 Prometheus 数据源后，创建以下面板：
1. 告警总数趋势
2. 告警类型分布饼图
3. 严重程度分布柱状图
4. 检测延迟折线图
5. 缓存命中率仪表盘

---

## 🛠️ 故障排除

### Web 服务器无法启动

**问题：** 端口被占用

**解决：**
```bash
# 查看端口占用
lsof -i :3000

# 使用其他端口
npm run web:start 8080
```

### 界面无法访问

**问题：** 防火墙阻止

**解决：**
```bash
# 检查防火墙
sudo ufw allow 3000

# 或使用本地访问
http://127.0.0.1:3000
```

### 数据不刷新

**问题：** 浏览器缓存

**解决：**
- 强制刷新：Ctrl+F5 或 Cmd+Shift+R
- 清除浏览器缓存
- 检查浏览器控制台错误

---

## 📝 最佳实践

1. **定期检查监控界面** - 每天查看告警统计
2. **设置 CRITICAL 告警通知** - 集成 Slack/邮件通知
3. **定期导出告警数据** - 每周导出 CSV 进行归档分析
4. **监控性能指标** - 关注检测延迟和缓存命中率
5. **定期审查配置** - 根据实际告警调整阈值

---

**最后更新：** 2026-03-07  
**版本：** v1.1.0