# 安全中间件功能文档

## 概述

本项目实现了全面的API安全中间件系统，包括限流、安全检查、安全头设置和认证失败处理等功能。

## 主要功能

### 1. 限流中间件 (Rate Limiting)

- **功能**: 基于IP地址的请求频率限制
- **默认配置**: 每分钟60个请求
- **实现**: 使用 `governor` crate 实现令牌桶算法
- **特性**:
  - 基于IP地址的独立限流
  - 可配置的请求频率
  - 自动清理过期记录

### 2. 安全检查中间件 (Security Check)

- **功能**: 检测和阻止可疑请求模式
- **检测模式**:
  - SQL注入尝试 (`union`, `select`, `insert`, `update`, `delete`, `drop`, `create`, `alter`)
  - XSS攻击 (`<script>`, `javascript:`, `vbscript:`, `onload=`, `onerror=`)
  - 路径遍历 (`../`, `../\`, `/etc/`, `/proc/`, `/sys/`)
  - 命令注入 (`cmd`, `exec`, `system`, `eval`, `base64_decode`)
  - 敏感账户名 (`admin`, `root`, `administrator`, `sa`, `dbo`)

### 3. 安全头中间件 (Security Headers)

- **功能**: 自动添加安全相关的HTTP头
- **添加的头**:
  - `X-Content-Type-Options: nosniff`
  - `X-Frame-Options: DENY`
  - `X-XSS-Protection: 1; mode=block`
  - `Referrer-Policy: strict-origin-when-cross-origin`
  - `Content-Security-Policy: default-src 'self'`
  - `Permissions-Policy: geolocation=(), microphone=(), camera=()`
- **移除的头**: `Server`, `X-Powered-By`

### 4. 暴力破解检测

- **功能**: 检测和防止暴力破解攻击
- **配置**:
  - 检测窗口: 5分钟
  - 最大尝试次数: 5次
  - 封禁时间: 1小时
- **触发条件**:
  - 可疑请求模式
  - 认证失败（登录相关端点）

### 5. IP封禁系统

- **功能**: 自动封禁恶意IP地址
- **特性**:
  - 基于暴力破解检测的自动封禁
  - 可配置的封禁时间
  - 自动清理过期封禁记录
  - 审计日志记录

### 6. JWT认证中间件

- **功能**: JWT令牌验证和用户认证
- **特性**:
  - Bearer token 提取
  - JWT签名验证
  - 过期时间检查
  - 用户ID注入到请求上下文

## 配置选项

```rust
pub struct SecurityConfig {
    /// 每分钟请求限制
    pub requests_per_minute: u32,
    /// 暴力破解检测窗口（秒）
    pub brute_force_window: u64,
    /// 暴力破解最大尝试次数
    pub brute_force_max_attempts: u32,
    /// IP封禁时间（秒）
    pub ban_duration: u64,
    /// 启用CORS
    pub enable_cors: bool,
    /// 允许的源
    pub allowed_origins: Vec<String>,
    /// 启用安全头
    pub enable_security_headers: bool,
    /// 最大请求体大小（字节）
    pub max_request_size: usize,
}
```

## 使用示例

### 基本集成

```rust
use rust_user_api::middleware::{SecurityConfig, SecurityState};

// 创建安全配置
let security_config = SecurityConfig::default();
let security_state = Arc::new(SecurityState::new(security_config));

// 应用中间件
let app = Router::new()
    .layer(axum::middleware::from_fn_with_state(
        security_state.clone(),
        rate_limiting_middleware,
    ))
    .layer(axum::middleware::from_fn_with_state(
        security_state.clone(),
        security_check_middleware,
    ))
    .layer(axum::middleware::from_fn(
        security_headers_middleware,
    ));
```

### JWT认证

```rust
use rust_user_api::middleware::{create_jwt, jwt_auth_middleware};

// 创建JWT token
let token = create_jwt("user_id_123")?;

// 应用JWT认证中间件
let protected_routes = Router::new()
    .route("/protected", get(protected_handler))
    .layer(axum::middleware::from_fn(jwt_auth_middleware));
```

## 监控和日志

### 审计日志

所有安全事件都会记录到审计日志中：

- 可疑请求模式检测
- IP封禁事件
- 限流触发
- 认证失败

### 指标收集

- 请求总数
- 错误率
- 平均响应时间
- 系统资源使用情况

## 安全最佳实践

1. **定期更新JWT密钥**: 在生产环境中使用强密钥并定期轮换
2. **监控审计日志**: 定期检查安全事件和异常模式
3. **调整限流参数**: 根据实际业务需求调整限流配置
4. **网络层防护**: 结合防火墙和CDN提供多层防护
5. **定期安全审计**: 定期检查和更新安全配置

## 性能考虑

- 使用高效的数据结构（DashMap）进行并发访问
- 自动清理过期记录避免内存泄漏
- 异步处理避免阻塞请求
- 可配置的检测模式减少不必要的计算

## 扩展性

系统设计支持：

- 自定义可疑模式
- 可插拔的认证方式
- 灵活的配置选项
- 多种存储后端支持

## 测试

项目包含全面的安全功能测试：

```bash
# 运行安全测试
cargo test security_tests

# 运行所有测试
cargo test
```

## 故障排除

### 常见问题

1. **限流过于严格**: 调整 `requests_per_minute` 参数
2. **误报可疑模式**: 检查和调整正则表达式模式
3. **JWT验证失败**: 检查密钥配置和token格式
4. **性能问题**: 监控内存使用和清理频率

### 调试技巧

- 启用详细日志记录
- 使用监控API检查系统状态
- 检查审计日志了解安全事件
- 使用测试工具验证配置