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

配置系统迁移指南

概述

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

迁移前准备

1. 备份当前配置

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

2. 安装新依赖

pip install python-dotenv==1.0.0

迁移步骤

第一步：环境变量设置

1. 复制环境变量示例文件

   cp env.example .env
   

2. 编辑 .env 文件 根据您的实际环境设置以下必需的环境变量：

   # 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. 测试配置系统

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

2. 测试应用启动

   python -c "from src.flask_prompt_master import create_app; app = create_app(); print('应用创建成功')"
   

第三步：更新代码引用

1. 应用初始化文件

旧代码：

from src.flask_prompt_master.config import Config

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

新代码：

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. 路由文件中的配置引用

旧代码：

from src.flask_prompt_master.config import Config

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

新代码：

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. 开发环境

   export FLASK_ENV=development
   python run_dev.py
   

2. 测试环境

   export FLASK_ENV=testing
   python -m pytest tests/
   

3. 生产环境

   export FLASK_ENV=production
   # 确保设置了所有必需的环境变量
   python run_dev.py
   

配置项对比

旧配置系统

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'

新配置系统

# 环境变量设置
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. 恢复旧配置

   cp src/flask_prompt_master/config.py.backup src/flask_prompt_master/config.py
   

2. 恢复旧的应用初始化代码

   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. 恢复旧的路由配置引用

   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. 部署简化：标准化的环境切换机制

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