novalon-website/docs/guides/SECURITY.md

安全配置文档

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

目录

1. 安全功能概述
2. 环境变量配置
3. 安全组件说明
4. 监控和日志
5. 最佳实践

安全功能概述

项目实现了以下多层安全防护机制：

• 增强验证码系统 - 数学验证码，支持多种复杂度级别
• 多层频率限制 - IP、邮箱和全局频率限制
• 输入清理 - 自动清理和检测恶意内容
• 安全日志系统 - 记录所有安全事件
• 安全中间件 - 统一的安全检查接口
• 安全监控仪表板 - 实时监控安全状态

环境变量配置

安全相关环境变量

在 .env 文件中添加以下安全配置：

# 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)

提供统一的安全配置管理，支持从环境变量读取配置。

主要功能：

• 集中管理所有安全配置
• 支持环境变量覆盖
• 提供默认值

使用示例：

import { SecurityConfig } from '@/lib/security/config';

const config = SecurityConfig.getInstance();
const maxRequests = config.rateLimit.maxRequests;

2. 增强验证码系统 (src/lib/security/captcha.ts)

实现数学验证码生成和验证功能。

主要功能：

• 支持三种复杂度级别：simple、medium、complex
• 基于时间戳的哈希验证
• 自动过期机制
• 防重放攻击

使用示例：

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级别频率限制
• 邮箱级别频率限制
• 全局频率限制
• 滑动窗口算法
• 自动清理过期记录

使用示例：

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注入检测
• 恶意内容检测
• 输入长度限制

使用示例：

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活动跟踪
• 自动日志清理
• 统计信息生成

使用示例：

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)

统一的安全检查接口。

主要功能：

• 集成所有安全组件
• 统一的安全检查流程
• 详细的错误报告
• 输入清理

使用示例：

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. 生产环境配置

# 生产环境建议配置
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. 开发环境配置

# 开发环境宽松配置
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)

• 初始安全功能实现
• 添加验证码系统
• 添加频率限制
• 添加输入清理
• 添加安全日志
• 添加安全监控仪表板