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,732 @@
+# 安全功能部署文档
+
+## 目录
+
+1. [部署前准备](#部署前准备)
+2. [环境配置](#环境配置)
+3. [部署步骤](#部署步骤)
+4. [部署后验证](#部署后验证)
+5. [监控和维护](#监控和维护)
+6. [故障排除](#故障排除)
+7. [回滚计划](#回滚计划)
+
+## 部署前准备
+
+### 系统要求
+
+- **Node.js**: 18.x 或更高版本
+- **npm**: 9.x 或更高版本
+- **数据库**: PostgreSQL 14+ 或 SQLite（开发环境）
+- **邮件服务**: Resend API 密钥
+- **操作系统**: Linux/macOS/Windows
+
+### 依赖检查
+
+在部署前，确保所有依赖都已正确安装：
+
+```bash
+# 检查 Node.js 版本
+node --version  # 应该 >= 18.x
+
+# 检查 npm 版本
+npm --version  # 应该 >= 9.x
+
+# 安装项目依赖
+npm install
+```
+
+### 安全配置检查
+
+确保以下安全配置文件已正确设置：
+
+```bash
+# 检查环境变量示例文件
+ls -la .env.example
+
+# 检查安全模块
+ls -la src/lib/security/
+```
+
+## 环境配置
+
+### 生产环境变量
+
+创建 `.env.production` 文件并配置以下变量：
+
+```bash
+# Resend API Configuration
+RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Company Email
+COMPANY_EMAIL=contact@novalon.cn
+
+# Next.js Configuration
+NEXT_PUBLIC_SITE_URL=https://www.novalon.cn
+
+# Sentry Error Monitoring (可选)
+NEXT_PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
+
+# NextAuth Configuration
+NEXTAUTH_SECRET=your-very-secure-secret-key-here
+NEXTAUTH_URL=https://www.novalon.cn
+
+# Admin User
+ADMIN_EMAIL=admin@novalon.cn
+ADMIN_PASSWORD=your-very-secure-password-here
+
+# Database
+DATABASE_URL=postgresql://user:password@host:port/database
+
+# File Upload
+UPLOAD_DIR=/var/www/uploads
+MAX_FILE_SIZE=10485760
+
+# Security Configuration
+# Rate Limiting (每分钟最大请求数)
+RATE_LIMIT_MAX_REQUESTS=5
+RATE_LIMIT_WINDOW_MS=60000
+
+# Captcha Configuration
+CAPTCHA_EXPIRY_MS=180000
+CAPTCHA_MAX_ATTEMPTS=3
+
+# Security Logging
+SECURITY_LOG_RETENTION_DAYS=90
+SECURITY_LOG_MAX_ENTRIES=5000
+```
+
+### 安全配置说明
+
+#### 频率限制配置
+
+生产环境建议配置：
+- `RATE_LIMIT_MAX_REQUESTS`: 5（每分钟最多5次请求）
+- `RATE_LIMIT_WINDOW_MS`: 60000（60秒时间窗口）
+
+开发环境建议配置：
+- `RATE_LIMIT_MAX_REQUESTS`: 100（宽松限制）
+- `RATE_LIMIT_WINDOW_MS`: 60000
+
+#### 验证码配置
+
+生产环境建议配置：
+- `CAPTCHA_EXPIRY_MS`: 180000（3分钟过期）
+- `CAPTCHA_MAX_ATTEMPTS`: 3（最多3次尝试）
+
+#### 安全日志配置
+
+生产环境建议配置：
+- `SECURITY_LOG_RETENTION_DAYS`: 90（保留90天）
+- `SECURITY_LOG_MAX_ENTRIES`: 5000（最多5000条记录）
+
+## 部署步骤
+
+### 步骤 1: 代码构建
+
+```bash
+# 拉取最新代码
+git pull origin main
+
+# 安装依赖
+npm install
+
+# 运行测试
+npm run test:unit
+
+# 构建生产版本
+npm run build
+```
+
+### 步骤 2: 环境变量配置
+
+```bash
+# 复制环境变量模板
+cp .env.example .env.production
+
+# 编辑环境变量
+nano .env.production
+```
+
+**重要提示**：
+- 确保 `NEXTAUTH_SECRET` 是一个强随机字符串
+- 确保 `ADMIN_PASSWORD` 是一个强密码
+- 确保 `RESEND_API_KEY` 是有效的 Resend API 密钥
+
+### 步骤 3: 数据库迁移
+
+```bash
+# 运行数据库迁移
+npm run db:migrate
+
+# 或者使用 Prisma
+npx prisma migrate deploy
+```
+
+### 步骤 4: 启动应用
+
+#### 使用 PM2（推荐）
+
+```bash
+# 安装 PM2
+npm install -g pm2
+
+# 启动应用
+pm2 start npm --name "novalon-website" -- start
+
+# 查看日志
+pm2 logs novalon-website
+
+# 查看状态
+pm2 status
+```
+
+#### 使用 Docker
+
+```bash
+# 构建镜像
+docker build -t novalon-website .
+
+# 运行容器
+docker run -d \
+  --name novalon-website \
+  -p 3000:3000 \
+  --env-file .env.production \
+  novalon-website
+```
+
+#### 使用 Systemd
+
+创建 `/etc/systemd/system/novalon-website.service` 文件：
+
+```ini
+[Unit]
+Description=Novalon Website
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/var/www/novalon-website
+ExecStart=/usr/bin/npm start
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+启动服务：
+
+```bash
+# 重载 systemd
+sudo systemctl daemon-reload
+
+# 启动服务
+sudo systemctl start novalon-website
+
+# 设置开机自启
+sudo systemctl enable novalon-website
+
+# 查看状态
+sudo systemctl status novalon-website
+```
+
+### 步骤 5: 配置反向代理（Nginx）
+
+创建 Nginx 配置文件 `/etc/nginx/sites-available/novalon.cn`：
+
+```nginx
+server {
+    listen 80;
+    server_name www.novalon.cn novalon.cn;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name www.novalon.cn novalon.cn;
+
+    ssl_certificate /etc/letsencrypt/live/novalon.cn/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/novalon.cn/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+
+    root /var/www/novalon-website;
+    index index.html;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location /api/admin/security {
+        # 限制访问安全监控端点
+        allow 192.168.1.0/24;
+        allow 10.0.0.0/8;
+        deny all;
+        
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+    }
+}
+```
+
+启用配置：
+
+```bash
+# 创建符号链接
+sudo ln -s /etc/nginx/sites-available/novalon.cn /etc/nginx/sites-enabled/
+
+# 测试配置
+sudo nginx -t
+
+# 重载 Nginx
+sudo systemctl reload nginx
+```
+
+### 步骤 6: 配置 SSL 证书
+
+使用 Let's Encrypt 获取免费 SSL 证书：
+
+```bash
+# 安装 Certbot
+sudo apt-get install certbot python3-certbot-nginx
+
+# 获取证书
+sudo certbot --nginx -d www.novalon.cn -d novalon.cn
+
+# 自动续期
+sudo certbot renew --dry-run
+```
+
+## 部署后验证
+
+### 功能验证
+
+#### 1. 基本功能测试
+
+访问联系页面并测试基本功能：
+
+```bash
+# 测试联系页面
+curl https://www.novalon.cn/contact
+
+# 测试API端点
+curl -X POST https://www.novalon.cn/api/contact \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Test","phone":"13800138000","email":"test@example.com","subject":"Test","message":"Test message"}'
+```
+
+#### 2. 安全功能测试
+
+验证安全功能是否正常工作：
+
+```bash
+# 测试频率限制
+for i in {1..10}; do
+  curl -X POST https://www.novalon.cn/api/contact \
+    -H "Content-Type: application/json" \
+    -d '{"name":"Test","phone":"13800138000","email":"test@example.com","subject":"Test","message":"Test message"}'
+  echo "Request $i completed"
+done
+```
+
+预期结果：前5个请求成功，后续请求被频率限制拦截。
+
+#### 3. 安全监控仪表板测试
+
+访问安全监控仪表板：
+
+```bash
+# 访问安全监控页面
+curl https://www.novalon.cn/admin/security
+```
+
+预期结果：显示安全统计信息和日志。
+
+### 性能验证
+
+#### 1. 响应时间测试
+
+```bash
+# 测试API响应时间
+time curl -X POST https://www.novalon.cn/api/contact \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Test","phone":"13800138000","email":"test@example.com","subject":"Test","message":"Test message"}'
+```
+
+预期结果：响应时间 < 500ms
+
+#### 2. 并发测试
+
+使用 Apache Bench 进行并发测试：
+
+```bash
+# 安装 Apache Bench
+sudo apt-get install apache2-utils
+
+# 并发测试
+ab -n 100 -c 10 https://www.novalon.cn/contact
+```
+
+预期结果：无错误，响应时间合理
+
+### 安全验证
+
+#### 1. SSL/TLS 配置检查
+
+```bash
+# 检查 SSL 配置
+openssl s_client -connect www.novalon.cn:443 -tls1_2
+openssl s_client -connect www.novalon.cn:443 -tls1_3
+```
+
+预期结果：支持 TLS 1.2 和 TLS 1.3
+
+#### 2. 安全头检查
+
+```bash
+# 检查安全头
+curl -I https://www.novalon.cn/contact
+```
+
+预期结果：包含以下安全头：
+- `X-Frame-Options: DENY`
+- `X-Content-Type-Options: nosniff`
+- `X-XSS-Protection: 1; mode=block`
+- `Strict-Transport-Security: max-age=31536000; includeSubDomains`
+
+#### 3. 漏洞扫描
+
+使用 OWASP ZAP 或类似工具进行安全扫描：
+
+```bash
+# 安装 OWASP ZAP
+sudo apt-get install zaproxy
+
+# 运行扫描
+zap-cli quick-scan --self-contained \
+  --start-options '-config api.disablekey=true' \
+  https://www.novalon.cn/contact
+```
+
+## 监控和维护
+
+### 应用监控
+
+#### 1. PM2 监控
+
+```bash
+# 查看应用状态
+pm2 status
+
+# 查看实时日志
+pm2 logs novalon-website --lines 100
+
+# 查看资源使用
+pm2 monit
+```
+
+#### 2. 日志监控
+
+```bash
+# 查看应用日志
+tail -f /var/log/novalon-website/app.log
+
+# 查看错误日志
+tail -f /var/log/novalon-website/error.log
+
+# 查看 Nginx 日志
+tail -f /var/log/nginx/access.log
+tail -f /var/log/nginx/error.log
+```
+
+#### 3. 安全监控
+
+定期访问安全监控仪表板：
+
+```bash
+# 访问安全监控页面
+https://www.novalon.cn/admin/security
+```
+
+关注以下指标：
+- 总请求数
+- 已拦截请求数
+- 验证码尝试次数
+- 频率限制命中次数
+- 恶意内容检测次数
+- 成功率
+
+### 定期维护任务
+
+#### 每日任务
+
+- 检查应用日志，查找错误和异常
+- 查看安全监控仪表板，关注高危事件
+- 检查磁盘空间使用情况
+
+#### 每周任务
+
+- 审查安全日志，识别异常模式
+- 检查频率限制统计，调整配置
+- 备份数据库和应用配置
+- 更新依赖包：`npm update`
+
+#### 每月任务
+
+- 审查和更新安全配置
+- 进行安全漏洞扫描
+- 测试备份恢复流程
+- 审查用户访问日志
+
+### 告警配置
+
+配置告警通知，当检测到以下情况时发送通知：
+
+1. **高危安全事件**：XSS攻击、SQL注入等
+2. **频繁的频率限制**：短时间内大量请求被拦截
+3. **应用错误**：应用崩溃或响应时间过长
+4. **磁盘空间不足**：磁盘使用率超过 80%
+
+## 故障排除
+
+### 常见问题
+
+#### 问题 1: 验证码总是失败
+
+**症状**：用户报告验证码总是验证失败
+
+**可能原因**：
+- 客户端和服务器时间不同步
+- 验证码过期时间设置过短
+- 浏览器缓存问题
+
+**解决方案**：
+```bash
+# 检查服务器时间
+date
+
+# 同步时间
+sudo ntpdate pool.ntp.org
+
+# 增加 CAPTCHA_EXPIRY_MS
+# 在 .env.production 中设置
+CAPTCHA_EXPIRY_MS=300000
+```
+
+#### 问题 2: 频率限制过于严格
+
+**症状**：正常用户被频率限制拦截
+
+**可能原因**：
+- RATE_LIMIT_MAX_REQUESTS 设置过低
+- 代理或负载均衡器导致IP识别问题
+- 时间窗口设置过短
+
+**解决方案**：
+```bash
+# 增加 RATE_LIMIT_MAX_REQUESTS
+# 在 .env.production 中设置
+RATE_LIMIT_MAX_REQUESTS=10
+
+# 增加 RATE_LIMIT_WINDOW_MS
+# 在 .env.production 中设置
+RATE_LIMIT_WINDOW_MS=120000
+```
+
+#### 问题 3: 安全监控仪表板无法访问
+
+**症状**：访问 `/admin/security` 返回 403 错误
+
+**可能原因**：
+- Nginx 配置限制了访问
+- 用户未登录
+- 权限配置问题
+
+**解决方案**：
+```bash
+# 检查 Nginx 配置
+sudo cat /etc/nginx/sites-available/novalon.cn
+
+# 更新允许的IP范围
+allow 192.168.1.0/24;
+allow 10.0.0.0/8;
+
+# 重载 Nginx
+sudo systemctl reload nginx
+```
+
+#### 问题 4: 应用启动失败
+
+**症状**：应用无法启动，PM2 显示错误
+
+**可能原因**：
+- 环境变量配置错误
+- 数据库连接失败
+- 端口被占用
+
+**解决方案**：
+```bash
+# 检查环境变量
+cat .env.production
+
+# 测试数据库连接
+psql -h host -U user -d database
+
+# 检查端口占用
+sudo lsof -i :3000
+
+# 查看详细错误日志
+pm2 logs novalon-website --err
+```
+
+### 日志分析
+
+#### 安全日志分析
+
+```bash
+# 查看最近的安全事件
+tail -100 /var/log/novalon-website/security.log
+
+# 统计高危事件
+grep "HIGH" /var/log/novalon-website/security.log | wc -l
+
+# 查找特定IP的活动
+grep "192.168.1.100" /var/log/novalon-website/security.log
+```
+
+#### 应用日志分析
+
+```bash
+# 查看错误日志
+grep "ERROR" /var/log/novalon-website/app.log
+
+# 查看慢请求
+grep "slow" /var/log/novalon-website/app.log
+
+# 统计请求数
+wc -l /var/log/novalon-website/access.log
+```
+
+## 回滚计划
+
+### 回滚触发条件
+
+在以下情况下考虑回滚：
+
+1. **严重安全漏洞**：发现无法快速修复的严重安全漏洞
+2. **性能严重下降**：响应时间增加超过 50%
+3. **功能严重故障**：核心功能无法使用
+4. **数据损坏**：数据库或文件系统损坏
+
+### 回滚步骤
+
+#### 步骤 1: 备份当前状态
+
+```bash
+# 备份数据库
+pg_dump -U user -h host database > backup_$(date +%Y%m%d_%H%M%S).sql
+
+# 备份应用文件
+tar -czf app_backup_$(date +%Y%m%d_%H%M%S).tar.gz /var/www/novalon-website
+
+# 备份配置文件
+cp .env.production .env.production.backup_$(date +%Y%m%d_%H%M%S)
+```
+
+#### 步骤 2: 停止应用
+
+```bash
+# 停止 PM2 应用
+pm2 stop novalon-website
+
+# 或停止 Systemd 服务
+sudo systemctl stop novalon-website
+```
+
+#### 步骤 3: 恢复之前的版本
+
+```bash
+# 恢复到之前的 Git 提交
+git checkout <previous-commit-hash>
+
+# 重新构建
+npm run build
+```
+
+#### 步骤 4: 恢复数据库（如果需要）
+
+```bash
+# 恢复数据库备份
+psql -U user -h host database < backup_YYYYMMDD_HHMMSS.sql
+```
+
+#### 步骤 5: 重新启动应用
+
+```bash
+# 启动 PM2 应用
+pm2 start novalon-website
+
+# 或启动 Systemd 服务
+sudo systemctl start novalon-website
+```
+
+#### 步骤 6: 验证回滚
+
+```bash
+# 测试基本功能
+curl https://www.novalon.cn/contact
+
+# 检查应用状态
+pm2 status
+
+# 查看日志
+pm2 logs novalon-website
+```
+
+## 附录
+
+### A. 安全配置最佳实践
+
+1. **使用强密码**：所有密码至少包含12个字符，包括大小写字母、数字和特殊字符
+2. **定期更新密钥**：每季度更新 API 密钥和会话密钥
+3. **最小权限原则**：数据库用户只授予必要的权限
+4. **网络隔离**：数据库和应用服务器之间使用私有网络
+5. **定期备份**：每天备份数据库，每周备份应用文件
+
+### B. 性能优化建议
+
+1. **启用缓存**：使用 Redis 缓存频繁访问的数据
+2. **CDN 加速**：使用 CDN 加速静态资源
+3. **数据库优化**：定期优化数据库表和索引
+4. **负载均衡**：使用负载均衡器分发请求
+5. **监控和调优**：持续监控性能指标，及时调优
+
+### C. 相关文档
+
+- [SECURITY.md](SECURITY.md) - 安全配置文档
+- [TESTING_REPORT.md](TESTING_REPORT.md) - 测试验证报告
+- [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) - 实施计划
+
+### D. 联系方式
+
+如有部署相关问题，请联系：
+
+- 技术支持：tech@novalon.cn
+- 安全团队：security@novalon.cn
+- 紧急联系：+86-xxx-xxxx-xxxx
+
+---
+
+**文档版本**: 1.0  
+**最后更新**: 2024-03-24  
+**维护者**: 技术团队