cloud-reporter/backend/README_VENV.md

Python 虚拟环境使用指南

快速开始

Windows

# 运行设置脚本
setup.bat

# 激活虚拟环境
activate_venv.bat

# 初始化数据库
python init_db.py

# 启动应用
python run.py

Unix/Linux/macOS

# 设置执行权限
chmod +x setup.sh

# 运行设置脚本
./setup.sh

# 激活虚拟环境
source activate_venv.sh

# 初始化数据库
python init_db.py

# 启动应用
python run.py

详细说明

1. 创建虚拟环境

自动设置 (推荐)

# Windows
setup.bat

# Unix/Linux/macOS
./setup.sh

手动设置

# 创建虚拟环境
python setup_venv.py

# 升级依赖
python setup_venv.py --upgrade

# 重新创建虚拟环境
python setup_venv.py --clean

2. 激活虚拟环境

Windows

# 方式1: 使用生成的脚本
activate_venv.bat

# 方式2: 直接激活
venv\Scripts\activate.bat

Unix/Linux/macOS

# 方式1: 使用生成的脚本
source activate_venv.sh

# 方式2: 直接激活
source venv/bin/activate

3. 停用虚拟环境

deactivate

4. 验证环境

# 检查Python路径
which python    # Unix/Linux/macOS
where python    # Windows

# 检查已安装的包
pip list

# 检查Flask是否正确安装
python -c "import flask; print(flask.__version__)"

常用命令

开发命令

# 启动Flask应用 (开发模式)
python run.py

# 初始化数据库
python init_db.py

# 初始化数据库并创建示例数据
python init_db.py --with-demo

# 重置数据库
python init_db.py --reset

Celery任务队列

# 启动Celery worker
celery -A celery_worker worker --loglevel=info

# Windows上启动Celery (需要额外配置)
celery -A celery_worker worker --loglevel=info --pool=solo

测试

# 运行所有测试
pytest

# 运行测试并显示覆盖率
pytest --cov=app

# 运行特定测试文件
pytest tests/test_auth.py

数据库迁移

# 初始化迁移
flask db init

# 创建迁移
flask db migrate -m "描述信息"

# 应用迁移
flask db upgrade

环境变量

创建 .env 文件 (基于 .env.example):

cp .env.example .env

编辑 .env 文件设置必要的环境变量:

FLASK_ENV=development
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret-key
DATABASE_URL=sqlite:///dev.db
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1
ENCRYPTION_KEY=your-encryption-key

依赖管理

安装新依赖

# 激活虚拟环境后
pip install package-name

# 更新requirements.txt
pip freeze > requirements.txt

升级依赖

# 升级所有依赖
python setup_venv.py --upgrade

# 升级特定包
pip install --upgrade package-name

故障排除

常见问题

1. Python版本不兼容

   • 确保使用Python 3.8或更高版本
   • 检查: python --version

2. 虚拟环境激活失败

   • Windows: 确保执行策略允许运行脚本
   • Unix/Linux: 确保脚本有执行权限 chmod +x activate_venv.sh

3. 依赖安装失败

   • 升级pip: pip install --upgrade pip
   • 清理缓存: pip cache purge
   • 重新创建环境: python setup_venv.py --clean

4. 数据库连接问题

   • 检查数据库文件路径
   • 确保有写入权限
   • 检查环境变量设置

重置环境

# 完全重置虚拟环境
python setup_venv.py --clean

# 重置数据库
python init_db.py --reset

项目结构

backend/
├── venv/                   # 虚拟环境目录
├── app/                    # 应用代码
├── config/                 # 配置文件
├── migrations/             # 数据库迁移
├── tests/                  # 测试文件
├── requirements.txt        # 依赖列表
├── setup_venv.py          # 虚拟环境设置脚本
├── setup.bat              # Windows快速设置
├── setup.sh               # Unix/Linux快速设置
├── activate_venv.bat      # Windows激活脚本
├── activate_venv.sh       # Unix/Linux激活脚本
├── init_db.py             # 数据库初始化脚本
└── run.py                 # 应用入口