create-dp-koa 1.0.0

package/template/docs/INSTALLATION_GUIDE.md

@@ -0,0 +1,611 @@
+# 安装配置指南
+
+本指南提供 DP-Koa Framework 的详细安装和配置步骤，适用于不同的部署环境。
+
+## 📋 目录
+
+- [系统要求](#系统要求)
+- [环境准备](#环境准备)
+- [项目安装](#项目安装)
+- [环境配置](#环境配置)
+- [数据库配置](#数据库配置)
+- [缓存配置](#缓存配置)
+- [安全配置](#安全配置)
+- [监控配置](#监控配置)
+- [验证安装](#验证安装)
+- [常见问题](#常见问题)
+
+## 🖥️ 系统要求
+
+### 最低要求
+
+| 组件 | 最低版本 | 推荐版本 |
+|------|----------|----------|
+| Node.js | 18.0.0 | 20.0.0+ |
+| npm | 8.0.0 | 10.0.0+ |
+| MySQL | 8.0 | 8.0.30+ |
+| Redis | 6.0 | 7.0+ |
+| Docker | 20.0 | 24.0+ |
+
+### 操作系统支持
+
+- **Linux**: Ubuntu 20.04+, CentOS 8+, RHEL 8+
+- **macOS**: macOS 10.15+
+- **Windows**: Windows 10/11, Windows Server 2019+
+
+## 🔧 环境准备
+
+### 1. 安装 Node.js
+
+#### 使用 Node Version Manager (推荐)
+
+```bash
+# 安装 nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+
+# 重新加载终端
+source ~/.bashrc
+
+# 安装 Node.js 20
+nvm install 20
+nvm use 20
+nvm alias default 20
+```
+
+#### 直接安装
+
+**Ubuntu/Debian:**
+```bash
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+**CentOS/RHEL:**
+```bash
+curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
+sudo yum install -y nodejs
+```
+
+**macOS (使用 Homebrew):**
+```bash
+brew install node@20
+```
+
+**Windows:**
+下载并安装 [Node.js 官方安装包](https://nodejs.org/)
+
+### 2. 安装数据库
+
+#### MySQL 安装
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update
+sudo apt install mysql-server-8.0
+sudo mysql_secure_installation
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install mysql-server
+sudo systemctl start mysqld
+sudo systemctl enable mysqld
+sudo mysql_secure_installation
+```
+
+**Docker (推荐):**
+```bash
+docker run --name mysql -e MYSQL_ROOT_PASSWORD=root_password \
+  -e MYSQL_DATABASE=app_db -e MYSQL_USER=app_user \
+  -e MYSQL_PASSWORD=app_password -p 3306:3306 -d mysql:8.0
+```
+
+#### SQLite (开发环境)
+
+SQLite 通常随系统安装，如需手动安装：
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install sqlite3 libsqlite3-dev
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install sqlite sqlite-devel
+```
+
+### 3. 安装 Redis (可选)
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install redis-server
+sudo systemctl start redis-server
+sudo systemctl enable redis-server
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install redis
+sudo systemctl start redis
+sudo systemctl enable redis
+```
+
+**Docker:**
+```bash
+docker run --name redis -p 6379:6379 -d redis:7-alpine
+```
+
+### 4. 安装 Docker (可选)
+
+**Ubuntu/Debian:**
+```bash
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+sudo usermod -aG docker $USER
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install -y yum-utils
+sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
+sudo yum install docker-ce docker-ce-cli containerd.io
+sudo systemctl start docker
+sudo systemctl enable docker
+```
+
+## 📦 项目安装
+
+### 1. 克隆项目
+
+```bash
+git clone <your-repository-url>
+cd dp-koa-framework
+```
+
+### 2. 安装依赖
+
+```bash
+# 安装生产依赖
+npm install --production
+
+# 或安装所有依赖（包括开发依赖）
+npm install
+```
+
+### 3. 验证安装
+
+```bash
+# 检查 Node.js 版本
+node --version
+
+# 检查 npm 版本
+npm --version
+
+# 检查项目依赖
+npm list --depth=0
+```
+
+## ⚙️ 环境配置
+
+### 1. 创建环境配置文件
+
+```bash
+# 复制环境变量模板
+cp env.production.example .env
+```
+
+### 2. 基础配置
+
+编辑 `.env` 文件：
+
+```bash
+# 应用配置
+NODE_ENV=development
+PORT=3000
+APP_NAME=DP-Koa-Framework
+APP_VERSION=1.0.0
+
+# 日志配置
+LOG_LEVEL=info
+LOG_DIR=./logs
+
+# 安全配置
+JWT_SECRET=your-super-secret-jwt-key-here
+JWT_EXPIRES_IN=24h
+BCRYPT_ROUNDS=12
+
+# 缓存配置
+CACHE_TTL=3600
+CACHE_MAX_SIZE=1000
+```
+
+### 3. 数据库配置
+
+#### MySQL 配置
+
+```bash
+# 数据库类型
+DB_TYPE=mysql
+
+# MySQL 连接配置
+DB_HOST=localhost
+DB_PORT=3306
+DB_USERNAME=app_user
+DB_PASSWORD=app_password
+DB_DATABASE=app_db
+
+# 连接池配置
+DB_POOL_MIN=5
+DB_POOL_MAX=20
+DB_POOL_IDLE=10000
+```
+
+#### SQLite 配置
+
+```bash
+# 数据库类型
+DB_TYPE=sqlite
+
+# SQLite 配置
+DB_DATABASE=./database/app.db
+DB_SYNCHRONIZE=true
+```
+
+#### 内存数据库配置（开发/测试）
+
+```bash
+# 数据库类型
+DB_TYPE=memory
+
+# 内存数据库配置
+DB_SYNCHRONIZE=true
+DB_LOGGING=true
+```
+
+### 4. Redis 配置
+
+```bash
+# Redis 配置
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+REDIS_TTL=3600
+```
+
+## 🗄️ 数据库配置
+
+### 1. MySQL 数据库设置
+
+#### 创建数据库和用户
+
+```sql
+-- 连接到 MySQL
+mysql -u root -p
+
+-- 创建数据库
+CREATE DATABASE app_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- 创建用户
+CREATE USER 'app_user'@'localhost' IDENTIFIED BY 'app_password';
+CREATE USER 'app_user'@'%' IDENTIFIED BY 'app_password';
+
+-- 授权
+GRANT ALL PRIVILEGES ON app_db.* TO 'app_user'@'localhost';
+GRANT ALL PRIVILEGES ON app_db.* TO 'app_user'@'%';
+
+-- 刷新权限
+FLUSH PRIVILEGES;
+```
+
+#### 验证连接
+
+```bash
+# 测试数据库连接
+mysql -h localhost -u app_user -p app_db
+```
+
+### 2. SQLite 数据库设置
+
+```bash
+# 创建数据库目录
+mkdir -p database
+
+# 创建数据库文件（应用启动时自动创建）
+touch database/app.db
+```
+
+### 3. 运行数据库迁移
+
+```bash
+# 生产环境自动运行迁移
+NODE_ENV=production npm start
+
+# 或手动运行迁移
+npm run migration:run
+```
+
+## 🚀 缓存配置
+
+### 1. Redis 缓存配置
+
+#### 安装和启动 Redis
+
+```bash
+# Ubuntu/Debian
+sudo apt install redis-server
+sudo systemctl start redis-server
+sudo systemctl enable redis-server
+
+# CentOS/RHEL
+sudo yum install redis
+sudo systemctl start redis
+sudo systemctl enable redis
+```
+
+#### 配置 Redis
+
+编辑 `/etc/redis/redis.conf`：
+
+```bash
+# 绑定地址
+bind 127.0.0.1
+
+# 端口
+port 6379
+
+# 密码（可选）
+requirepass your_redis_password
+
+# 持久化
+save 900 1
+save 300 10
+save 60 10000
+```
+
+#### 验证 Redis
+
+```bash
+# 测试 Redis 连接
+redis-cli ping
+# 应该返回 PONG
+```
+
+### 2. 内存缓存配置
+
+如果使用内存缓存，无需额外配置：
+
+```bash
+# 在 .env 中设置
+CACHE_TYPE=memory
+CACHE_TTL=3600
+CACHE_MAX_SIZE=1000
+```
+
+## 🔒 安全配置
+
+### 1. JWT 配置
+
+```bash
+# 生成强密钥
+openssl rand -base64 64
+
+# 在 .env 中设置
+JWT_SECRET=your-generated-secret-key
+JWT_EXPIRES_IN=24h
+JWT_REFRESH_EXPIRES_IN=7d
+```
+
+### 2. 密码加密配置
+
+```bash
+# bcrypt 轮数（推荐 12-15）
+BCRYPT_ROUNDS=12
+```
+
+### 3. CORS 配置
+
+```bash
+# CORS 配置
+CORS_ORIGIN=http://localhost:3000
+CORS_CREDENTIALS=true
+CORS_MAX_AGE=86400
+```
+
+### 4. 速率限制
+
+```bash
+# API 速率限制
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX_REQUESTS=100
+```
+
+## 📊 监控配置
+
+### 1. 日志配置
+
+```bash
+# 日志级别
+LOG_LEVEL=info
+
+# 日志目录
+LOG_DIR=./logs
+
+# 日志轮转
+LOG_MAX_SIZE=10m
+LOG_MAX_FILES=5
+```
+
+### 2. 健康检查配置
+
+```bash
+# 健康检查端点
+HEALTH_CHECK_ENABLED=true
+HEALTH_CHECK_PATH=/health
+
+# 监控端点
+METRICS_ENABLED=true
+METRICS_PATH=/metrics
+```
+
+### 3. Prometheus 配置
+
+创建 `docker/prometheus/prometheus.yml`：
+
+```yaml
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: 'dp-koa-framework'
+    static_configs:
+      - targets: ['app:3000']
+    metrics_path: '/metrics'
+    scrape_interval: 5s
+```
+
+## ✅ 验证安装
+
+### 1. 启动应用
+
+```bash
+# 开发模式
+npm run dev
+
+# 生产模式
+npm run build
+npm start
+```
+
+### 2. 健康检查
+
+```bash
+# 检查应用状态
+curl http://localhost:3000/health
+
+# 检查数据库连接
+curl http://localhost:3000/health/db
+
+# 检查缓存状态
+curl http://localhost:3000/health/cache
+```
+
+### 3. API 测试
+
+```bash
+# 测试用户 API
+curl http://localhost:3000/api/users
+
+# 测试商品 API
+curl http://localhost:3000/api/goods
+
+# 查看 Swagger 文档
+open http://localhost:3000/swagger-ui
+```
+
+### 4. 运行测试
+
+```bash
+# 运行所有测试
+npm test
+
+# 运行特定测试
+npm run test:framework
+npm run test:service
+npm run test:integration
+```
+
+## ❓ 常见问题
+
+### 1. 数据库连接失败
+
+**问题**: 无法连接到数据库
+
+**解决方案**:
+```bash
+# 检查数据库服务状态
+sudo systemctl status mysql
+
+# 检查连接配置
+mysql -h localhost -u app_user -p app_db
+
+# 检查防火墙
+sudo ufw status
+```
+
+### 2. 端口被占用
+
+**问题**: 端口 3000 被占用
+
+**解决方案**:
+```bash
+# 查找占用进程
+lsof -i :3000
+
+# 杀死进程
+kill -9 <PID>
+
+# 或使用其他端口
+PORT=3001 npm start
+```
+
+### 3. 依赖安装失败
+
+**问题**: npm install 失败
+
+**解决方案**:
+```bash
+# 清理缓存
+npm cache clean --force
+
+# 删除 node_modules
+rm -rf node_modules package-lock.json
+
+# 重新安装
+npm install
+```
+
+### 4. 权限问题
+
+**问题**: 文件权限错误
+
+**解决方案**:
+```bash
+# 修复文件权限
+sudo chown -R $USER:$USER .
+chmod -R 755 .
+```
+
+### 5. 内存不足
+
+**问题**: 构建时内存不足
+
+**解决方案**:
+```bash
+# 增加 Node.js 内存限制
+export NODE_OPTIONS="--max-old-space-size=4096"
+
+# 或使用 swap
+sudo fallocate -l 2G /swapfile
+sudo chmod 600 /swapfile
+sudo mkswap /swapfile
+sudo swapon /swapfile
+```
+
+## 📚 下一步
+
+安装完成后，建议您：
+
+1. **阅读开发指南**: [开发指南](DEVELOPMENT_GUIDE.md)
+2. **了解注解系统**: [注解系统指南](ENTERPRISE_ANNOTATION_SYSTEM_GUIDE.md)
+3. **学习服务层设计**: [服务层指南](SERVICE_PATTERN_GUIDE.md)
+4. **查看部署指南**: [部署指南](ENTERPRISE_DEPLOYMENT_GUIDE.md)
+
+---
+
+**相关链接**:
+- [快速开始指南](QUICK_START.md) - 5分钟快速上手
+- [开发指南](DEVELOPMENT_GUIDE.md) - 开发规范和最佳实践
+- [故障排除指南](TROUBLESHOOTING.md) - 常见问题解决
+
+