docs: 整理文档结构并创建索引（任务 2.3/20）

2026-04-12 16:24:51 +08:00
parent 1f52d47ed5
commit 5cd7d48bf2
33 changed files with 1140 additions and 1176 deletions
@@ -0,0 +1,505 @@
+# 生产环境部署和监控指南（轻量级版本）
+
+## 目录
+1. [环境准备](#环境准备)
+2. [部署流程](#部署流程)
+3. [轻量级监控配置](#轻量级监控配置)
+4. [告警配置](#告警配置)
+5. [维护和运维](#维护和运维)
+
+## 环境准备
+
+### 系统要求
+- Linux/Unix 服务器（推荐 Ubuntu 22.04+）
+- Node.js 18+
+- 至少 1GB RAM
+- 至少 5GB 磁盘空间
+
+### 必需的软件
+```bash
+# 安装 Node.js
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# 安装 PM2（进程管理器）
+npm install -g pm2
+```
+
+## 部署流程
+
+### 1. 配置环境变量
+
+复制并编辑生产环境配置：
+```bash
+cp .env.production .env.local
+```
+
+更新以下关键配置：
+- `RESEND_API_KEY`: Resend API 密钥
+- `NEXT_PUBLIC_SENTRY_DSN`: Sentry DSN
+- `NEXTAUTH_SECRET`: 认证密钥
+- `ADMIN_PASSWORD`: 管理员密码
+- `NEXT_PUBLIC_GA_MEASUREMENT_ID`: Google Analytics ID（可选）
+
+### 2. 安装依赖
+
+```bash
+npm ci --production=false
+```
+
+### 3. 运行测试
+
+```bash
+cd e2e
+TEST_ENV=development npx playwright test --reporter=list
+cd ..
+```
+
+### 4. 构建生产版本
+
+```bash
+npm run build
+```
+
+### 5. 启动生产服务器
+
+使用 PM2 启动服务：
+```bash
+pm2 start npm --name "novalon-website" -- start
+```
+
+### 6. 验证部署
+
+访问以下URL验证部署：
+- 网站: http://localhost:3000
+- 健康检查: http://localhost:3000/api/health
+- 管理后台: http://localhost:3000/admin
+
+## 轻量级监控配置
+
+### 监控架构
+
+采用轻量级监控方案，包含以下组件：
+
+1. **Sentry** - 错误监控和性能追踪
+2. **UptimeRobot** - 外部可用性监控
+3. **Google Analytics** - 用户行为和访问统计
+4. **健康检查API** - 内部服务状态
+5. **邮件告警** - 关键问题通知
+
+### 1. Sentry 错误监控
+
+#### 配置步骤
+
+Sentry 已经集成在项目中，只需配置环境变量：
+
+```env
+NEXT_PUBLIC_SENTRY_DSN=https://xxxxxxxxxxxxx@o4507xxxxx.ingest.sentry.io/xxxxxxxxxxxxx
+```
+
+#### 配置告警
+
+1. 登录 Sentry Dashboard
+2. 进入 Settings → Alerts
+3. 创建新的 Alert Rule：
+   - **Issue**: Critical Errors
+   - **Environment**: Production
+   - **Frequency**: Immediately
+   - **Email**: ops@novalon.cn
+
+#### 功能特性
+
+- JavaScript 错误捕获
+- 性能监控
+- 用户会话回放
+- 错误告警
+
+### 2. UptimeRobot 可用性监控
+
+#### 注册和配置
+
+1. 访问 https://uptimerobot.com/
+2. 注册免费账号
+3. 创建新的 Monitor：
+   - **Monitor Type**: HTTP(s)
+   - **URL**: https://www.novalon.cn
+   - **Monitoring Interval**: 5 minutes
+   - **Alert Contacts**: ops@novalon.cn
+
+#### 配置告警
+
+在 UptimeRobot 中设置：
+- **Down Alert**: 网站不可用时发送邮件
+- **Up Alert**: 网站恢复时发送邮件
+- **SSL Expiry**: SSL 证书过期提醒
+
+#### 推荐监控端点
+
+```yaml
+- 主页: https://www.novalon.cn
+- 健康检查: https://www.novalon.cn/api/health
+- 管理后台: https://www.novalon.cn/admin
+```
+
+### 3. Google Analytics 访问统计
+
+#### 获取跟踪 ID
+
+1. 访问 https://analytics.google.com/
+2. 创建新的 GA4 属性
+3. 复制测量 ID（格式：G-XXXXXXXXXX）
+
+#### 配置环境变量
+
+```env
+NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX
+```
+
+#### 集成到应用
+
+创建 `src/lib/analytics.ts`：
+```typescript
+export const GA_MEASUREMENT_ID = process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID;
+
+export const pageview = (url: string) => {
+  if (typeof window !== 'undefined' && GA_MEASUREMENT_ID) {
+    window.gtag('config', GA_MEASUREMENT_ID, {
+      page_path: url,
+    });
+  }
+};
+
+export const event = (action: string, category: string, label?: string) => {
+  if (typeof window !== 'undefined' && GA_MEASUREMENT_ID) {
+    window.gtag('event', action, {
+      event_category: category,
+      event_label: label,
+    });
+  }
+};
+```
+
+在 `src/app/layout.tsx` 中添加：
+```typescript
+import Script from 'next/script';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <head>
+        {process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID && (
+          <Script
+            src={`https://www.googletagmanager.com/gtag/js?id=${process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID}`}
+            strategy="afterInteractive"
+          />
+        )}
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### 4. 健康检查 API
+
+健康检查端点：`/api/health`
+
+**返回数据：**
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "version": "1.0.0",
+  "checks": {
+    "database": "connected",
+    "uptime": 123456
+  }
+}
+```
+
+## 告警配置
+
+### 告警策略
+
+只监控关键问题：
+- **服务不可用**（通过 UptimeRobot）
+- **严重错误**（通过 Sentry）
+- **数据库连接失败**（通过健康检查）
+
+### 告警阈值
+
+| 指标 | 阈值 | 告警级别 | 通知方式 |
+|--------|--------|----------|----------|
+| 网站可用性 | < 99.9% | Critical | UptimeRobot 邮件 |
+| 响应时间 | > 3秒 | Warning | UptimeRobot 邮件 |
+| JavaScript 错误 | > 10次/小时 | Critical | Sentry 邮件 |
+| 数据库连接 | 失败 | Critical | 手动检查 |
+
+### 邮件通知
+
+**Sentry 告警：**
+- 接收邮箱: ops@novalon.cn
+- 告警级别: Critical
+- 响应时间: 立即
+
+**UptimeRobot 告警：**
+- 接收邮箱: ops@novalon.cn
+- 告警类型: Down, Up, SSL Expiry
+- 响应时间: 立即
+
+## 维护和运维
+
+### 日常维护
+
+#### 每日检查
+- [ ] 查看 Sentry 错误报告
+- [ ] 检查 UptimeRobot 状态
+- [ ] 查看关键日志
+
+#### 每周检查
+- [ ] 分析 Google Analytics 数据
+- [ ] 检查性能趋势
+- [ ] 审查安全日志
+
+#### 每月检查
+- [ ] 更新依赖包
+- [ ] 备份数据库
+- [ ] 审查监控配置
+
+### 日志管理
+
+```bash
+# 查看应用日志
+pm2 logs novalon-website
+
+# 查看错误日志
+pm2 logs novalon-website --err
+
+# 清理旧日志
+pm2 flush
+```
+
+### 数据库备份
+
+```bash
+# 手动备份
+./scripts/backup.sh
+
+# 设置定时备份
+crontab -e
+# 添加以下行（每天凌晨 2 点备份）
+0 2 * * * /path/to/scripts/backup.sh
+```
+
+### 故障处理
+
+#### 1. 服务无法启动
+```bash
+# 检查 PM2 状态
+pm2 status
+
+# 查看错误日志
+pm2 logs novalon-website --err
+
+# 重启服务
+pm2 restart novalon-website
+```
+
+#### 2. 网站不可用
+1. 检查 UptimeRobot 告警
+2. 查看服务器状态
+3. 检查应用日志
+4. 重启服务
+
+#### 3. 错误激增
+1. 查看 Sentry 错误详情
+2. 分析错误模式
+3. 修复关键问题
+4. 部署热修复
+
+### 更新部署
+
+#### 零停机部署
+```bash
+# 1. 构建新版本
+npm run build
+
+# 2. 备份当前版本
+cp -r dist dist_backup
+
+# 3. 替换新版本
+rm -rf dist
+mv dist_new dist
+
+# 4. 重启服务（优雅重启）
+pm2 reload novalon-website
+```
+
+#### 回滚
+```bash
+# 回滚到上一个版本
+rm -rf dist
+mv dist_backup dist
+
+# 重启服务
+pm2 restart novalon-website
+```
+
+### 安全加固
+
+#### 防火墙配置
+```bash
+# 只允许必要端口
+ufw allow 22/tcp    # SSH
+ufw allow 80/tcp    # HTTP
+ufw allow 443/tcp   # HTTPS
+ufw enable
+```
+
+#### SSL/TLS 配置
+```bash
+# 使用 Let's Encrypt 获取免费证书
+certbot certonly --webroot -w /var/www/html -d www.novalon.cn
+
+# 配置 Nginx
+server {
+    listen 443 ssl;
+    server_name www.novalon.cn;
+
+    ssl_certificate /etc/letsencrypt/live/www.novalon.cn/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/www.novalon.cn/privkey.pem;
+
+    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;
+    }
+}
+```
+
+#### 定期更新
+```bash
+# 更新系统包
+sudo apt update && sudo apt upgrade -y
+
+# 更新 Node.js 依赖
+npm audit fix
+npm update
+
+# 更新 PM2
+pm2 update
+```
+
+## 性能优化
+
+### 1. 应用优化
+- 启用 gzip 压缩
+- 优化图片和静态资源
+- 使用 CDN 加速
+
+### 2. 数据库优化
+- 创建适当的索引
+- 定期清理旧数据
+- 优化查询语句
+
+### 3. 服务器优化
+- 调整 PM2 配置
+- 配置 swap
+- 优化文件系统
+
+## 应急预案
+
+### 1. 服务完全不可用
+1. 检查 UptimeRobot 告警
+2. 检查服务器状态
+3. 查看应用日志
+4. 尝试重启服务
+5. 如果无法恢复，切换到备用服务器
+
+### 2. 数据丢失
+1. 立即停止写入操作
+2. 从最近的备份恢复
+3. 验证数据完整性
+4. 分析丢失原因，防止再次发生
+
+### 3. 安全事件
+1. 立即隔离受影响系统
+2. 收集日志和证据
+3. 评估影响范围
+4. 修复安全漏洞
+5. 恢复服务
+6. 事后分析
+
+## 联系方式
+
+- **运维告警**: ops@novalon.cn
+- **业务咨询**: contact@novalon.cn
+
+## 附录
+
+### A. 常用命令
+```bash
+# 查看服务状态
+pm2 status
+
+# 重启服务
+pm2 restart novalon-website
+
+# 查看日志
+pm2 logs novalon-website
+
+# 检查磁盘空间
+df -h
+
+# 检查内存使用
+free -h
+
+# 检查进程
+ps aux | grep node
+```
+
+### B. 配置文件位置
+- 应用配置: `/etc/novalon-website/`
+- 日志文件: `~/.pm2/logs/`
+- 数据文件: `/var/lib/novalon-website/`
+- 备份文件: `/var/backups/novalon-website/`
+
+### C. 监控服务
+- **Sentry**: https://sentry.io/
+- **UptimeRobot**: https://uptimerobot.com/
+- **Google Analytics**: https://analytics.google.com/
+
+## 快速开始
+
+### 一键配置脚本
+
+```bash
+# 运行轻量级监控配置脚本
+chmod +x scripts/setup-lightweight-monitoring.sh
+./scripts/setup-lightweight-monitoring.sh
+```
+
+这个脚本会：
+- 检查 Sentry 配置
+- 配置 Google Analytics（可选）
+- 提供 UptimeRobot 配置指导
+- 创建健康检查端点
+- 配置 Sentry 告警
+
+### 部署脚本
+
+```bash
+# 运行生产部署脚本
+chmod +x scripts/deploy-production.sh
+./scripts/deploy-production.sh
+```
+
+这个脚本会：
+- 安装依赖
+- 运行测试
+- 构建生产版本
+- 启动服务
+- 健康检查