张翔
498bb3a3c8
- 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
733 lines
14 KiB
Markdown
733 lines
14 KiB
Markdown
# 安全功能部署文档
|
||
|
||
## 目录
|
||
|
||
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
|
||
**维护者**: 技术团队
|