novalon/novalon-website

Fork 0

Files

T

张翔 11e3147015 docs: add deployment documentation for security features

2026-03-24 11:44:53 +08:00

14 KiB

Raw Blame History

安全功能部署文档

部署前准备

系统要求

Node.js: 18.x 或更高版本
npm: 9.x 或更高版本
数据库: PostgreSQL 14+ 或 SQLite（开发环境）
邮件服务: Resend API 密钥
操作系统: Linux/macOS/Windows

依赖检查

在部署前，确保所有依赖都已正确安装：

# 检查 Node.js 版本
node --version  # 应该 >= 18.x

# 检查 npm 版本
npm --version  # 应该 >= 9.x

# 安装项目依赖
npm install

安全配置检查

确保以下安全配置文件已正确设置：

# 检查环境变量示例文件
ls -la .env.example

# 检查安全模块
ls -la src/lib/security/

环境配置

生产环境变量

创建 .env.production 文件并配置以下变量：

# 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: 代码构建

# 拉取最新代码
git pull origin main

# 安装依赖
npm install

# 运行测试
npm run test:unit

# 构建生产版本
npm run build

步骤 2: 环境变量配置

# 复制环境变量模板
cp .env.example .env.production

# 编辑环境变量
nano .env.production

重要提示：

确保 NEXTAUTH_SECRET 是一个强随机字符串
确保 ADMIN_PASSWORD 是一个强密码
确保 RESEND_API_KEY 是有效的 Resend API 密钥

步骤 3: 数据库迁移

# 运行数据库迁移
npm run db:migrate

# 或者使用 Prisma
npx prisma migrate deploy

步骤 4: 启动应用

使用 PM2（推荐）

# 安装 PM2
npm install -g pm2

# 启动应用
pm2 start npm --name "novalon-website" -- start

# 查看日志
pm2 logs novalon-website

# 查看状态
pm2 status

使用 Docker

# 构建镜像
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 文件：

[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

启动服务：

# 重载 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：

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;
    }
}

启用配置：

# 创建符号链接
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 证书：

# 安装 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. 基本功能测试

访问联系页面并测试基本功能：

# 测试联系页面
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. 安全功能测试

验证安全功能是否正常工作：

# 测试频率限制
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. 安全监控仪表板测试

访问安全监控仪表板：

# 访问安全监控页面
curl https://www.novalon.cn/admin/security

预期结果：显示安全统计信息和日志。

性能验证

1. 响应时间测试

# 测试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 进行并发测试：

# 安装 Apache Bench
sudo apt-get install apache2-utils

# 并发测试
ab -n 100 -c 10 https://www.novalon.cn/contact

预期结果：无错误，响应时间合理

安全验证

1. SSL/TLS 配置检查

# 检查 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. 安全头检查

# 检查安全头
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 或类似工具进行安全扫描：

# 安装 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 监控

# 查看应用状态
pm2 status

# 查看实时日志
pm2 logs novalon-website --lines 100

# 查看资源使用
pm2 monit

2. 日志监控

# 查看应用日志
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. 安全监控

定期访问安全监控仪表板：

# 访问安全监控页面
https://www.novalon.cn/admin/security

关注以下指标：

总请求数
已拦截请求数
验证码尝试次数
频率限制命中次数
恶意内容检测次数
成功率

定期维护任务

每日任务

检查应用日志，查找错误和异常
查看安全监控仪表板，关注高危事件
检查磁盘空间使用情况

每周任务

审查安全日志，识别异常模式
检查频率限制统计，调整配置
备份数据库和应用配置
更新依赖包：npm update

每月任务

审查和更新安全配置
进行安全漏洞扫描
测试备份恢复流程
审查用户访问日志

告警配置

配置告警通知，当检测到以下情况时发送通知：

高危安全事件：XSS攻击、SQL注入等
频繁的频率限制：短时间内大量请求被拦截
应用错误：应用崩溃或响应时间过长
磁盘空间不足：磁盘使用率超过 80%

故障排除

常见问题

问题 1: 验证码总是失败

症状：用户报告验证码总是验证失败

可能原因：

客户端和服务器时间不同步
验证码过期时间设置过短
浏览器缓存问题

解决方案：

# 检查服务器时间
date

# 同步时间
sudo ntpdate pool.ntp.org

# 增加 CAPTCHA_EXPIRY_MS
# 在 .env.production 中设置
CAPTCHA_EXPIRY_MS=300000

问题 2: 频率限制过于严格

症状：正常用户被频率限制拦截

可能原因：

RATE_LIMIT_MAX_REQUESTS 设置过低
代理或负载均衡器导致IP识别问题
时间窗口设置过短

解决方案：

# 增加 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 配置限制了访问
用户未登录
权限配置问题

解决方案：

# 检查 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 显示错误

可能原因：

环境变量配置错误
数据库连接失败
端口被占用

解决方案：

# 检查环境变量
cat .env.production

# 测试数据库连接
psql -h host -U user -d database

# 检查端口占用
sudo lsof -i :3000

# 查看详细错误日志
pm2 logs novalon-website --err

日志分析

安全日志分析

# 查看最近的安全事件
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

应用日志分析

# 查看错误日志
grep "ERROR" /var/log/novalon-website/app.log

# 查看慢请求
grep "slow" /var/log/novalon-website/app.log

# 统计请求数
wc -l /var/log/novalon-website/access.log

回滚计划

回滚触发条件

在以下情况下考虑回滚：

严重安全漏洞：发现无法快速修复的严重安全漏洞
性能严重下降：响应时间增加超过 50%
功能严重故障：核心功能无法使用
数据损坏：数据库或文件系统损坏

回滚步骤

步骤 1: 备份当前状态

# 备份数据库
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: 停止应用

# 停止 PM2 应用
pm2 stop novalon-website

# 或停止 Systemd 服务
sudo systemctl stop novalon-website

步骤 3: 恢复之前的版本

# 恢复到之前的 Git 提交
git checkout <previous-commit-hash>

# 重新构建
npm run build

步骤 4: 恢复数据库（如果需要）

# 恢复数据库备份
psql -U user -h host database < backup_YYYYMMDD_HHMMSS.sql

步骤 5: 重新启动应用

# 启动 PM2 应用
pm2 start novalon-website

# 或启动 Systemd 服务
sudo systemctl start novalon-website

步骤 6: 验证回滚

# 测试基本功能
curl https://www.novalon.cn/contact

# 检查应用状态
pm2 status

# 查看日志
pm2 logs novalon-website

附录

A. 安全配置最佳实践

使用强密码：所有密码至少包含12个字符，包括大小写字母、数字和特殊字符
定期更新密钥：每季度更新 API 密钥和会话密钥
最小权限原则：数据库用户只授予必要的权限
网络隔离：数据库和应用服务器之间使用私有网络
定期备份：每天备份数据库，每周备份应用文件

B. 性能优化建议

启用缓存：使用 Redis 缓存频繁访问的数据
CDN 加速：使用 CDN 加速静态资源
数据库优化：定期优化数据库表和索引
负载均衡：使用负载均衡器分发请求
监控和调优：持续监控性能指标，及时调优

C. 相关文档

SECURITY.md - 安全配置文档
TESTING_REPORT.md - 测试验证报告
IMPLEMENTATION_PLAN.md - 实施计划

D. 联系方式

如有部署相关问题，请联系：

技术支持：tech@novalon.cn
安全团队：security@novalon.cn
紧急联系：+86-xxx-xxxx-xxxx

文档版本: 1.0
最后更新: 2024-03-24
维护者: 技术团队

14 KiB Raw Blame History Unescape Escape

安全功能部署文档

目录

部署前准备

系统要求

依赖检查

安全配置检查

环境配置

生产环境变量

安全配置说明

频率限制配置

验证码配置

安全日志配置

部署步骤

步骤 1: 代码构建

步骤 2: 环境变量配置

步骤 3: 数据库迁移

步骤 4: 启动应用

使用 PM2（推荐）

使用 Docker

使用 Systemd

步骤 5: 配置反向代理（Nginx）

步骤 6: 配置 SSL 证书

部署后验证

功能验证

1. 基本功能测试

2. 安全功能测试

3. 安全监控仪表板测试

性能验证

1. 响应时间测试

2. 并发测试

安全验证

1. SSL/TLS 配置检查

2. 安全头检查

3. 漏洞扫描

监控和维护

应用监控

1. PM2 监控

2. 日志监控

3. 安全监控

定期维护任务

每日任务

每周任务

每月任务

告警配置

故障排除

常见问题

问题 1: 验证码总是失败

问题 2: 频率限制过于严格

问题 3: 安全监控仪表板无法访问

问题 4: 应用启动失败

日志分析

安全日志分析

应用日志分析

回滚计划

回滚触发条件

回滚步骤

步骤 1: 备份当前状态

步骤 2: 停止应用

步骤 3: 恢复之前的版本

步骤 4: 恢复数据库（如果需要）

步骤 5: 重新启动应用

步骤 6: 验证回滚

附录

A. 安全配置最佳实践

B. 性能优化建议

C. 相关文档

D. 联系方式

14 KiB

Raw Blame History