wwjcloud/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
  }'
```

## 🧪 测试配置

### 验证配置

```bash
# 启动应用后访问配置验证接口
curl http://localhost:3000/adminapi/config/validate

# 查看系统配置
curl http://localhost:3000/adminapi/config/system
```

### 配置检查清单

- [ ] 数据库连接正常
- [ ] Redis 连接正常
- [ ] JWT 密钥已设置
- [ ] 日志级别合适
- [ ] 文件上传路径存在
- [ ] 第三方服务配置正确

## 🚨 常见问题

### 1. 配置不生效

**问题**：修改了 `.env` 文件但配置没有生效

**解决**：
- 确保 `.env` 文件在项目根目录
- 重启应用
- 检查环境变量名称是否正确

### 2. 数据库连接失败

**问题**：无法连接到数据库

**解决**：
- 检查 `DB_HOST`、`DB_PORT`、`DB_USERNAME`、`DB_PASSWORD`
- 确保数据库服务正在运行
- 检查防火墙设置

### 3. Redis 连接失败

**问题**：无法连接到 Redis

**解决**：
- 检查 `REDIS_HOST`、`REDIS_PORT`、`REDIS_PASSWORD`
- 确保 Redis 服务正在运行
- 检查 Redis 配置

### 4. JWT 错误

**问题**：JWT 相关错误

**解决**：
- 确保 `JWT_SECRET` 已设置且足够复杂
- 检查 `JWT_EXPIRES_IN` 格式
- 验证 `JWT_ALGORITHM` 设置

## 📚 相关文档

- [配置中心使用指南](../src/config/README.md)
- [API 文档](http://localhost:3000/docs)
- [健康检查](http://localhost:3000/health)

## 🤝 支持

如果遇到配置问题，请：

1. 检查本文档的常见问题部分
2. 查看应用日志
3. 使用配置验证接口检查配置
4. 联系技术支持团队