wwjcloud-nest-v1/docs/CONFIG_SETUP.md

# WWJCloud Backend 配置设置指南

## 📋 概述

本文档说明如何设置 WWJCloud Backend 的环境变量配置。

## 🚀 快速开始

### 1. 复制配置文件

```bash
# 复制示例配置文件
cp env.example .env

# 或者复制特定环境的配置
cp env.development .env  # 开发环境
cp env.production .env   # 生产环境
```

### 2. 修改配置

根据你的实际环境修改 `.env` 文件中的配置项。

## 📁 配置文件说明

### 配置文件类型

- `env.example` - 配置示例文件（包含所有配置项）
- `env.development` - 开发环境配置
- `env.production` - 生产环境配置
- `.env` - 实际使用的配置文件（需要手动创建）

### 配置优先级

1. **环境变量** (最高优先级)
2. **默认配置** (最低优先级)

## 🔧 必需配置项

### 应用基础配置

```bash
# 应用名称
APP_NAME=WWJCloud Backend

# 应用端口
PORT=3000

# 运行环境
NODE_ENV=development  # development, production, test
```

### 数据库配置

```bash
# 数据库主机
DB_HOST=localhost

# 数据库端口
DB_PORT=3306

# 数据库用户名
DB_USERNAME=root

# 数据库密码
DB_PASSWORD=your_password

# 数据库名称
DB_DATABASE=wwjcloud

# 是否同步数据库结构（生产环境必须为 false）
DB_SYNC=false

# 是否启用数据库日志
DB_LOGGING=false
```

### Redis 配置

```bash
# Redis 主机
REDIS_HOST=localhost

# Redis 端口
REDIS_PORT=6379

# Redis 密码
REDIS_PASSWORD=

# Redis 数据库编号
REDIS_DB=0

# Redis 键前缀
REDIS_KEY_PREFIX=wwjcloud:
```

### JWT 配置

```bash
# JWT 密钥（生产环境必须修改）
JWT_SECRET=your-super-secret-jwt-key

# JWT 过期时间
JWT_EXPIRES_IN=7d

# JWT 算法
JWT_ALGORITHM=HS256
```

## 🌍 环境特定配置

### 开发环境

```bash
# 复制开发环境配置
cp env.development .env

# 主要特点：
# - 启用详细日志 (LOG_LEVEL=debug)
# - 启用数据库日志 (DB_LOGGING=true)
# - 使用本地服务 (localhost)
# - 启用调试工具 (DEBUG_ENABLED=true)
```

### 生产环境

```bash
# 复制生产环境配置
cp env.production .env

# 主要特点：
# - 关闭详细日志 (LOG_LEVEL=warn)
# - 关闭数据库日志 (DB_LOGGING=false)
# - 使用生产服务器
# - 关闭调试工具 (DEBUG_ENABLED=false)
# - 启用监控 (PROMETHEUS_ENABLED=true)
```

## 🔐 安全配置

### 生产环境安全要求

1. **修改所有密钥**
   ```bash
   JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters
   SESSION_SECRET=production-session-secret-key
   COOKIE_SECRET=production-cookie-secret-key
   ```

2. **设置强密码**
   ```bash
   DB_PASSWORD=your-strong-database-password
   REDIS_PASSWORD=your-strong-redis-password
   ```

3. **配置 CORS**
   ```bash
   CORS_ORIGIN=https://your-domain.com
   ```

4. **设置域名白名单**
   ```bash
   ALLOWED_DOMAINS=your-domain.com,api.your-domain.com
   ```

## 📊 监控配置

### 启用监控

```bash
# 启用指标收集
METRICS_ENABLED=true
METRICS_PORT=9090

# 启用 Prometheus 监控
PROMETHEUS_ENABLED=true

# 启用健康检查
HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_INTERVAL=30000
```

### 追踪配置

```bash
# 启用分布式追踪
TRACING_ENABLED=true

# Jaeger 端点
JAEGER_ENDPOINT=http://jaeger:14268/api/traces
```

## 🔄 动态配置

### 启用动态配置

```bash
# 启用动态配置功能
ENABLE_DYNAMIC_CONFIG=true

# 配置缓存时间
CONFIG_CACHE_TTL=300
```

### 动态配置示例

通过 API 接口管理动态配置：

```bash
# 设置邮件配置
curl -X POST http://localhost:3000/adminapi/config/dynamic \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "key": "email.smtp",
    "value": {
      "host": "smtp.gmail.com",
      "port": 587,
      "secure": false
    },
    "description": "SMTP 服务器配置",
    "category": "email",
    "isPublic": false
  }'
```

## 🧪 测试配置

本章节的 AI 专属配置与守卫说明已迁移至 v1 模块文档：
- `wwjcloud-nest-v1/docs/AI-RECOVERY-DEV.md`
- `wwjcloud-nest-v1/docs/AI-RECOVERY-SECURITY.md`

项目主文档不再承载 v1 专属说明，请在 v1 目录内查看与维护。