feat: 完成Rust User API完整开发
Some checks failed
Deploy to Production / Run Tests (push) Failing after 16m35s
Deploy to Production / Security Scan (push) Has been skipped
Deploy to Production / Build Docker Image (push) Has been skipped
Deploy to Production / Deploy to Staging (push) Has been skipped
Deploy to Production / Deploy to Production (push) Has been skipped
Deploy to Production / Notify Results (push) Successful in 31s

 新功能:
- SQLite数据库集成和持久化存储
- 数据库迁移系统和版本管理
- API分页功能和高效查询
- 用户搜索和过滤机制
- 完整的RBAC角色权限系统
- 结构化日志记录和系统监控
- API限流和多层安全防护
- Docker容器化和生产部署配置

🔒 安全特性:
- JWT认证和授权
- 限流和防暴力破解
- 安全头和CORS配置
- 输入验证和XSS防护
- 审计日志和安全监控

📊 监控和运维:
- Prometheus指标收集
- 健康检查和系统监控
- 自动化备份和恢复
- 完整的运维文档和脚本
- CI/CD流水线配置

🚀 部署支持:
- 多环境Docker配置
- 生产环境部署指南
- 性能优化和安全加固
- 故障排除和应急响应
- 自动化运维脚本

📚 文档完善:
- API使用文档
- 部署检查清单
- 运维操作手册
- 性能和安全指南
- 故障排除指南
This commit is contained in:
2025-08-07 16:03:32 +08:00
parent cf01d557b9
commit bb9d7a869d
45 changed files with 8433 additions and 85 deletions

201
docs/security-features.md Normal file
View File

@@ -0,0 +1,201 @@
# 安全中间件功能文档
## 概述
本项目实现了全面的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检查系统状态
- 检查审计日志了解安全事件
- 使用测试工具验证配置