innomind-vita/docs/specs/env/nodejs-env.md

InnoMind Vita - AI-Powered Industrial Software Platform

# Node.js 环境配置规范

## 版本要求

### 1. Node.js
- 最低版本：18.0.0
- 推荐版本：20.x LTS
- 包管理器：pnpm 8.x

### 2. 运行时配置
```json
{
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=8.0.0"
  }
}
```

## 环境变量

### 1. 基础配置
```bash
# 运行环境
NODE_ENV=development|production|test

# 服务配置
PORT=3000
HOST=localhost

# 日志级别
LOG_LEVEL=debug|info|warn|error
```

### 2. 环境文件
```
.env                # 默认环境变量
.env.local         # 本地环境变量（不提交到git）
.env.development   # 开发环境变量
.env.test          # 测试环境变量
.env.production    # 生产环境变量
```

## 进程管理

### 1. 开发环境
- 使用 `nodemon` 实现热重载
- 使用 `ts-node` 直接运行 TypeScript
- 使用 `node-inspector` 调试

### 2. 生产环境
- 使用 `pm2` 进程管理
- 配置自动重启
- 启用性能监控
- 日志管理

## 配置示例

### 1. nodemon配置
```json
{
  "watch": ["src"],
  "ext": ".ts,.js",
  "ignore": [],
  "exec": "ts-node ./src/main.ts"
}
```

### 2. pm2配置
```json
{
  "apps": [
    {
      "name": "innomind-vita",
      "script": "dist/main.js",
      "instances": "max",
      "exec_mode": "cluster",
      "watch": false,
      "env": {
        "NODE_ENV": "production"
      },
      "merge_logs": true,
      "log_date_format": "YYYY-MM-DD HH:mm:ss"
    }
  ]
}
```

## 开发工具

### 1. 必需工具
- TypeScript
- ts-node
- nodemon
- node-inspector

### 2. 可选工具
- pm2
- node-gyp
- cross-env

## 安装步骤

### 1. 开发环境
```bash
# 安装开发依赖
pnpm add -D typescript ts-node nodemon @types/node

# 安装调试工具
pnpm add -D node-inspector
```

### 2. 生产环境
```bash
# 全局安装pm2
npm install -g pm2

# 安装生产依赖
pnpm add cross-env dotenv
```

## 启动脚本

### 1. 开发模式
```json
{
  "scripts": {
    "dev:node": "nodemon",
    "debug:node": "node --inspect -r ts-node/register src/main.ts",
    "build:node": "tsc -p tsconfig.node.json",
    "start:node": "node dist/main.js"
  }
}
```

### 2. 生产模式
```json
{
  "scripts": {
    "start:prod": "pm2 start pm2.config.json",
    "stop:prod": "pm2 stop innomind-vita",
    "restart:prod": "pm2 restart innomind-vita",
    "logs:prod": "pm2 logs innomind-vita"
  }
}
```

## 最佳实践

### 1. 性能优化
- 启用压缩
- 使用缓存
- 错误处理
- 日志分级

### 2. 安全配置
- 使用 HTTPS
- 设置 CORS
- 启用 Helmet
- 限制请求速率

### 3. 监控告警
- 性能监控
- 错误监控
- 资源监控
- 日志监控