create-dp-koa 1.0.0

package/template/docs/ENTERPRISE_LOGGING_SYSTEM_GUIDE.md

@@ -0,0 +1,494 @@
+# 企业级日志系统文档
+
+## 概述
+
+本文档描述了DP-Koa框架的企业级日志系统实现，该系统符合企业项目的要求，提供了完整的日志记录、监控、审计和分析功能。
+
+## 系统特性
+
+### ✅ 企业级要求满足情况
+
+| 要求 | 状态 | 说明 |
+|------|------|------|
+| 结构化日志 | ✅ | JSON格式，包含完整的上下文信息 |
+| 请求追踪 | ✅ | 每个请求分配唯一ID，支持分布式追踪 |
+| 敏感信息脱敏 | ✅ | 自动识别并脱敏敏感字段 |
+| 性能监控 | ✅ | 记录请求耗时、数据库操作等性能指标 |
+| 安全审计 | ✅ | 记录所有安全相关事件和操作 |
+| 日志分类 | ✅ | 按类型分离：结构化、错误、审计、性能 |
+| 日志管理 | ✅ | 提供日志查询、下载、清理等管理功能 |
+| 实时监控 | ✅ | 支持实时日志流和SSE |
+
+## 架构设计
+
+### 核心组件
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    企业级日志系统架构                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │  日志中间件   │  │  日志器类    │  │  布局器      │          │
+│  │             │  │             │  │             │          │
+│  │ • 请求追踪   │  │ • 上下文管理 │  │ • JSON格式化 │          │
+│  │ • 性能监控   │  │ • 脱敏处理   │  │ • 敏感信息   │          │
+│  │ • 安全审计   │  │ • 分类记录   │  │   脱敏      │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │  结构化日志   │  │   错误日志   │  │   审计日志   │          │
+│  │             │  │             │  │             │          │
+│  │ • 所有日志   │  │ • 错误信息   │  │ • 安全事件   │          │
+│  │ • JSON格式   │  │ • 堆栈跟踪   │  │ • 操作记录   │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │  性能日志    │  │  管理接口    │  │  实时流      │          │
+│  │             │  │             │  │             │          │
+│  │ • 请求耗时   │  │ • 查询统计   │  │ • SSE流     │          │
+│  │ • 数据库操作 │  │ • 文件下载   │  │ • 实时监控   │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 日志格式
+
+### 结构化日志格式
+
+```json
+{
+  "timestamp": "2025-01-25T10:30:00.000Z",
+  "level": "INFO",
+  "category": "default",
+  "message": "Request completed",
+  "service": "dp-koa-framework",
+  "version": "1.0.0",
+  "environment": "production",
+  "requestId": "550e8400-e29b-41d4-a716-446655440000",
+  "userId": "user123",
+  "sessionId": "session456",
+  "traceId": "trace789",
+  "spanId": "span101",
+  "pid": 12345,
+  "hostname": "server-01",
+  "method": "GET",
+  "url": "/api/users",
+  "status": 200,
+  "duration": "150ms",
+  "responseSize": 1024
+}
+```
+
+### 日志级别
+
+| 级别 | 用途 | 示例 |
+|------|------|------|
+| `TRACE` | 详细跟踪信息 | 函数调用、变量值 |
+| `DEBUG` | 调试信息 | 开发环境详细信息 |
+| `INFO` | 一般信息 | 请求处理、业务操作 |
+| `WARN` | 警告信息 | 性能问题、配置问题 |
+| `ERROR` | 错误信息 | 异常、失败操作 |
+| `FATAL` | 致命错误 | 系统崩溃、严重错误 |
+
+## 敏感信息脱敏
+
+### 自动脱敏字段
+
+系统会自动识别并脱敏以下敏感字段：
+
+```typescript
+const SENSITIVE_FIELDS = [
+  'password', 'token', 'secret', 'key', 'auth', 'credential',
+  'ssn', 'socialSecurityNumber', 'creditCard', 'cardNumber',
+  'phone', 'email', 'address', 'ip', 'mac'
+]
+```
+
+### 脱敏示例
+
+**原始数据：**
+```json
+{
+  "username": "john_doe",
+  "password": "secret123",
+  "email": "john@example.com",
+  "phone": "13800138000"
+}
+```
+
+**脱敏后：**
+```json
+{
+  "username": "john_doe",
+  "password": "***REDACTED***",
+  "email": "***REDACTED***",
+  "phone": "***REDACTED***"
+}
+```
+
+## 日志分类
+
+### 1. 结构化日志 (`/logs/structured/`)
+- **用途**: 所有应用日志的主要存储
+- **格式**: JSON格式
+- **保留**: 30天，50MB/文件
+- **内容**: 请求处理、业务操作、系统状态
+
+### 2. 错误日志 (`/logs/error/`)
+- **用途**: 专门记录错误和异常
+- **格式**: JSON格式
+- **保留**: 15天，20MB/文件
+- **内容**: 错误堆栈、异常详情、失败操作
+
+### 3. 审计日志 (`/logs/audit/`)
+- **用途**: 安全审计和合规要求
+- **格式**: JSON格式
+- **保留**: 20天，30MB/文件
+- **内容**: 用户操作、权限变更、安全事件
+
+### 4. 性能日志 (`/logs/performance/`)
+- **用途**: 性能监控和优化
+- **格式**: JSON格式
+- **保留**: 15天，25MB/文件
+- **内容**: 请求耗时、数据库操作、性能指标
+
+## API接口
+
+### 日志管理接口
+
+#### 1. 获取日志统计
+```http
+GET /admin/logs/stats
+```
+
+**响应示例：**
+```json
+{
+  "code": 0,
+  "data": {
+    "totalFiles": 15,
+    "totalSize": 1048576,
+    "fileTypes": {
+      ".log": { "count": 12, "size": 800000 },
+      ".json": { "count": 3, "size": 248576 }
+    },
+    "lastModified": "2025-01-25T10:30:00.000Z"
+  },
+  "message": "日志统计信息获取成功"
+}
+```
+
+#### 2. 获取日志文件列表
+```http
+GET /admin/logs/files
+```
+
+**响应示例：**
+```json
+{
+  "code": 0,
+  "data": [
+    {
+      "name": "structured.2025-01-25.log",
+      "size": 1024000,
+      "modified": "2025-01-25T10:30:00.000Z",
+      "created": "2025-01-25T00:00:00.000Z",
+      "type": ".log"
+    }
+  ],
+  "message": "日志文件列表获取成功"
+}
+```
+
+#### 3. 下载日志文件
+```http
+GET /admin/logs/download/{filename}
+```
+
+#### 4. 查看日志内容
+```http
+GET /admin/logs/view/{filename}?lines=100&offset=0
+```
+
+**参数：**
+- `lines`: 返回行数（默认100）
+- `offset`: 起始行号（默认0）
+
+#### 5. 清理过期日志
+```http
+POST /admin/logs/clean
+Content-Type: application/json
+
+{
+  "days": 30
+}
+```
+
+#### 6. 设置日志级别
+```http
+POST /admin/logs/level
+Content-Type: application/json
+
+{
+  "level": "info",
+  "category": "default"
+}
+```
+
+#### 7. 实时日志流
+```http
+GET /admin/logs/stream/{filename}
+```
+
+**响应类型**: `text/event-stream`
+
+## 使用指南
+
+### 1. 基本日志记录
+
+```typescript
+import { logger } from '../framework/utils/logger'
+
+// 基本日志
+logger.info('用户登录成功', { userId: '123', ip: '192.168.1.1' })
+logger.warn('数据库连接超时', { timeout: 5000 })
+logger.error('文件上传失败', error, { filename: 'test.jpg' })
+
+// 业务日志
+logger.business('ORDER_CREATED', {
+  orderId: 'ORD-001',
+  userId: '123',
+  amount: 99.99
+})
+
+// 安全审计
+logger.audit('USER_LOGIN', '/api/auth/login', {
+  userId: '123',
+  ip: '192.168.1.1',
+  userAgent: 'Mozilla/5.0...'
+})
+
+// 性能监控
+logger.performance('DATABASE_QUERY', 150, {
+  query: 'SELECT * FROM users',
+  rows: 100
+})
+
+// 安全事件
+logger.security('FAILED_LOGIN', 'medium', {
+  username: 'admin',
+  ip: '192.168.1.1',
+  attempts: 3
+})
+```
+
+### 2. 请求上下文日志
+
+```typescript
+// 在控制器中使用
+export class UserController extends BaseController {
+  async getUser(ctx: Context) {
+    // 自动包含请求ID和用户信息
+    ctx.logger.info('获取用户信息', { userId: ctx.params.id })
+    
+    try {
+      const user = await this.userService.findById(ctx.params.id)
+      ctx.logger.business('USER_VIEWED', { userId: ctx.params.id })
+      
+      ctx.body = { code: 0, data: user }
+    } catch (error) {
+      ctx.logger.error('获取用户失败', error, { userId: ctx.params.id })
+      throw error
+    }
+  }
+}
+```
+
+### 3. 自定义日志器
+
+```typescript
+import { createRequestLogger } from '../framework/utils/logger'
+
+// 创建带请求ID的日志器
+const requestLogger = createRequestLogger('req-123')
+requestLogger.setRequestContext('req-123', 'user456', 'session789')
+
+// 使用自定义日志器
+requestLogger.info('处理用户请求', { action: 'update_profile' })
+```
+
+## 配置说明
+
+### 环境变量
+
+```bash
+# 日志级别
+LOG_LEVEL=info
+
+# 日志目录
+LOG_DIR=./logs
+
+# 服务名称
+SERVICE_NAME=dp-koa-framework
+
+# 服务版本
+SERVICE_VERSION=1.0.0
+
+# 环境
+NODE_ENV=production
+```
+
+### 日志配置
+
+```typescript
+// src/framework/utils/logger.ts
+log4js.configure({
+  pm2: true,
+  appenders: {
+    structured: {
+      type: 'dateFile',
+      filename: getFullPath("/logs/structured"),
+      pattern: 'yyyy-MM-dd.log',
+      maxLogSize: '50M',
+      backups: 30
+    },
+    // ... 其他配置
+  },
+  categories: {
+    default: {
+      appenders: ['console', 'structured'],
+      level: 'debug'
+    }
+  }
+})
+```
+
+## 监控和告警
+
+### 1. 性能监控
+
+系统自动记录以下性能指标：
+- HTTP请求耗时
+- 数据库查询时间
+- 缓存操作耗时
+- 内存使用情况
+
+### 2. 错误监控
+
+自动记录：
+- 未捕获异常
+- 数据库连接错误
+- 第三方服务调用失败
+- 业务逻辑错误
+
+### 3. 安全监控
+
+记录安全事件：
+- 登录失败
+- 权限越界
+- 异常访问模式
+- 敏感操作
+
+## 最佳实践
+
+### 1. 日志记录原则
+
+- **结构化**: 使用JSON格式，便于解析和分析
+- **上下文**: 包含足够的上下文信息
+- **级别**: 合理使用日志级别
+- **性能**: 避免在热路径中记录过多日志
+
+### 2. 敏感信息处理
+
+- 自动脱敏敏感字段
+- 避免记录完整密码或令牌
+- 记录操作而非数据内容
+
+### 3. 性能考虑
+
+- 异步写入日志
+- 批量处理日志
+- 合理设置日志级别
+- 定期清理过期日志
+
+### 4. 安全考虑
+
+- 日志文件权限控制
+- 传输加密
+- 访问审计
+- 备份策略
+
+## 故障排查
+
+### 常见问题
+
+1. **日志文件过大**
+   - 检查日志级别设置
+   - 调整文件大小限制
+   - 增加日志轮转频率
+
+2. **性能影响**
+   - 降低日志级别
+   - 使用异步写入
+   - 优化日志格式
+
+3. **磁盘空间不足**
+   - 设置自动清理
+   - 压缩历史日志
+   - 调整保留策略
+
+### 调试技巧
+
+1. **查看实时日志**
+   ```bash
+   tail -f logs/structured.2025-01-25.log
+   ```
+
+2. **搜索特定请求**
+   ```bash
+   grep "requestId:550e8400" logs/structured.2025-01-25.log
+   ```
+
+3. **分析性能问题**
+   ```bash
+   grep "PERFORMANCE" logs/performance.2025-01-25.log | jq '.duration'
+   ```
+
+## 扩展功能
+
+### 1. 日志聚合
+
+可以集成ELK Stack：
+- **Elasticsearch**: 日志存储和搜索
+- **Logstash**: 日志收集和处理
+- **Kibana**: 日志可视化和分析
+
+### 2. 告警系统
+
+集成告警功能：
+- 错误率阈值告警
+- 性能指标告警
+- 安全事件告警
+
+### 3. 日志分析
+
+支持高级分析：
+- 用户行为分析
+- 性能趋势分析
+- 安全威胁检测
+
+## 总结
+
+DP-Koa框架的企业级日志系统提供了完整的日志记录、监控、审计和分析功能，满足企业项目的各种需求：
+
+- ✅ **结构化日志**: JSON格式，便于解析和分析
+- ✅ **请求追踪**: 完整的请求链路追踪
+- ✅ **敏感信息脱敏**: 自动识别和脱敏敏感数据
+- ✅ **性能监控**: 详细的性能指标记录
+- ✅ **安全审计**: 完整的安全事件记录
+- ✅ **日志管理**: 丰富的管理接口和功能
+- ✅ **实时监控**: 支持实时日志流
+- ✅ **高可用性**: 异步写入，不影响业务性能
+
+该系统为企业级应用提供了可靠的日志基础设施，支持运维监控、安全审计、性能优化和故障排查等各个方面。
+
+

package/template/docs/ENVIRONMENT_CONFIG_EXAMPLE.md

@@ -0,0 +1,69 @@
+# 环境配置文件示例
+
+## 开发环境 (.env.development)
+```
+NODE_ENV=development
+
+# 数据库配置
+db_enable=1
+db_host=127.0.0.1
+db_port=3306
+db_username=root
+db_password=123456
+db_database=ytkj_service
+db_memory=0
+
+# 新注解系统配置
+USE_NEW_ANNOTATION_SYSTEM=1
+
+# 日志配置
+LOG_LEVEL=info
+```
+
+## 生产环境 (.env.production)
+```
+NODE_ENV=production
+
+# 数据库配置
+db_enable=1
+db_host=your-production-host
+db_port=3306
+db_username=your-username
+db_password=your-password
+db_database=ytkj_service_prod
+db_memory=0
+
+# 新注解系统配置（生产环境建议先禁用）
+USE_NEW_ANNOTATION_SYSTEM=0
+
+# 日志配置
+LOG_LEVEL=warn
+```
+
+## 测试环境 (.env.test)
+```
+NODE_ENV=test
+
+# 数据库配置
+db_enable=1
+db_memory=1
+
+# 新注解系统配置
+USE_NEW_ANNOTATION_SYSTEM=1
+
+# 日志配置
+LOG_LEVEL=error
+```
+
+## 配置说明
+
+### USE_NEW_ANNOTATION_SYSTEM
+- `1`: 启用新注解处理器系统
+- `0`: 使用旧注解系统（默认）
+
+### 迁移建议
+1. 开发环境：启用新系统进行测试
+2. 测试环境：启用新系统进行验证
+3. 生产环境：先禁用，逐步迁移后启用
+
+