张翔
332 lines
7.8 KiB
Markdown
332 lines
7.8 KiB
Markdown
# 安全配置文档
|
|
|
|
本文档详细说明了项目中新增的安全功能及其配置方法。
|
|
|
|
## 目录
|
|
|
|
1. [安全功能概述](#安全功能概述)
|
|
2. [环境变量配置](#环境变量配置)
|
|
3. [安全组件说明](#安全组件说明)
|
|
4. [监控和日志](#监控和日志)
|
|
5. [最佳实践](#最佳实践)
|
|
|
|
## 安全功能概述
|
|
|
|
项目实现了以下多层安全防护机制：
|
|
|
|
- **增强验证码系统** - 数学验证码，支持多种复杂度级别
|
|
- **多层频率限制** - IP、邮箱和全局频率限制
|
|
- **输入清理** - 自动清理和检测恶意内容
|
|
- **安全日志系统** - 记录所有安全事件
|
|
- **安全中间件** - 统一的安全检查接口
|
|
- **安全监控仪表板** - 实时监控安全状态
|
|
|
|
## 环境变量配置
|
|
|
|
### 安全相关环境变量
|
|
|
|
在 `.env` 文件中添加以下安全配置：
|
|
|
|
```bash
|
|
# Security Configuration
|
|
# Rate Limiting (每分钟最大请求数)
|
|
RATE_LIMIT_MAX_REQUESTS=10
|
|
RATE_LIMIT_WINDOW_MS=60000
|
|
|
|
# Captcha Configuration
|
|
CAPTCHA_EXPIRY_MS=300000
|
|
CAPTCHA_MAX_ATTEMPTS=3
|
|
|
|
# Security Logging
|
|
SECURITY_LOG_RETENTION_DAYS=30
|
|
SECURITY_LOG_MAX_ENTRIES=1000
|
|
```
|
|
|
|
### 环境变量说明
|
|
|
|
| 变量名 | 类型 | 默认值 | 说明 |
|
|
|---------|------|---------|------|
|
|
| `RATE_LIMIT_MAX_REQUESTS` | Number | 10 | 单个IP在时间窗口内的最大请求数 |
|
|
| `RATE_LIMIT_WINDOW_MS` | Number | 60000 | 频率限制的时间窗口（毫秒），默认为60秒 |
|
|
| `CAPTCHA_EXPIRY_MS` | Number | 300000 | 验证码过期时间（毫秒），默认为5分钟 |
|
|
| `CAPTCHA_MAX_ATTEMPTS` | Number | 3 | 单个会话的最大验证码尝试次数 |
|
|
| `SECURITY_LOG_RETENTION_DAYS` | Number | 30 | 安全日志保留天数 |
|
|
| `SECURITY_LOG_MAX_ENTRIES` | Number | 1000 | 内存中保留的最大日志条目数 |
|
|
|
|
## 安全组件说明
|
|
|
|
### 1. 安全配置模块 (`src/lib/security/config.ts`)
|
|
|
|
提供统一的安全配置管理，支持从环境变量读取配置。
|
|
|
|
**主要功能：**
|
|
- 集中管理所有安全配置
|
|
- 支持环境变量覆盖
|
|
- 提供默认值
|
|
|
|
**使用示例：**
|
|
|
|
```typescript
|
|
import { SecurityConfig } from '@/lib/security/config';
|
|
|
|
const config = SecurityConfig.getInstance();
|
|
const maxRequests = config.rateLimit.maxRequests;
|
|
```
|
|
|
|
### 2. 增强验证码系统 (`src/lib/security/captcha.ts`)
|
|
|
|
实现数学验证码生成和验证功能。
|
|
|
|
**主要功能：**
|
|
- 支持三种复杂度级别：simple、medium、complex
|
|
- 基于时间戳的哈希验证
|
|
- 自动过期机制
|
|
- 防重放攻击
|
|
|
|
**使用示例：**
|
|
|
|
```typescript
|
|
import { generateCaptcha, validateCaptcha } from '@/lib/security/captcha';
|
|
|
|
// 生成验证码
|
|
const captcha = generateCaptcha('simple');
|
|
console.log(captcha.question); // "1 + 1 = ?"
|
|
console.log(captcha.answer); // 2
|
|
|
|
// 验证验证码
|
|
const isValid = validateCaptcha(hash, answer, timestamp);
|
|
```
|
|
|
|
### 3. 频率限制系统 (`src/lib/security/rate-limiter.ts`)
|
|
|
|
实现多层频率限制机制。
|
|
|
|
**主要功能：**
|
|
- IP级别频率限制
|
|
- 邮箱级别频率限制
|
|
- 全局频率限制
|
|
- 滑动窗口算法
|
|
- 自动清理过期记录
|
|
|
|
**使用示例：**
|
|
|
|
```typescript
|
|
import { RateLimiter } from '@/lib/security/rate-limiter';
|
|
|
|
const rateLimiter = new RateLimiter();
|
|
|
|
// 检查IP频率限制
|
|
const ipCheck = rateLimiter.checkIP(ip);
|
|
if (!ipCheck.allowed) {
|
|
return { error: '请求过于频繁，请稍后再试' };
|
|
}
|
|
|
|
// 检查邮箱频率限制
|
|
const emailCheck = rateLimiter.checkEmail(email);
|
|
if (!emailCheck.allowed) {
|
|
return { error: '该邮箱提交过于频繁，请稍后再试' };
|
|
}
|
|
```
|
|
|
|
### 4. 输入清理模块 (`src/lib/security/sanitizer.ts`)
|
|
|
|
实现输入清理和恶意内容检测。
|
|
|
|
**主要功能：**
|
|
- HTML标签清理
|
|
- XSS攻击检测
|
|
- SQL注入检测
|
|
- 恶意内容检测
|
|
- 输入长度限制
|
|
|
|
**使用示例：**
|
|
|
|
```typescript
|
|
import { sanitizeInput, detectMaliciousContent } from '@/lib/security/sanitizer';
|
|
|
|
// 清理输入
|
|
const sanitized = sanitizeInput(userInput);
|
|
|
|
// 检测恶意内容
|
|
const malicious = detectMaliciousContent(userInput);
|
|
if (malicious.detected) {
|
|
return { error: '检测到恶意内容' };
|
|
}
|
|
```
|
|
|
|
### 5. 安全日志系统 (`src/lib/security/logger.ts`)
|
|
|
|
记录所有安全相关事件。
|
|
|
|
**主要功能：**
|
|
- 事件类型分类
|
|
- 严重级别标记
|
|
- IP活动跟踪
|
|
- 自动日志清理
|
|
- 统计信息生成
|
|
|
|
**使用示例：**
|
|
|
|
```typescript
|
|
import { SecurityLogger } from '@/lib/security/logger';
|
|
|
|
const logger = new SecurityLogger();
|
|
|
|
// 记录安全事件
|
|
logger.logEvent({
|
|
type: SecurityEventType.CAPTCHA_FAILED,
|
|
ip: clientIP,
|
|
email: userEmail,
|
|
userAgent: request.headers.get('user-agent'),
|
|
});
|
|
|
|
// 获取统计信息
|
|
const stats = logger.getStats();
|
|
console.log(stats.totalRequests);
|
|
console.log(stats.blockedRequests);
|
|
```
|
|
|
|
### 6. 安全中间件 (`src/lib/security/middleware.ts`)
|
|
|
|
统一的安全检查接口。
|
|
|
|
**主要功能：**
|
|
- 集成所有安全组件
|
|
- 统一的安全检查流程
|
|
- 详细的错误报告
|
|
- 输入清理
|
|
|
|
**使用示例：**
|
|
|
|
```typescript
|
|
import { SecurityMiddleware } from '@/lib/security/middleware';
|
|
|
|
const middleware = new SecurityMiddleware();
|
|
|
|
const result = await middleware.checkRequest({
|
|
ip: clientIP,
|
|
email: userEmail,
|
|
name: userName,
|
|
captchaHash: captchaHash,
|
|
captchaAnswer: captchaAnswer,
|
|
captchaTimestamp: captchaTimestamp,
|
|
});
|
|
|
|
if (!result.allowed) {
|
|
return Response.json(
|
|
{ error: result.errors[0] },
|
|
{ status: 403 }
|
|
);
|
|
}
|
|
|
|
// 清理输入
|
|
const sanitized = middleware.sanitizeRequest({
|
|
name: userName,
|
|
email: userEmail,
|
|
message: userMessage,
|
|
});
|
|
```
|
|
|
|
## 监控和日志
|
|
|
|
### 安全监控仪表板
|
|
|
|
访问路径：`/admin/security`
|
|
|
|
**功能：**
|
|
- 实时安全统计
|
|
- 安全日志查看
|
|
- 按严重级别过滤
|
|
- 自动刷新数据
|
|
|
|
**统计指标：**
|
|
- 总请求数
|
|
- 已拦截请求数
|
|
- 验证码尝试次数
|
|
- 频率限制命中次数
|
|
- 恶意内容检测次数
|
|
- 成功率
|
|
|
|
### 安全事件类型
|
|
|
|
| 事件类型 | 严重级别 | 说明 |
|
|
|---------|---------|------|
|
|
| `captcha_failed` | Low | 验证码验证失败 |
|
|
| `captcha_expired` | Low | 验证码已过期 |
|
|
| `rate_limit_exceeded` | Medium | 超过频率限制 |
|
|
| `malicious_content` | High | 检测到恶意内容 |
|
|
| `xss_attempt` | High | XSS攻击尝试 |
|
|
| `sql_injection_attempt` | High | SQL注入尝试 |
|
|
| `suspicious_ip` | Medium | 可疑IP活动 |
|
|
| `blocked_request` | High | 请求被拦截 |
|
|
|
|
## 最佳实践
|
|
|
|
### 1. 生产环境配置
|
|
|
|
```bash
|
|
# 生产环境建议配置
|
|
RATE_LIMIT_MAX_REQUESTS=5
|
|
RATE_LIMIT_WINDOW_MS=60000
|
|
CAPTCHA_EXPIRY_MS=180000
|
|
CAPTCHA_MAX_ATTEMPTS=3
|
|
SECURITY_LOG_RETENTION_DAYS=90
|
|
SECURITY_LOG_MAX_ENTRIES=5000
|
|
```
|
|
|
|
### 2. 开发环境配置
|
|
|
|
```bash
|
|
# 开发环境宽松配置
|
|
RATE_LIMIT_MAX_REQUESTS=100
|
|
RATE_LIMIT_WINDOW_MS=60000
|
|
CAPTCHA_EXPIRY_MS=600000
|
|
CAPTCHA_MAX_ATTEMPTS=10
|
|
SECURITY_LOG_RETENTION_DAYS=7
|
|
SECURITY_LOG_MAX_ENTRIES=500
|
|
```
|
|
|
|
### 3. 安全建议
|
|
|
|
1. **定期审查日志** - 定期检查安全日志，识别异常模式
|
|
2. **监控统计指标** - 关注拦截率和成功率的变化
|
|
3. **及时更新配置** - 根据实际使用情况调整限制参数
|
|
4. **保护敏感端点** - 确保管理端点有额外的认证
|
|
5. **使用HTTPS** - 生产环境必须使用HTTPS
|
|
6. **定期备份** - 定期备份安全日志和配置
|
|
|
|
### 4. 故障排除
|
|
|
|
**问题：验证码总是失败**
|
|
- 检查客户端和服务器时间是否同步
|
|
- 确认验证码未过期
|
|
- 检查CAPTCHA_EXPIRY_MS配置
|
|
|
|
**问题：频率限制过于严格**
|
|
- 调整RATE_LIMIT_MAX_REQUESTS
|
|
- 增加RATE_LIMIT_WINDOW_MS
|
|
- 检查是否有代理或负载均衡器
|
|
|
|
**问题：误报率过高**
|
|
- 调整恶意内容检测规则
|
|
- 检查sanitizer配置
|
|
- 审查安全日志中的误报案例
|
|
|
|
## 技术支持
|
|
|
|
如需技术支持或报告安全问题，请联系：
|
|
|
|
- 邮箱：security@novalon.cn
|
|
- 文档：查看项目README.md
|
|
- 问题追踪：查看项目Issues
|
|
|
|
## 更新日志
|
|
|
|
### v1.0.0 (2024-03-24)
|
|
- 初始安全功能实现
|
|
- 添加验证码系统
|
|
- 添加频率限制
|
|
- 添加输入清理
|
|
- 添加安全日志
|
|
- 添加安全监控仪表板
|