diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..1fa02e3 --- /dev/null +++ b/DEPLOYMENT.md @@ -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 + +# 重新构建 +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 +**维护者**: 技术团队