# 统一环境变量配置管理

## 🎯 概述

本项目采用统一的环境变量配置管理系统，提供类型安全、可验证、易维护的配置管理方案。

## 📁 目录结构

```
config/env/
├── .env                    # 基础配置（包含所有变量的默认值）
├── .env.development        # 开发环境差异配置
├── .env.testing           # 测试环境差异配置
├── .env.production        # 生产环境差异配置
├── .env.example           # 示例配置（用于文档和初始化）
└── environment.schema.json # 环境变量模式定义
```

## 🔧 使用方法

### 1. 基础使用

```python
from app.core.unified_config import settings

# 访问配置
print(settings.DATABASE_URL)
print(settings.REDIS_URL)
print(settings.LOG_LEVEL)
```

### 2. 环境切换

通过设置 `ENVIRONMENT` 环境变量来切换配置：

```bash
# 开发环境（默认）
ENVIRONMENT=development python app/main.py

# 测试环境
ENVIRONMENT=testing python app/main.py

# 生产环境
ENVIRONMENT=production python app/main.py
```

### 3. 配置验证

```python
from app.core.env_validator import validate_current_environment
from app.core.unified_config import settings

# 验证当前配置
result = validate_current_environment(settings)
print(f"验证结果: {'通过' if result['valid'] else '失败'}")
print(f"错误: {result['errors']}")
print(f"警告: {result['warnings']}")
```

## 📋 环境变量说明

### 必需配置

| 变量名 | 说明 | 格式 |
|--------|------|------|
| `DATABASE_URL` | PostgreSQL数据库连接URL | `postgresql+asyncpg://user:password@host:port/dbname` |
| `REDIS_URL` | Redis连接URL | `redis://[:password@]host:port/db` |

### 常用可选配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ENVIRONMENT` | 运行环境 | `development` |
| `DEBUG` | 调试模式 | `false` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `PORT` | 服务端口 | `8000` |
| `AGENTS_DIR` | Agent目录 | `app/agent_studio/agents` |

### 完整配置列表

参见 [environment.schema.json](environment.schema.json) 文件获取所有配置项的详细说明。

## 🚀 最佳实践

### 1. 环境配置原则

- **基础配置**：将所有变量的默认值放在 `.env` 中
- **环境差异**：只在环境特定文件中覆盖需要修改的变量
- **避免重复**：不要在多个文件中重复定义相同的变量

### 2. 安全配置

- **敏感信息**：不要在 `.env.example` 中包含真实密码或密钥
- **版本控制**：不要将 `.env.local` 或包含真实密钥的文件提交到版本控制
- **生产环境**：生产配置应该使用最安全、最严格的设置

### 3. 开发流程

1. 复制 `.env.example` 为 `.env` 并修改必要配置
2. 使用 `validate_current_environment()` 验证配置
3. 根据需要创建 `.env.local` 进行本地覆盖
4. 为不同环境创建相应的 `.env.{environment}` 文件

## 🔍 故障排除

### 常见问题

1. **配置验证失败**
   ```bash
   python -c "from app.core.env_validator import validate_current_environment; print(validate_current_environment())"
   ```

2. **环境变量未生效**
   - 检查文件路径是否正确
   - 确认 `ENVIRONMENT` 变量设置
   - 检查配置文件中变量名是否正确

3. **类型验证错误**
   - 检查变量值的格式是否符合要求
   - 参考 `environment.schema.json` 中的类型定义

### 调试工具

```python
from app.core.unified_config import print_current_config
print_current_config()
```

## 📚 高级功能

### 自定义验证

```python
from app.core.env_validator import EnvironmentValidator

# 创建自定义验证器
validator = EnvironmentValidator()

# 验证特定变量
errors = validator.validate_specific_vars(['DATABASE_URL', 'REDIS_URL'])

# 生成配置模板
template = validator.generate_env_template()
print(template)
```

### 配置重载

```python
from app.core.unified_config import reload_settings

# 重新加载配置（开发时有用）
new_settings = reload_settings()
```

## 🔧 扩展配置

### 添加新配置项

1. 在 `UnifiedSettings` 类中添加新字段
2. 更新 `environment.schema.json` 中的模式定义
3. 在相应的 `.env` 文件中添加默认值

### 自定义验证规则

在 `EnvironmentValidator` 类中添加自定义验证方法：

```python
def _validate_custom_rule(self, var_name, value, config):
    # 自定义验证逻辑
    pass
```

## 📞 支持

如有问题，请检查日志输出或使用调试工具。配置系统会在应用启动时自动验证所有必需的环境变量。