# 安全功能部署文档

## 目录

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  
**维护者**: 技术团队