aitsc/docs/development/配置迁移指南.md

# 配置系统迁移指南

## 概述

本文档指导您从旧的配置系统迁移到新的分层配置管理系统。

## 迁移前准备

### 1. 备份当前配置
```bash
# 备份当前的配置文件
cp src/flask_prompt_master/config.py src/flask_prompt_master/config.py.backup
```

### 2. 安装新依赖
```bash
pip install python-dotenv==1.0.0
```

## 迁移步骤

### 第一步：环境变量设置

1. **复制环境变量示例文件**
   ```bash
   cp env.example .env
   ```

2. **编辑 .env 文件**
   根据您的实际环境设置以下必需的环境变量：
   ```bash
   # Flask基础配置
   SECRET_KEY=your-actual-secret-key
   FLASK_ENV=development
   
   # 数据库配置
   DATABASE_URL=mysql+pymysql://username:password@localhost:3306/database_name?charset=utf8mb4
   
   # OpenAI兼容API配置
   LLM_API_URL=https://api.deepseek.com/v1
   LLM_API_KEY=your-actual-api-key
   
   # 微信小程序配置
   WX_APPID=your-actual-wx-appid
   WX_SECRET=your-actual-wx-secret
   ```

### 第二步：验证配置

1. **测试配置系统**
   ```bash
   # 设置环境变量
   export FLASK_ENV=development
   
   # 测试配置加载
   python -c "from config import get_config; print('配置系统正常')"
   ```

2. **测试应用启动**
   ```bash
   python -c "from src.flask_prompt_master import create_app; app = create_app(); print('应用创建成功')"
   ```

### 第三步：更新代码引用

#### 1. 应用初始化文件
旧代码：
```python
from src.flask_prompt_master.config import Config

def create_app(config_class=Config):
    app = Flask(__name__)
    app.config.from_object(config_class)
```

新代码：
```python
from config import get_config

def create_app(config_class=None):
    if config_class is None:
        config_class = get_config()
    app = Flask(__name__)
    app.config.from_object(config_class)
    config_class.init_app(app)
```

#### 2. 路由文件中的配置引用
旧代码：
```python
from src.flask_prompt_master.config import Config

client = OpenAI(api_key=Config.LLM_API_KEY, base_url=Config.LLM_API_URL)
```

新代码：
```python
def get_openai_client():
    return OpenAI(
        api_key=current_app.config['LLM_API_KEY'], 
        base_url=current_app.config['LLM_API_URL']
    )

client = get_openai_client()
```

### 第四步：环境切换测试

1. **开发环境**
   ```bash
   export FLASK_ENV=development
   python run_dev.py
   ```

2. **测试环境**
   ```bash
   export FLASK_ENV=testing
   python -m pytest tests/
   ```

3. **生产环境**
   ```bash
   export FLASK_ENV=production
   # 确保设置了所有必需的环境变量
   python run_dev.py
   ```

## 配置项对比

### 旧配置系统
```python
class Config:
    SECRET_KEY = 'dev-key'
    SQLALCHEMY_DATABASE_URI = 'mysql+pymysql://root:123456@localhost:3306/pro_db?charset=utf8mb4'
    LLM_API_KEY = 'sk-fdf7cc1c73504e628ec0119b7e11b8cc'
    WX_APPID = 'wx2c65877d37fc29bf'
    WX_SECRET = '89aa97dda3c1347c6ae3d6ab4627f1f4'
```

### 新配置系统
```python
# 环境变量设置
SECRET_KEY=your-secret-key
DATABASE_URL=mysql+pymysql://username:password@localhost:3306/database_name?charset=utf8mb4
LLM_API_KEY=your-api-key
WX_APPID=your-wx-appid
WX_SECRET=your-wx-secret
```

## 常见问题解决

### 1. 环境变量未设置错误
**错误信息：** `ValueError: SECRET_KEY 环境变量未设置`

**解决方案：**
- 确保 `.env` 文件存在且包含所有必需的环境变量
- 检查环境变量名称是否正确
- 确保 `python-dotenv` 已安装

### 2. 配置类导入错误
**错误信息：** `ModuleNotFoundError: No module named 'config'`

**解决方案：**
- 确保在项目根目录下运行命令
- 检查 `config/` 目录是否存在
- 确保 `config/__init__.py` 文件存在

### 3. 跨域配置错误
**错误信息：** `ValueError: 生产环境必须设置 CORS_ORIGINS 环境变量`

**解决方案：**
- 在生产环境中设置 `CORS_ORIGINS` 环境变量
- 或者修改生产环境配置使用默认值

## 迁移检查清单

- [ ] 备份旧配置文件
- [ ] 安装新依赖包
- [ ] 创建 `.env` 文件并设置环境变量
- [ ] 更新应用初始化代码
- [ ] 更新路由文件中的配置引用
- [ ] 测试开发环境配置
- [ ] 测试测试环境配置
- [ ] 测试生产环境配置
- [ ] 验证所有功能正常工作
- [ ] 删除旧配置文件

## 回滚方案

如果迁移过程中出现问题，可以快速回滚：

1. **恢复旧配置**
   ```bash
   cp src/flask_prompt_master/config.py.backup src/flask_prompt_master/config.py
   ```

2. **恢复旧的应用初始化代码**
   ```python
   from src.flask_prompt_master.config import Config
   
   def create_app(config_class=Config):
       app = Flask(__name__)
       app.config.from_object(config_class)
       return app
   ```

3. **恢复旧的路由配置引用**
   ```python
   from src.flask_prompt_master.config import Config
   
   client = OpenAI(api_key=Config.LLM_API_KEY, base_url=Config.LLM_API_URL)
   ```

## 总结

新的配置系统提供了以下优势：

1. **环境分离**：不同环境使用不同的配置
2. **安全性提升**：敏感信息通过环境变量管理
3. **可维护性增强**：配置结构清晰，易于管理
4. **部署简化**：标准化的环境切换机制

完成迁移后，您的应用将具有更好的配置管理能力和安全性。