create-dp-koa 1.0.0

package/template/docs/TROUBLESHOOTING.md

@@ -0,0 +1,869 @@
+# 故障排除指南
+
+本指南提供 DP-Koa Framework 常见问题的诊断和解决方案，帮助您快速定位和解决问题。
+
+## 📋 目录
+
+- [故障诊断流程](#故障诊断流程)
+- [启动问题](#启动问题)
+- [数据库问题](#数据库问题)
+- [网络连接问题](#网络连接问题)
+- [性能问题](#性能问题)
+- [内存问题](#内存问题)
+- [权限问题](#权限问题)
+- [配置问题](#配置问题)
+- [日志分析](#日志分析)
+- [监控和告警](#监控和告警)
+- [紧急恢复](#紧急恢复)
+
+## 🔍 故障诊断流程
+
+### 1. 问题分类
+
+| 问题类型 | 症状 | 优先级 | 影响范围 |
+|----------|------|--------|----------|
+| 启动失败 | 应用无法启动 | 高 | 全部功能 |
+| 数据库连接 | 数据操作失败 | 高 | 核心功能 |
+| 网络问题 | API 请求失败 | 中 | 部分功能 |
+| 性能问题 | 响应缓慢 | 中 | 用户体验 |
+| 内存泄漏 | 内存持续增长 | 低 | 长期稳定性 |
+
+### 2. 诊断步骤
+
+```bash
+# 1. 检查应用状态
+curl http://localhost:3000/health
+
+# 2. 检查系统资源
+top
+free -h
+df -h
+
+# 3. 检查网络连接
+netstat -tulpn | grep :3000
+ss -tulpn | grep :3000
+
+# 4. 检查日志
+tail -f logs/error.$(date +%Y-%m-%d).log
+tail -f logs/log.$(date +%Y-%m-%d).log
+
+# 5. 检查进程状态
+ps aux | grep node
+pm2 status
+```
+
+## 🚀 启动问题
+
+### 1. 应用无法启动
+
+#### 症状
+- 应用启动后立即退出
+- 端口无法绑定
+- 依赖加载失败
+
+#### 诊断步骤
+
+```bash
+# 检查 Node.js 版本
+node --version
+npm --version
+
+# 检查依赖安装
+npm list --depth=0
+
+# 检查端口占用
+lsof -i :3000
+netstat -tulpn | grep :3000
+
+# 检查环境变量
+env | grep NODE_ENV
+env | grep DB_
+
+# 手动启动查看错误
+node dist/main.js
+```
+
+#### 常见解决方案
+
+**端口被占用**:
+```bash
+# 查找占用进程
+lsof -i :3000
+
+# 杀死进程
+kill -9 <PID>
+
+# 或使用其他端口
+PORT=3001 npm start
+```
+
+**依赖缺失**:
+```bash
+# 重新安装依赖
+rm -rf node_modules package-lock.json
+npm install
+
+# 检查依赖版本冲突
+npm ls
+```
+
+**环境变量问题**:
+```bash
+# 检查 .env 文件
+cat .env
+
+# 验证环境变量
+node -e "console.log(process.env.NODE_ENV)"
+```
+
+### 2. Docker 容器启动失败
+
+#### 症状
+- 容器启动后立即退出
+- 健康检查失败
+- 日志显示错误信息
+
+#### 诊断步骤
+
+```bash
+# 查看容器状态
+docker ps -a
+
+# 查看容器日志
+docker logs <container-name>
+
+# 进入容器调试
+docker exec -it <container-name> sh
+
+# 检查镜像
+docker images dp-koa-framework
+```
+
+#### 常见解决方案
+
+**内存不足**:
+```bash
+# 检查系统内存
+free -h
+
+# 增加 swap
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+```
+
+**权限问题**:
+```bash
+# 检查文件权限
+ls -la dist/main.js
+
+# 修复权限
+chmod +x dist/main.js
+chown -R nodejs:nodejs /app
+```
+
+## 🗄️ 数据库问题
+
+### 1. 数据库连接失败
+
+#### 症状
+- 应用启动时报数据库连接错误
+- API 请求返回数据库相关错误
+- 健康检查显示数据库不可用
+
+#### 诊断步骤
+
+```bash
+# 检查数据库服务状态
+systemctl status mysql
+docker ps | grep mysql
+
+# 测试数据库连接
+mysql -h localhost -u app_user -p app_db
+
+# 检查数据库配置
+cat .env | grep DB_
+
+# 检查网络连接
+telnet localhost 3306
+```
+
+#### 常见解决方案
+
+**MySQL 服务未启动**:
+```bash
+# 启动 MySQL 服务
+sudo systemctl start mysql
+sudo systemctl enable mysql
+
+# Docker 环境
+docker start mysql-container
+```
+
+**连接配置错误**:
+```bash
+# 检查配置文件
+cat .env
+
+# 验证连接参数
+mysql -h $DB_HOST -P $DB_PORT -u $DB_USERNAME -p$DB_PASSWORD $DB_DATABASE
+```
+
+**防火墙阻止**:
+```bash
+# 检查防火墙状态
+sudo ufw status
+sudo iptables -L
+
+# 开放数据库端口
+sudo ufw allow 3306
+```
+
+### 2. 数据库性能问题
+
+#### 症状
+- 查询响应缓慢
+- 连接池耗尽
+- 数据库 CPU 使用率高
+
+#### 诊断步骤
+
+```bash
+# 检查数据库状态
+mysql -u root -p -e "SHOW PROCESSLIST;"
+mysql -u root -p -e "SHOW STATUS LIKE 'Connections';"
+
+# 检查慢查询
+mysql -u root -p -e "SHOW VARIABLES LIKE 'slow_query_log';"
+mysql -u root -p -e "SHOW VARIABLES LIKE 'long_query_time';"
+```
+
+#### 常见解决方案
+
+**连接池配置**:
+```bash
+# 增加连接池大小
+export DB_POOL_MAX=50
+export DB_POOL_MIN=10
+```
+
+**查询优化**:
+```sql
+-- 添加索引
+CREATE INDEX idx_user_email ON users(email);
+CREATE INDEX idx_goods_status ON goods(status);
+
+-- 分析查询计划
+EXPLAIN SELECT * FROM users WHERE email = 'user@example.com';
+```
+
+### 3. 数据库迁移问题
+
+#### 症状
+- 迁移执行失败
+- 表结构不匹配
+- 数据丢失
+
+#### 诊断步骤
+
+```bash
+# 检查迁移状态
+npm run migration:show
+
+# 查看迁移日志
+tail -f logs/migration.log
+
+# 检查数据库结构
+mysql -u root -p -e "DESCRIBE users;"
+```
+
+#### 常见解决方案
+
+**回滚迁移**:
+```bash
+# 回滚到上一个版本
+npm run migration:revert
+
+# 手动修复数据
+mysql -u root -p app_db < backup.sql
+```
+
+## 🌐 网络连接问题
+
+### 1. API 请求失败
+
+#### 症状
+- HTTP 请求超时
+- 连接被拒绝
+- 响应状态码异常
+
+#### 诊断步骤
+
+```bash
+# 测试本地连接
+curl -v http://localhost:3000/health
+
+# 测试外部连接
+curl -v http://your-domain.com/health
+
+# 检查 DNS 解析
+nslookup your-domain.com
+dig your-domain.com
+
+# 检查路由
+traceroute your-domain.com
+```
+
+#### 常见解决方案
+
+**端口未开放**:
+```bash
+# 检查防火墙
+sudo ufw status
+sudo iptables -L
+
+# 开放端口
+sudo ufw allow 3000
+sudo ufw allow 80
+sudo ufw allow 443
+```
+
+**代理配置问题**:
+```bash
+# 检查 Nginx 配置
+sudo nginx -t
+sudo nginx -s reload
+
+# 检查代理设置
+curl -H "Host: your-domain.com" http://localhost:3000/health
+```
+
+### 2. SSL/TLS 问题
+
+#### 症状
+- HTTPS 连接失败
+- 证书错误
+- 安全警告
+
+#### 诊断步骤
+
+```bash
+# 检查证书
+openssl x509 -in /path/to/certificate.crt -text -noout
+
+# 测试 SSL 连接
+openssl s_client -connect your-domain.com:443
+
+# 检查证书链
+curl -vI https://your-domain.com
+```
+
+#### 常见解决方案
+
+**证书过期**:
+```bash
+# 更新 Let's Encrypt 证书
+sudo certbot renew
+
+# 手动更新证书
+sudo cp new-certificate.crt /etc/ssl/certs/
+sudo cp new-private.key /etc/ssl/private/
+sudo systemctl reload nginx
+```
+
+**证书配置错误**:
+```nginx
+# 检查 Nginx SSL 配置
+server {
+    listen 443 ssl;
+    ssl_certificate /path/to/certificate.crt;
+    ssl_certificate_key /path/to/private.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+}
+```
+
+## ⚡ 性能问题
+
+### 1. 响应缓慢
+
+#### 症状
+- API 响应时间过长
+- 用户界面加载缓慢
+- 系统资源使用率高
+
+#### 诊断步骤
+
+```bash
+# 检查系统负载
+top
+htop
+iostat -x 1
+
+# 检查网络延迟
+ping google.com
+traceroute api.your-domain.com
+
+# 检查应用性能
+curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/health
+```
+
+创建 `curl-format.txt`:
+```
+     time_namelookup:  %{time_namelookup}\n
+        time_connect:  %{time_connect}\n
+     time_appconnect:  %{time_appconnect}\n
+    time_pretransfer:  %{time_pretransfer}\n
+       time_redirect:  %{time_redirect}\n
+  time_starttransfer:  %{time_starttransfer}\n
+                     ----------\n
+          time_total:  %{time_total}\n
+```
+
+#### 常见解决方案
+
+**数据库查询优化**:
+```sql
+-- 添加索引
+CREATE INDEX idx_created_at ON orders(created_at);
+CREATE INDEX idx_user_status ON users(status);
+
+-- 优化查询
+EXPLAIN SELECT * FROM users WHERE status = 'active' ORDER BY created_at DESC LIMIT 10;
+```
+
+**缓存配置**:
+```bash
+# 启用 Redis 缓存
+export CACHE_TYPE=redis
+export REDIS_HOST=localhost
+export REDIS_PORT=6379
+
+# 调整缓存 TTL
+export CACHE_TTL=3600
+```
+
+**应用优化**:
+```bash
+# 启用集群模式
+pm2 start dist/main.js -i max
+
+# 调整内存限制
+export NODE_OPTIONS="--max-old-space-size=2048"
+```
+
+### 2. 内存使用过高
+
+#### 症状
+- 系统内存不足
+- 应用崩溃
+- 交换空间使用率高
+
+#### 诊断步骤
+
+```bash
+# 检查内存使用
+free -h
+top -p $(pgrep node)
+
+# 检查内存泄漏
+node --inspect dist/main.js
+# 然后在 Chrome 中打开 chrome://inspect
+
+# 检查交换使用
+swapon -s
+```
+
+#### 常见解决方案
+
+**增加系统内存**:
+```bash
+# 增加 swap
+sudo fallocate -l 4G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+
+# 永久挂载
+echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
+```
+
+**应用内存优化**:
+```bash
+# 限制 Node.js 内存
+export NODE_OPTIONS="--max-old-space-size=1024"
+
+# 启用垃圾回收
+export NODE_OPTIONS="--expose-gc"
+```
+
+## 🔐 权限问题
+
+### 1. 文件权限错误
+
+#### 症状
+- 无法读取配置文件
+- 日志文件无法写入
+- 上传文件失败
+
+#### 诊断步骤
+
+```bash
+# 检查文件权限
+ls -la .env
+ls -la logs/
+ls -la uploads/
+
+# 检查用户权限
+whoami
+groups
+id
+
+# 检查 SELinux 状态
+sestatus
+getenforce
+```
+
+#### 常见解决方案
+
+**修复文件权限**:
+```bash
+# 修复应用目录权限
+sudo chown -R app:app /app
+sudo chmod -R 755 /app
+
+# 修复日志目录权限
+sudo chmod 755 logs/
+sudo chmod 644 logs/*.log
+
+# 修复上传目录权限
+sudo chmod 755 uploads/
+sudo chmod 644 uploads/*
+```
+
+**SELinux 配置**:
+```bash
+# 临时禁用 SELinux
+sudo setenforce 0
+
+# 永久禁用 SELinux
+sudo sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
+```
+
+### 2. 数据库权限问题
+
+#### 症状
+- 数据库连接被拒绝
+- 表操作失败
+- 迁移执行失败
+
+#### 诊断步骤
+
+```bash
+# 测试数据库连接
+mysql -u app_user -p app_db
+
+# 检查用户权限
+mysql -u root -p -e "SHOW GRANTS FOR 'app_user'@'localhost';"
+
+# 检查数据库权限
+mysql -u root -p -e "SELECT * FROM mysql.user WHERE User='app_user';"
+```
+
+#### 常见解决方案
+
+**修复数据库权限**:
+```sql
+-- 重新授权
+GRANT ALL PRIVILEGES ON app_db.* TO 'app_user'@'localhost';
+FLUSH PRIVILEGES;
+
+-- 创建用户
+CREATE USER 'app_user'@'localhost' IDENTIFIED BY 'password';
+GRANT ALL PRIVILEGES ON app_db.* TO 'app_user'@'localhost';
+FLUSH PRIVILEGES;
+```
+
+## ⚙️ 配置问题
+
+### 1. 环境变量问题
+
+#### 症状
+- 配置未生效
+- 默认值被使用
+- 敏感信息泄露
+
+#### 诊断步骤
+
+```bash
+# 检查环境变量
+env | grep NODE_ENV
+env | grep DB_
+env | grep JWT_
+
+# 检查 .env 文件
+cat .env
+
+# 验证配置加载
+node -e "console.log(require('dotenv').config())"
+```
+
+#### 常见解决方案
+
+**修复环境变量**:
+```bash
+# 重新加载环境变量
+source .env
+
+# 检查变量格式
+echo $NODE_ENV
+echo $DB_HOST
+
+# 验证必需变量
+required_vars=("NODE_ENV" "DB_HOST" "DB_PASSWORD" "JWT_SECRET")
+for var in "${required_vars[@]}"; do
+    if [ -z "${!var}" ]; then
+        echo "Error: $var is not set"
+        exit 1
+    fi
+done
+```
+
+### 2. 配置文件错误
+
+#### 症状
+- 应用启动失败
+- 功能异常
+- 日志显示配置错误
+
+#### 诊断步骤
+
+```bash
+# 检查配置文件语法
+node -c dist/main.js
+
+# 检查 JSON 配置
+jq . config.json
+
+# 检查 YAML 配置
+yamllint config.yml
+```
+
+#### 常见解决方案
+
+**修复配置文件**:
+```bash
+# 备份配置文件
+cp config.json config.json.backup
+
+# 验证配置
+node -e "console.log(JSON.parse(require('fs').readFileSync('config.json', 'utf8')))"
+
+# 重置为默认配置
+cp config.json.example config.json
+```
+
+## 📊 日志分析
+
+### 1. 日志文件位置
+
+```bash
+# 应用日志
+logs/log.$(date +%Y-%m-%d).log
+logs/error.$(date +%Y-%m-%d).log
+logs/performance.$(date +%Y-%m-%d).log
+
+# 系统日志
+/var/log/syslog
+/var/log/nginx/access.log
+/var/log/nginx/error.log
+
+# Docker 日志
+docker logs <container-name>
+```
+
+### 2. 日志分析工具
+
+```bash
+# 实时查看日志
+tail -f logs/error.$(date +%Y-%m-%d).log
+
+# 搜索错误
+grep -i "error" logs/*.log
+
+# 统计错误数量
+grep -c "ERROR" logs/error.$(date +%Y-%m-%d).log
+
+# 分析访问模式
+awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -nr
+```
+
+### 3. 常见错误模式
+
+**数据库连接错误**:
+```
+ERROR: Database connection failed: connect ECONNREFUSED 127.0.0.1:3306
+```
+
+**内存不足错误**:
+```
+FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
+```
+
+**权限错误**:
+```
+Error: EACCES: permission denied, open '/app/logs/app.log'
+```
+
+## 🚨 监控和告警
+
+### 1. 健康检查
+
+```bash
+# 基础健康检查
+curl -f http://localhost:3000/health
+
+# 详细健康检查
+curl -f http://localhost:3000/health/detailed
+
+# 数据库健康检查
+curl -f http://localhost:3000/health/db
+
+# 缓存健康检查
+curl -f http://localhost:3000/health/cache
+```
+
+### 2. 监控脚本
+
+```bash
+#!/bin/bash
+# monitor.sh
+
+APP_URL="http://localhost:3000"
+EMAIL="admin@example.com"
+
+# 检查应用状态
+if ! curl -f $APP_URL/health > /dev/null 2>&1; then
+    echo "Application is down!" | mail -s "Alert: Application Down" $EMAIL
+fi
+
+# 检查磁盘空间
+DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')
+if [ $DISK_USAGE -gt 80 ]; then
+    echo "Disk usage is ${DISK_USAGE}%" | mail -s "Alert: High Disk Usage" $EMAIL
+fi
+
+# 检查内存使用
+MEMORY_USAGE=$(free | awk 'NR==2{printf "%.0f", $3*100/$2}')
+if [ $MEMORY_USAGE -gt 90 ]; then
+    echo "Memory usage is ${MEMORY_USAGE}%" | mail -s "Alert: High Memory Usage" $EMAIL
+fi
+```
+
+### 3. 告警配置
+
+```bash
+# 设置定时任务
+crontab -e
+
+# 每5分钟检查一次
+*/5 * * * * /path/to/monitor.sh
+
+# 每小时检查一次磁盘
+0 * * * * df -h | awk '$5 > 80 {print $0}' | mail -s "Disk Usage Alert" admin@example.com
+```
+
+## 🆘 紧急恢复
+
+### 1. 应用崩溃恢复
+
+```bash
+# 重启应用
+pm2 restart dp-koa-app
+
+# 或使用 Docker
+docker restart dp-koa-container
+
+# 检查恢复状态
+curl http://localhost:3000/health
+```
+
+### 2. 数据库恢复
+
+```bash
+# 从备份恢复
+mysql -u root -p app_db < backup_$(date +%Y%m%d).sql
+
+# 检查数据完整性
+mysql -u root -p -e "SELECT COUNT(*) FROM users;"
+```
+
+### 3. 系统恢复
+
+```bash
+# 重启服务
+sudo systemctl restart nginx
+sudo systemctl restart mysql
+
+# 清理临时文件
+sudo rm -rf /tmp/*
+sudo rm -rf /var/tmp/*
+
+# 释放内存
+echo 3 | sudo tee /proc/sys/vm/drop_caches
+```
+
+### 4. 回滚策略
+
+```bash
+# 代码回滚
+git checkout previous-stable-commit
+npm install
+npm run build
+pm2 restart dp-koa-app
+
+# 配置回滚
+cp config.json.backup config.json
+pm2 restart dp-koa-app
+
+# 数据库回滚
+mysql -u root -p app_db < backup_before_update.sql
+```
+
+## 📞 获取帮助
+
+### 1. 内部资源
+
+- **日志文件**: `logs/` 目录
+- **配置文件**: `.env`, `config.json`
+- **监控面板**: http://localhost:3000/metrics
+- **健康检查**: http://localhost:3000/health
+
+### 2. 外部资源
+
+- **GitHub Issues**: [项目问题跟踪](https://github.com/your-repo/issues)
+- **Stack Overflow**: [技术问答社区](https://stackoverflow.com/questions/tagged/node.js)
+- **Node.js 文档**: [官方文档](https://nodejs.org/docs/)
+
+### 3. 联系支持
+
+- **邮箱**: support@example.com
+- **紧急联系**: +86-xxx-xxxx-xxxx
+- **工作时间**: 周一至周五 9:00-18:00
+
+## 📚 相关文档
+
+- [快速开始指南](QUICK_START.md) - 5分钟快速上手
+- [安装配置指南](INSTALLATION_GUIDE.md) - 详细安装步骤
+- [开发指南](DEVELOPMENT_GUIDE.md) - 开发规范和最佳实践
+- [部署指南](DEPLOYMENT_GUIDE.md) - 生产环境部署
+
+---
+
+**紧急情况**:
+- 应用完全无法访问: 立即重启服务
+- 数据库连接失败: 检查数据库服务状态
+- 内存使用过高: 重启应用释放内存
+- 磁盘空间不足: 清理日志和临时文件
+
+