# 配置管理系统说明

## 概述

本项目采用分层配置管理系统，支持环境变量和配置文件两种方式，实现敏感信息与应用配置的分离。

## 配置文件结构

```
autool/
├── .env                    # 环境变量配置（敏感信息，不提交）
├── .env.example            # 环境变量配置模板（提交到版本库）
├── config/
│   ├── current_env.txt     # 当前环境标识（prod/test）
│   ├── prod.yaml           # 生产环境配置
│   ├── test.yaml           # 测试环境配置
│   ├── local.yaml          # 本地覆盖配置（不提交）
│   └── local.yaml.example  # 本地配置示例
├── config_loader.py        # 配置文件加载模块
├── env_loader.py           # 环境变量加载模块
└── config_usage_examples.py # 使用示例
```

## 配置优先级

配置加载的优先级从高到低为：

1. **环境变量**（`.env` 文件或系统环境变量）
2. **本地配置**（`config/local.yaml` 或 `config/local.json`）
3. **环境配置**（`config/prod.yaml` 或 `config/test.yaml`）

## 快速开始

### 1. 配置环境变量（敏感信息）

```bash
# 复制模板文件
cp .env.example .env

# 编辑 .env 文件，填入实际的 API 密钥
vim .env
```

`.env` 文件示例：
```bash
# AI 服务 API 密钥
GEMINI_API_KEY=your_actual_gemini_api_key_here
AZURE_API_KEY=your_actual_azure_api_key_here
QWEN_API_KEY=sk-your_actual_qwen_api_key_here
GLM_API_KEY=your_actual_glm_api_key_here

# 通知服务 Token
WECHAT_TOKEN_YFZ=your_actual_wechat_token_here
WECOM_TOKEN_TEAM1=your_actual_wecom_token_here

# 系统认证
IOS_PASSWORD=your_ios_device_password_here
```

### 2. 配置本地开发环境（可选）

如果需要覆盖环境配置（如修改路径、调试参数等），可创建本地配置文件：

```bash
# 复制本地配置模板
cp config/local.yaml.example config/local.yaml

# 编辑本地配置
vim config/local.yaml
```

`config/local.yaml` 示例：
```yaml
# 本地开发配置覆盖
logging:
  level: DEBUG  # 覆盖生产环境的 INFO

output:
  base_dir: D:/local_output  # 使用本地路径

redis:
  host: 127.0.0.1  # 使用本地 Redis
  db: 9  # 独立的数据库编号
```

### 3. 在代码中使用配置

#### 读取环境变量（推荐用于敏感信息）

```python
from env_loader import get_env, get_env_bool, get_env_int

# 读取必需的环境变量
gemini_api_key = get_env(
    "GEMINI_API_KEY",
    required=True,
    hint="See .env.example for setup instructions"
)

# 读取可选的环境变量（带默认值）
azure_api_key = get_env("AZURE_API_KEY", default="")
debug_mode = get_env_bool("DEBUG", default=False)
timeout = get_env_int("TIMEOUT", default=30)
```

#### 读取配置文件（推荐用于应用配置）

```python
from config_loader import load_config

# 加载配置（自动根据 current_env.txt 选择环境）
config = load_config()

# 读取配置项
output_dir = config.get("output", {}).get("base_dir", "./output")
log_level = config.get("logging", {}).get("level", "INFO")
redis_host = config.get("redis", {}).get("host", "localhost")
```

#### 在配置文件中引用环境变量

配置文件支持 `${ENV_VAR_NAME}` 格式引用环境变量：

`config/prod.yaml`:
```yaml
notifications:
  wechat:
    yfz: "${WECHAT_TOKEN_YFZ}"  # 从环境变量读取
  wecom:
    team1: "${WECOM_TOKEN_TEAM1}"
```

加载后会自动展开：
```python
config = load_config()
token = config["notifications"]["wechat"]["yfz"]  # 自动展开为实际的 token 值
```

## 最佳实践

### 1. 敏感信息 vs 应用配置

**使用 `.env` 文件的场景**：
- API 密钥、Token
- 数据库密码、Redis 密码
- 系统账户密码
- 其他不应出现在版本库中的敏感信息

**使用配置文件（`config/*.yaml`）的场景**：
- 应用功能开关
- 超时设置、重试次数等参数
- 文件路径、目录配置
- 日志级别、输出格式等
- 非敏感的业务配置

### 2. 环境隔离

```bash
# 切换到测试环境
echo "test" > config/current_env.txt

# 切换回生产环境
echo "prod" > config/current_env.txt
```

### 3. 本地开发配置

本地配置文件（`config/local.yaml`）用于覆盖环境配置，常见用途：

- 使用本地路径替代网络共享路径（提升速度）
- 启用详细日志（`DEBUG`）
- 连接本地数据库/Redis（避免影响生产环境）
- 临时关闭某些功能特性

### 4. 团队协作

**提交到版本库的文件**：
- `.env.example` - 环境变量模板，不含真实密钥
- `config/prod.yaml`, `config/test.yaml` - 环境配置
- `config/local.yaml.example` - 本地配置示例

**不提交到版本库的文件**（已在 `.gitignore` 中）：
- `.env` - 包含真实密钥
- `config/local.yaml`, `config/local.json` - 个人本地配置

## 迁移指南

### 从硬编码配置迁移

**旧代码**：
```python
# 硬编码在代码中
GEMINI_API_KEY = "AQ.Ab8RN6INSIgaGdgj5hmmYmi35QLw6K3likBz2bP37_I_F6V5aQ"
OUTPUT_DIR = "./output"
LOG_LEVEL = "INFO"
```

**新代码**：
```python
from env_loader import get_env
from config_loader import load_config

# 敏感信息从环境变量读取
GEMINI_API_KEY = get_env("GEMINI_API_KEY", required=True)

# 应用配置从配置文件读取
config = load_config()
OUTPUT_DIR = config.get("output", {}).get("base_dir", "./output")
LOG_LEVEL = config.get("logging", {}).get("level", "INFO")
```

**配置文件**：

`.env`:
```bash
GEMINI_API_KEY=AQ.Ab8RN6INSIgaGdgj5hmmYmi35QLw6K3likBz2bP37_I_F6V5aQ
```

`config/prod.yaml`:
```yaml
output:
  base_dir: ./output
logging:
  level: INFO
```

### 向后兼容处理

如果配置文件不存在，给出友好提示：

```python
from config_loader import load_config

try:
    config = load_config()
except FileNotFoundError as e:
    print(f"Configuration file not found: {e}")
    print("Please set up the configuration files in the config/ directory")
    # 使用默认配置或退出
    config = {}  # 使用空配置或默认值
```

环境变量不存在时的友好提示：

```python
from env_loader import get_env, print_env_setup_guide, check_required_env_vars

# 检查必需的环境变量
missing_vars = check_required_env_vars(["GEMINI_API_KEY", "AZURE_API_KEY"])

if missing_vars:
    print(f"Missing required environment variables: {', '.join(missing_vars)}")
    print_env_setup_guide()
    raise ValueError("Please configure environment variables")
```

## 常见问题

### Q1: `.env` 文件和 `config/local.yaml` 有什么区别？

- `.env` 用于**敏感信息**（API 密钥、密码等），格式固定为 `KEY=VALUE`
- `config/local.yaml` 用于**本地配置覆盖**（路径、参数等），支持嵌套结构

### Q2: 如何验证配置是否生效？

```python
from env_loader import get_env
from config_loader import load_config

# 检查环境变量
print(f"GEMINI_API_KEY: {get_env('GEMINI_API_KEY', default='<not set>')}")

# 检查配置文件
config = load_config()
print(f"Environment: {config.get('environment', {}).get('name', 'unknown')}")
print(f"Log level: {config.get('logging', {}).get('level', 'INFO')}")
```

### Q3: 配置文件支持哪些格式？

- **环境变量**：`.env` 文件（`KEY=VALUE` 格式）
- **配置文件**：`.yaml`、`.yml`、`.json`

推荐使用 YAML 格式，因为：
- 支持注释
- 支持嵌套结构
- 可读性更好

### Q4: 如何在配置文件中引用环境变量？

使用 `${ENV_VAR_NAME}` 格式：

```yaml
notifications:
  wechat:
    yfz: "${WECHAT_TOKEN_YFZ}"  # 引用环境变量
```

加载时会自动展开为环境变量的值。

### Q5: 环境变量和配置文件冲突时如何处理？

环境变量的优先级最高。例如：

`.env`:
```
LOG_LEVEL=DEBUG
```

`config/prod.yaml`:
```yaml
logging:
  level: INFO
```

如果在配置文件中引用环境变量：
```yaml
logging:
  level: "${LOG_LEVEL}"  # 实际值为 DEBUG（环境变量）
```

## 完整示例

参考 `config_usage_examples.py` 文件，包含：
- 环境变量读取示例
- 配置文件读取示例
- 完整的初始化函数
- 配置验证逻辑
- 迁移指南

## 安全建议

1. **永远不要提交包含真实密钥的文件**
   - `.env` 已在 `.gitignore` 中排除
   - 提交前检查：`git status` 确保 `.env` 不在待提交列表中

2. **定期轮换 API 密钥**
   - 定期更新 `.env` 中的密钥
   - 旧密钥在服务提供商处失效

3. **最小权限原则**
   - API 密钥只授予必需的权限
   - 生产环境和开发环境使用不同的密钥

4. **密钥泄露应急处理**
   - 立即在服务提供商处撤销泄露的密钥
   - 生成新密钥并更新 `.env` 文件
   - 检查是否有未授权使用记录

## 参考资料

- 配置加载模块：`config_loader.py`
- 环境变量加载模块：`env_loader.py`
- 使用示例：`config_usage_examples.py`
- 环境变量模板：`.env.example`
- 本地配置示例：`config/local.yaml.example`