8.3 KiB
8.3 KiB
电气量测控平台前后端启动说明
1. 文档说明
本文档用于说明 EMCP 项目前后端的开发环境准备、依赖安装、启动步骤、访问地址以及常见问题处理方式。
项目目录：
- 根目录：
d:\Trae_space\EMCP - 后端目录：
d:\Trae_space\EMCP\backend - 前端目录：
d:\Trae_space\EMCP\frontend - 文档目录：
d:\Trae_space\EMCP\document
2. 当前项目技术栈
2.1 后端
- 语言：
Python 3.8 - 当前虚拟环境版本：
Python 3.8.10 - 框架：
FastAPI - 服务启动：
Uvicorn - 配置存储：
JSON - 报警存储：
SQLite - 实时通信：
WebSocket
2.2 前端
- 框架：
Vue 3 - 构建工具：
Vite - HTTP 请求：
Axios
3. 启动前准备
3.1 后端准备
后端目录已创建虚拟环境：
- 虚拟环境路径：
d:\Trae_space\EMCP\backend\.venv
如虚拟环境不存在，可在 backend 目录重新创建：
cd d:\Trae_space\EMCP\backend
py -3.8 -m venv .venv
激活虚拟环境：
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
3.2 前端准备
确保本机已安装：
Node.jsnpm
进入前端目录后通过 npm 安装依赖。
4. 首次安装依赖
4.1 安装后端依赖
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
说明：
- 当前项目已包含
setup.py与pyproject.toml - 若
pip install -e .[dev]因环境兼容问题失败，可先升级pip后重试：
python -m pip install --upgrade pip
pip install -e .[dev]
4.2 安装前端依赖
cd d:\Trae_space\EMCP\frontend
npm install
5. 启动后端
5.1 启动命令
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload
5.2 启动成功标志
终端出现类似信息表示启动成功：
Uvicorn running on http://127.0.0.1:8000
5.3 后端访问地址
- 健康检查：
http://127.0.0.1:8000/ - 接口文档：
http://127.0.0.1:8000/docs - OpenAPI：
http://127.0.0.1:8000/openapi.json
5.4 后端主要接口
- 实时数据：
GET /api/real-time-data - 设备状态：
GET /api/device-status - 设备配置：
POST /api/config/device - 通道配置：
POST /api/config/channel - 线路报警设置：
POST /api/config/line_alarm_setting - AI 报警设置：
POST /api/config/ai_alarm_setting - 系统设置：
POST /api/config/system - 报警历史：
GET /api/alarm/list - 控制指令：
POST /api/control/switch
5.5 WebSocket 地址
- 实时数据：
ws://127.0.0.1:8000/ws/real-time - 报警推送：
ws://127.0.0.1:8000/ws/alarm
5.6 后端 Debug 调试启动
开发阶段如果需要断点调试后端，推荐使用以下两种方式。
方式一：在 IDE 中直接调试 uvicorn
适用于 Trae / VS Code / Cursor 一类支持 launch.json 的编辑器。
可在工作区创建或补充调试配置文件：
d:\Trae_space\EMCP\.vscode\launch.json
示例配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug FastAPI Backend",
"type": "python",
"request": "launch",
"module": "uvicorn",
"cwd": "d:\\Trae_space\\EMCP\\backend",
"args": [
"app.main:app",
"--host",
"127.0.0.1",
"--port",
"8000",
"--reload"
],
"jinja": true,
"justMyCode": true
}
]
}
使用方式：
- 打开项目根目录
d:\Trae_space\EMCP - 选择
Debug FastAPI Backend - 启动调试
- 在
backend/app/下设置断点
说明：
cwd必须指向backend，否则app.main:app可能导入失败- 调试时建议使用后端虚拟环境解释器：
d:\Trae_space\EMCP\backend\.venv\Scripts\python.exe - 如果
--reload导致断点命中不稳定，可临时去掉--reload
方式二：使用 debugpy 启动后再附加调试
先安装调试依赖：
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
pip install debugpy
然后使用以下命令启动：
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
python -m debugpy --listen 5678 -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
启动后可在 IDE 中使用“附加到进程/Attach”方式连接：
- 主机：
127.0.0.1 - 端口：
5678
如果不需要热重载，也可以使用更稳定的命令：
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
python -m debugpy --listen 5678 -m uvicorn app.main:app --host 127.0.0.1 --port 8000
Debug 调试建议
- 需要稳定断点时，优先关闭
--reload - 排查接口逻辑时，建议在以下位置打断点：
backend/app/api/routes/backend/app/services/platform_service.pybackend/app/adapters/device_client.py
- 如果要调试模拟采集链路，可重点查看：
backend/app/tasks/polling.pybackend/app/cache/memory_store.pybackend/app/ws/manager.py
6. 启动前端
6.1 启动命令
cd d:\Trae_space\EMCP\frontend
npm run dev -- --host 127.0.0.1 --port 5173
6.2 启动成功标志
终端出现类似地址表示启动成功：
Local: http://127.0.0.1:5173/
6.3 前端访问地址
- 前端页面：
http://127.0.0.1:5173/
7. 推荐启动顺序
建议按以下顺序启动：
- 先启动后端
- 再启动前端
- 浏览器打开前端地址进行联调
原因：
- 前端默认请求后端接口：
http://127.0.0.1:8000/api - 前端默认连接后端 WebSocket：
ws://127.0.0.1:8000/ws/real-timews://127.0.0.1:8000/ws/alarm
前端接口配置位置：
frontend/src/api/http.ts
默认请求头中已携带：
X-API-Token: admin123
8. 模拟系统说明
当前项目后端默认启用模拟设备采集。
后端配置位置：
backend/app/core/config.py
当前关键配置：
use_mock_device: bool = True
poll_interval_seconds: float = 0.5
说明：
use_mock_device = True表示使用模拟设备数据源- 后端会按
0.5秒周期采集模拟数据 - 前端可用于联调实时数据、设备状态、报警历史、控制指令、配置保存等功能
9. 当前已打通页面
当前前端页面均已可以进入，已完成联调的页面如下：
- 实时数据
- 设备状态
- 设备配置
- 通道配置
- 报警设置
- 报警历史
- 控制指令
- 系统设置
其中：
设备状态支持手动刷新报警历史支持分页和刷新设备配置 / 通道配置 / 报警设置已接通真实后端提交接口
10. 常用开发命令
10.1 后端测试
cd d:\Trae_space\EMCP\backend
.\.venv\Scripts\Activate.ps1
python -m pytest
10.2 前端构建
cd d:\Trae_space\EMCP\frontend
npm run build
11. 常见问题
11.1 后端启动失败，提示类型注解错误
如果出现类似报错：
TypeError: 'type' object is not subscriptable
原因通常是 Python 版本不兼容。当前项目要求使用：
Python 3.8
请确认虚拟环境版本是否正确。
11.2 前端页面打不开
请检查：
- 前端服务是否已启动
- 地址是否为
http://127.0.0.1:5173/ npm install是否已执行成功
11.3 前端有页面但接口不通
请检查：
- 后端服务是否已启动
- 后端地址是否为
http://127.0.0.1:8000 frontend/src/api/http.ts中baseURL是否正确
11.4 页面能打开但实时数据不更新
请检查：
- 后端是否正常运行
- 后端轮询任务是否已启动
- WebSocket 是否可连
- 若 WebSocket 未连通，前端当前会自动回退到 HTTP 轮询读取实时数据
11.5 保存接口返回 401 或 403
请检查请求头中是否包含：
X-API-Token: admin123
12. 关闭服务
在各自终端中按：
Ctrl + C
即可停止前端或后端服务。
13. 建议
日常开发建议保持两个独立终端：
- 终端 1：后端
uvicorn - 终端 2：前端
vite
如果需要后续交付或部署，可在本说明基础上继续补充：
- 生产环境启动说明
- Windows 开机自启说明
- Ubuntu / RK3568 部署说明
- Nginx 反向代理说明