# 环境变量配置指南

## 概述

koa3-demo 项目现在包含完整的环境变量验证系统，确保应用启动前所有必需的环境变量都已正确配置。

## 安全改进

根据中小型项目安全规范要求，我们已经实现：

- ✅ 移除了 `JWT_SECRET` 的默认值，强制要求环境变量配置
- ✅ 增强了环境变量验证，包括格式和安全性检查
- ✅ 提供了完整的 `.env.example` 模板文件
- ✅ 添加了敏感信息脱敏显示功能

## 快速开始

### 1. 复制环境变量模板

```bash
cp .env.example .env
```

### 2. 配置必需的环境变量

编辑 `.env` 文件，设置以下必需变量：

```bash
# 会话密钥（用于 cookie 签名）
SESSION_SECRET=your-super-secret-session-key-at-least-32-chars,backup-secret-key

# JWT 密钥（用于令牌签名和验证）
JWT_SECRET=your-super-secret-jwt-key-must-be-at-least-32-characters-long
```

### 3. 启动应用

```bash
# 开发环境
bun run dev

# 生产环境
bun run start
```

## 环境变量详解

### 必需变量 (Required)

| 变量名 | 描述 | 要求 |
|--------|------|------|
| `SESSION_SECRET` | 会话密钥，用于 cookie 签名 | 支持多个密钥（逗号分隔），用于密钥轮换 |
| `JWT_SECRET` | JWT 令牌密钥 | 最少 32 个字符，用于令牌签名和验证 |

### 可选变量 (Optional)

| 变量名 | 默认值 | 描述 |
|--------|--------|------|
| `NODE_ENV` | development | 运行环境 (development/production/test) |
| `PORT` | 3000 | 服务器端口 |
| `LOG_DIR` | logs | 日志文件目录 |
| `HTTPS_ENABLE` | off | 是否启用 HTTPS (on/off) |

## 验证功能

应用启动时会自动验证：

1. **必需变量检查**：确保所有必需的环境变量都已设置
2. **格式验证**：检查变量格式是否正确（如端口号是数字）
3. **安全性检查**：验证密钥长度和复杂度
4. **脱敏显示**：启动日志中安全地显示环境变量状态

## 测试环境变量配置

```bash
# 运行环境变量验证测试
bun run test:env
```

## 生产环境最佳实践

1. **密钥生成**：使用安全的随机字符串生成器
2. **密钥轮换**：定期更换密钥，SESSION_SECRET 支持多密钥轮换
3. **环境隔离**：不同环境使用不同的密钥
4. **版本控制**：永远不要将 `.env` 文件提交到 Git

## Docker 部署

### 使用环境变量文件

```bash
# 复制并编辑环境变量
cp .env.example .env.docker

# 使用 docker-compose
docker-compose --env-file .env.docker up
```

### 直接设置环境变量

```bash
export SESSION_SECRET="your-production-session-secret"
export JWT_SECRET="your-production-jwt-secret"
docker-compose up
```

## 故障排除

### 应用启动失败

如果应用启动时出现环境变量相关错误：

1. 检查 `.env` 文件是否存在
2. 确认所有必需的环境变量都已设置
3. 验证 JWT_SECRET 长度至少 32 个字符
4. 确保 SESSION_SECRET 不为空

### 查看详细错误信息

应用会在启动时显示详细的验证信息：

```
[INFO] 🔍 开始验证环境变量...
[ERROR] ❌ 缺少必需的环境变量:
[ERROR]    - JWT_SECRET
[ERROR] 请设置这些环境变量后重新启动应用
```

## 安全注意事项

1. **密钥强度**：使用至少 32 个字符的强随机密钥
2. **定期轮换**：定期更换密钥，特别是在生产环境
3. **访问控制**：限制对环境变量文件的访问权限
4. **监控**：监控环境变量的访问和使用情况

## 相关文件

- `.env.example` - 环境变量模板文件
- `src/utils/envValidator.js` - 环境变量验证模块
- `src/global.js` - 应用初始化和环境变量集成
- `docker-compose.yml` - Docker 环境配置