library-picturebook-activity/backend/docs/ENVIRONMENT_CONFIG.md

# 环境配置指南

## 环境区分方案

项目支持通过 `NODE_ENV` 环境变量和不同的 `.env` 文件来区分开发和生产环境。

## 配置文件结构

```
backend/
├── .env                    # 默认配置（可选，作为后备）
├── .env.development        # 开发环境配置
├── .env.production         # 生产环境配置
└── .env.test              # 测试环境配置（可选）
```

## 配置优先级

配置文件按以下优先级加载：

1. `.env.${NODE_ENV}` - 根据当前环境加载（最高优先级）
2. `.env` - 默认配置文件（后备）

例如：
- `NODE_ENV=development` → 加载 `.env.development`
- `NODE_ENV=production` → 加载 `.env.production`
- 未设置 `NODE_ENV` → 默认加载 `.env.development`，然后 `.env`

## 开发环境配置

### 创建 `.env.development` 文件

```env
# 开发环境配置
NODE_ENV=development

# 开发数据库（本地数据库）
DATABASE_URL="mysql://root:password@localhost:3306/competition_management_dev?schema=public"

# JWT 密钥（开发环境可以使用简单密钥）
JWT_SECRET="dev-secret-key-not-for-production"

# 服务器端口
PORT=3001

# 日志级别
LOG_LEVEL=debug

# CORS 配置（开发环境允许所有来源）
CORS_ORIGIN=*
```

### 开发环境数据库命名建议

- 数据库名：`competition_management_dev`
- 便于区分：开发和生产使用不同的数据库
- 安全：避免误操作生产数据

## 生产环境配置

### 创建 `.env.production` 文件

```env
# 生产环境配置
NODE_ENV=production

# 生产数据库（远程或云数据库）
DATABASE_URL="mysql://prod_user:strong_password@prod-db-host:3306/competition_management?schema=public&sslmode=require"

# JWT 密钥（必须使用强随机字符串）
# 生成方式: openssl rand -hex 32
JWT_SECRET="your-production-secret-key-must-be-strong-and-random-64-chars"

# 服务器端口
PORT=3001

# 日志级别
LOG_LEVEL=error

# CORS 配置（生产环境指定具体域名）
CORS_ORIGIN=https://yourdomain.com

# 数据库连接池配置
DB_POOL_MIN=2
DB_POOL_MAX=10

# SSL/TLS 配置
SSL_ENABLED=true
```

### 生产环境数据库配置要点

1. **使用独立的数据库服务器**
2. **启用 SSL 连接**（`sslmode=require`）
3. **使用强密码**
4. **限制数据库用户权限**（最小权限原则）
5. **定期备份**

## 使用方法

### 开发环境

```bash
# 方式 1: 设置环境变量后启动
NODE_ENV=development pnpm start:dev

# 方式 2: 在 package.json 中配置（推荐）
# 已自动配置，直接运行：
pnpm start:dev
```

### 生产环境

```bash
# 方式 1: 设置环境变量后启动
NODE_ENV=production pnpm start:prod

# 方式 2: 在部署脚本中设置
export NODE_ENV=production
pnpm start:prod
```

### 测试环境（可选）

```bash
# 创建 .env.test 文件
NODE_ENV=test
DATABASE_URL="mysql://root:password@localhost:3306/competition_management_test?schema=public"
JWT_SECRET="test-secret-key"
PORT=3002

# 运行测试
NODE_ENV=test pnpm test
```

## 数据库命名规范

建议使用以下命名规范来区分不同环境的数据库：

| 环境 | 数据库名 | 说明 |
|------|---------|------|
| 开发 | `competition_management_dev` | 开发环境数据库 |
| 测试 | `competition_management_test` | 测试环境数据库 |
| 生产 | `competition_management` | 生产环境数据库 |
| 预发布 | `competition_management_staging` | 预发布环境数据库 |

## 创建不同环境的数据库

### 开发环境数据库

```sql
CREATE DATABASE competition_management_dev 
CHARACTER SET utf8mb4 
COLLATE utf8mb4_unicode_ci;
```

### 生产环境数据库

```sql
CREATE DATABASE competition_management 
CHARACTER SET utf8mb4 
COLLATE utf8mb4_unicode_ci;
```

## 环境变量管理最佳实践

### 1. 使用 .gitignore

确保 `.env*` 文件不被提交到版本控制：

```gitignore
# .env files
.env
.env.local
.env.*.local
.env.development
.env.production
.env.test
```

### 2. 提供示例文件

创建 `.env.example` 或 `.env.*.example` 文件作为模板：

```bash
# 开发环境示例
cp .env.development.example .env.development

# 生产环境示例
cp .env.production.example .env.production
```

### 3. 使用环境变量管理工具（生产环境）

- **Docker**: 使用 `docker-compose.yml` 中的 `env_file`
- **Kubernetes**: 使用 `ConfigMap` 和 `Secret`
- **云平台**: 
  - AWS: Secrets Manager
  - Azure: Key Vault
  - GCP: Secret Manager

### 4. 验证配置

在应用启动时验证必要的环境变量：

```typescript
// 可以在 main.ts 中添加验证
if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL is required');
}
```

## 快速开始

### 1. 创建开发环境配置

```bash
cd backend

# 创建开发环境配置文件
cat > .env.development << EOF
NODE_ENV=development
DATABASE_URL="mysql://root:password@localhost:3306/competition_management_dev?schema=public"
JWT_SECRET="dev-secret-key"
PORT=3001
EOF
```

### 2. 创建生产环境配置

```bash
# 创建生产环境配置文件（不要提交到 Git）
cat > .env.production << EOF
NODE_ENV=production
DATABASE_URL="mysql://prod_user:password@prod-host:3306/competition_management?schema=public&sslmode=require"
JWT_SECRET="$(openssl rand -hex 32)"
PORT=3001
EOF
```

### 3. 初始化数据库

```bash
# 开发环境
NODE_ENV=development pnpm prisma:migrate dev

# 生产环境（部署时）
NODE_ENV=production pnpm prisma:migrate deploy
```

## 常见问题

### Q: 如何确保使用正确的环境配置？

A: 在启动应用前检查 `NODE_ENV` 环境变量：
```bash
echo $NODE_ENV  # 应该显示 development 或 production
```

### Q: 生产环境配置应该存储在哪里？

A: 
- **不要提交到 Git**
- 使用环境变量管理工具（如 Docker secrets、K8s secrets）
- 或使用云平台提供的密钥管理服务

### Q: 如何在不同环境间切换？

A: 通过设置 `NODE_ENV` 环境变量：
```bash
# 开发环境
export NODE_ENV=development
pnpm start:dev

# 生产环境
export NODE_ENV=production
pnpm start:prod
```

### Q: 数据库迁移如何区分环境？

A: Prisma 会根据 `DATABASE_URL` 环境变量自动使用对应的数据库：
```bash
# 开发环境迁移
NODE_ENV=development pnpm prisma:migrate dev

# 生产环境迁移
NODE_ENV=production pnpm prisma:migrate deploy
```