From d6862b075442cb9de01db39143f24b30d5c97150 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=A0=E7=BF=94?= Date: Tue, 24 Mar 2026 11:29:05 +0800 Subject: [PATCH] docs: add security configuration documentation --- .env.example | 13 ++ SECURITY.md | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 344 insertions(+) create mode 100644 SECURITY.md diff --git a/.env.example b/.env.example index 6966bc6..d8f6edf 100644 --- a/.env.example +++ b/.env.example @@ -24,3 +24,16 @@ DATABASE_URL=file:./data/dev.db # File Upload UPLOAD_DIR=./uploads MAX_FILE_SIZE=10485760 + +# 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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..4e9afeb --- /dev/null +++ b/SECURITY.md @@ -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) +- 初始安全功能实现 +- 添加验证码系统 +- 添加频率限制 +- 添加输入清理 +- 添加安全日志 +- 添加安全监控仪表板