# 安全配置文档

本文档详细说明了项目中新增的安全功能及其配置方法。

## 目录

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)
- 初始安全功能实现
- 添加验证码系统
- 添加频率限制
- 添加输入清理
- 添加安全日志
- 添加安全监控仪表板