refactor: reorganize project structure and improve code quality

- Move CI/CD configs to config/ci/ directory - Reorganize scripts into categorized directories (deployment, monitoring, testing, utils) - Consolidate documentation into docs/ directory with proper structure - Update linting and testing configurations - Remove obsolete test reports and performance summaries - Add new documentation for code quality tools and contact form security - Improve project organization and maintainability - Fix lint-staged config to only lint JS/TS files - Disable react/react-in-jsx-scope rule for Next.js compatibility - Ignore scripts and test config directories in ESLint
2026-03-24 13:38:58 +08:00
parent c06ac08510
commit 498bb3a3c8
62 changed files with 5473 additions and 6498 deletions
@@ -0,0 +1,331 @@
+# 安全配置文档
+
+本文档详细说明了项目中新增的安全功能及其配置方法。
+
+## 目录
+
+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)
+- 初始安全功能实现
+- 添加验证码系统
+- 添加频率限制
+- 添加输入清理
+- 添加安全日志
+- 添加安全监控仪表板