Visual_MediaCrawler | 项目文档

Appearance

项目环境管理指南 ​

本文档详细介绍Visual_MediaCrawler项目的环境配置、管理和启动流程，包括后端Python环境和前端Node.js环境的完整配置说明。

后端环境管理 ​

Python环境要求 ​

  • Python版本：3.13.5或更高版本
  • 包管理工具：uv（推荐）或pip
  • 操作系统：Windows/Linux/macOS

虚拟环境配置 ​

项目使用uv作为Python包管理工具，相比传统的pip，它提供了更快的依赖解析和安装速度。

安装uv ​

bash
# 使用pip安装uv
pip install uv

# 或使用官方推荐的安装方式
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

创建虚拟环境 ​

bash
# 在项目根目录下创建虚拟环境
uv venv .venv

# 激活虚拟环境
# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

安装项目依赖 ​

bash
# 使用uv安装依赖
uv sync

# 或者使用requirements.txt安装
uv pip install -r requirements.txt

后端服务启动 ​

项目提供了两种启动后端API服务的方式：

方式一：使用批处理脚本（推荐） ​

bash
# 在项目根目录下执行
api\api_run.bat

批处理脚本会自动激活虚拟环境并启动API服务。

方式二：手动启动 ​

bash
# 激活虚拟环境
.venv\Scripts\activate

# 启动API服务
cd api
uvicorn api:app --host 127.0.0.1 --port 10001 --reload

前端环境管理 ​

Node.js环境要求 ​

  • Node.js版本：16.0.0或更高版本
  • npm版本：7.0.0或更高版本
  • 推荐IDE：Visual Studio Code（配合Vue.js扩展）

前端依赖安装 ​

bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

前端服务启动 ​

项目提供了两种启动前端开发服务的方式：

方式一：使用批处理脚本（推荐） ​

bash
# 在前端目录下执行
frontend_run_dev.bat

方式二：手动启动 ​

bash
# 进入前端目录
cd frontend

# 启动开发服务
npm run dev

前端构建 ​

bash
# 构建生产环境版本
npm run build

# 预览构建结果
npm run preview

前端配置说明 ​

前端项目基于Vite构建，主要配置文件包括：

  • vite.config.js：Vite配置文件，定义了开发服务器端口(10002)和插件配置
  • package.json：项目依赖和脚本配置
  • src/config/：前端配置目录
    • api.js：API接口地址配置
    • constants.js：全局常量定义
    • theme.js：主题相关配置

主要依赖包括：

  • Vue 3：前端框架
  • Vue Router：路由管理
  • Element Plus：UI组件库
  • Axios：HTTP客户端
  • ECharts：数据可视化图表库
  • Pinia：状态管理
  • Tailwind CSS：实用工具优先的CSS框架

修改API服务地址时，编辑frontend/src/config/api.js文件：

javascript
// 开发环境API地址
export const DEV_API_URL = 'http://localhost:10001';

// 生产环境API地址
export const PROD_API_URL = 'http://your-production-api-url';

开发环境集成 ​

前后端联调 ​

前端默认API请求地址为http://localhost:10001，后端API服务默认监听地址为127.0.0.1:10001。确保两者正常启动后，前端可以正常访问后端API。

开发端口 ​

开发工具推荐 ​

  • Visual Studio Code：轻量级代码编辑器，推荐安装以下扩展：
    • Python扩展：提供Python语言支持
    • Volar：Vue 3语法支持
    • ESLint：代码质量检查
    • Prettier：代码格式化
    • Tailwind CSS IntelliSense：Tailwind CSS智能提示
  • PyCharm：专业Python IDE，适合后端开发
  • Chrome DevTools：前端调试工具

代码风格和规范 ​

  • 后端代码规范：

    • 遵循PEP 8规范
    • 使用类型注解增强代码可读性
    • 异步函数使用async/await语法
    • 使用mypy进行类型检查

  • 前端代码规范：

    • 遵循项目中.eslintrc.js定义的ESLint规则
    • 使用Vue 3组合式API（Composition API）
    • 组件使用PascalCase命名
    • 使用TypeScript类型定义

常见问题解决 ​

后端问题 ​

  1. 依赖安装失败

    • 检查Python版本是否符合要求（3.13.5+）
    • 尝试使用pip install --no-cache-dir -r requirements.txt
    • 使用国内镜像源加速下载：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
    • 如果使用uv，尝试：uv pip install -r requirements.txt

  2. 数据库连接错误

    • 检查数据库配置是否正确（SQLite路径或MySQL连接参数）
    • 确认MySQL服务是否启动（如使用MySQL）
    • 检查网络连接和防火墙设置（特别是远程MySQL）
    • 运行python db_init.py --check-connection验证连接

  3. API服务启动失败

    • 检查端口10001是否被占用：netstat -ano | findstr 10001（Windows）或lsof -i:10001（Linux/macOS）
    • 检查虚拟环境是否正确激活
    • 检查日志输出，识别具体错误

前端问题 ​

  1. 依赖安装失败

    • 检查Node.js版本是否符合要求（16+）
    • 尝试清除npm缓存：npm cache clean --force
    • 使用国内镜像源：npm config set registry https://registry.npmmirror.com
    • 尝试使用yarn代替npm：yarn install

  2. 开发服务器启动失败

    • 检查端口10002是否被占用：netstat -ano | findstr 10002（Windows）或lsof -i:10002（Linux/macOS）
    • 检查项目依赖是否完整安装
    • 检查vite.config.js配置是否正确
    • 尝试删除node_modules目录后重新安装依赖

  3. API连接问题

    • 确认后端API服务是否正常运行
    • 检查前端配置中的API地址是否正确
    • 检查浏览器控制台是否有CORS错误

虚拟环境激活失败 ​

如果虚拟环境激活失败，可能是由于执行策略限制，可以尝试：

bash
# Windows PowerShell中设置执行策略
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

环境更新与维护 ​

后端依赖更新 ​

bash
# 使用uv更新所有依赖到最新版本
uv pip install --upgrade -r requirements.txt

# 或使用pip更新
pip install --upgrade -r requirements.txt

# 生成新的依赖锁文件
uv pip freeze > requirements.txt

前端依赖更新 ​

bash
# 进入前端目录
cd frontend

# 更新依赖
npm update

# 检查过时的依赖
npm outdated

# 安装特定依赖的最新版本
npm install package-name@latest

环境清理 ​

bash
# Windows系统清理Python缓存文件
powershell -Command "Get-ChildItem -Path . -Include __pycache__ -Recurse -Force | Remove-Item -Recurse -Force"
powershell -Command "Get-ChildItem -Path . -Include *.pyc -Recurse -Force | Remove-Item -Force"

# Linux/macOS清理Python缓存文件
find . -name "__pycache__" -type d -exec rm -rf {} +
find . -name "*.pyc" -delete

# 清理前端构建文件
cd frontend
rm -rf dist
rm -rf node_modules/.vite

定期维护建议 ​

  1. 依赖审查：每月检查一次依赖更新，特别关注安全更新
  2. 环境备份：在重大更新前备份虚拟环境和配置文件
  3. 版本控制：使用git记录环境配置变更
  4. 性能监控：定期检查服务性能，及时优化配置

多环境配置 ​

开发环境 ​

开发环境配置专注于开发便利性和调试能力：

  • 后端：启用调试模式和热重载
  • 前端：启用源码映射和热模块替换
  • 数据库：优先使用SQLite简化配置

测试环境 ​

测试环境模拟生产环境但具有额外的测试工具：

  • 后端：禁用调试模式，启用测试日志
  • 前端：使用生产构建但保留源码映射
  • 数据库：使用与生产相同类型的数据库，但使用测试数据集

生产环境 ​

生产环境配置专注于性能、安全性和稳定性：

  • 后端：禁用调试模式，优化性能设置
  • 前端：使用压缩的生产构建
  • 数据库：使用高可用性配置的MySQL
  • 安全：启用所有安全措施，如HTTPS和请求限制

Released under the 'NON-COMMERCIAL LEARNING LICENSE 1.1' License

Copyright © 2025-present persist-1