docs: 更新 README，反映当前架构和功能
- 更新系统架构图（MQTT订阅 + WebSocket推送） - 添加完整的 API 接口文档 - 添加 MQTT 消息格式说明 - 更新项目结构说明 - 添加与 wvp-platform 集成说明 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
248
README.md
248
README.md
@@ -1,118 +1,210 @@
|
|||||||
# AI 告警平台后端服务
|
# AI 告警平台后端服务
|
||||||
|
|
||||||
> ⚠️ **重要**：本项目是芋道大前端中的**告警业务模块后端**，不是独立前端项目。
|
基于 FastAPI 的 AI 告警接收与管理平台，支持 MQTT 告警订阅、WebSocket 实时推送、设备心跳监控。
|
||||||
|
|
||||||
## 项目定位
|
## 功能特性
|
||||||
|
|
||||||
**职责**：接收边缘端（ai_edge）告警、保存告警证据、提供 REST API
|
- **MQTT 告警订阅**：自动订阅边缘设备告警消息（`edge/alert/#`）
|
||||||
|
- **WebSocket 实时推送**：告警实时推送到前端
|
||||||
|
- **设备心跳监控**：监控边缘设备在线状态
|
||||||
|
- **REST API**：告警查询、处理、统计等完整接口
|
||||||
|
- **告警去重**：基于时间窗口的告警去重机制
|
||||||
|
|
||||||
**不负责**：
|
## 系统架构
|
||||||
- 设备管理（由 IoT 平台负责）
|
|
||||||
- 推理逻辑（由边缘端 ai_edge 负责）
|
|
||||||
- 用户体系（复用芋道前端用户体系）
|
|
||||||
|
|
||||||
## 在芋道中的定位
|
|
||||||
|
|
||||||
```
|
```
|
||||||
yudao-ui-admin-vben (芋道前端项目)
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
├─ 用户管理（已有）
|
│ AI 告警平台架构 │
|
||||||
├─ 权限管理（已有）
|
├─────────────────────────────────────────────────────────────┤
|
||||||
├─ 系统配置（已有）
|
│ │
|
||||||
└─ 业务模块
|
│ ┌──────────────┐ MQTT ┌──────────────────────┐ │
|
||||||
└─ 告警管理（本项目后端对接）
|
│ │ ai_edge │──────────────→│ EMQX Broker │ │
|
||||||
├─ 告警列表
|
│ │ 边缘推理 │ edge/alert/# │ │ │
|
||||||
├─ 告警详情
|
│ └──────────────┘ └──────────┬───────────┘ │
|
||||||
├─ 人工处理
|
│ │ │
|
||||||
└─ 大模型分析结果展示
|
│ MQTT Subscribe │
|
||||||
|
│ ▼ │
|
||||||
|
│ ┌──────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ 本服务 (FastAPI) │ │
|
||||||
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||||
|
│ │ │ MqttService │ │AlertService │ │DeviceService│ │ │
|
||||||
|
│ │ │ 消息订阅 │→ │ 告警处理 │ │ 心跳监控 │ │ │
|
||||||
|
│ │ └─────────────┘ └──────┬──────┘ └─────────────┘ │ │
|
||||||
|
│ │ │ │ │
|
||||||
|
│ │ ▼ │ │
|
||||||
|
│ │ ┌─────────────┐ ┌─────────────┐ │ │
|
||||||
|
│ │ │ WebSocket │← │ Database │ │ │
|
||||||
|
│ │ │ 实时推送 │ │ SQLite │ │ │
|
||||||
|
│ │ └──────┬──────┘ └─────────────┘ │ │
|
||||||
|
│ └─────────│────────────────────────────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ ▼ │
|
||||||
|
│ ┌──────────────┐ │
|
||||||
|
│ │ 前端/AIOT │ │
|
||||||
|
│ │ 主平台 │ │
|
||||||
|
│ └──────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
## 技术栈
|
## 技术栈
|
||||||
|
|
||||||
| 层级 | 技术 |
|
| 组件 | 技术 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| 后端框架 | FastAPI + Uvicorn |
|
| Web 框架 | FastAPI + Uvicorn |
|
||||||
| 数据库 | SQLite（轻量）或 MySQL |
|
| 消息队列 | MQTT (paho-mqtt) |
|
||||||
| 图片存储 | 阿里云 OSS |
|
| 实时推送 | WebSocket |
|
||||||
| 异步任务 | asyncio（预留 Celery） |
|
| 数据库 | SQLite / MySQL |
|
||||||
|
| ORM | SQLAlchemy |
|
||||||
|
| 配置管理 | Pydantic Settings + YAML |
|
||||||
|
|
||||||
## 快速开始
|
## 快速开始
|
||||||
|
|
||||||
|
### 1. 安装依赖
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 激活 yolo 环境
|
|
||||||
conda activate yolo
|
|
||||||
|
|
||||||
# 2. 进入项目目录
|
|
||||||
cd c:\Users\16337\PycharmProjects\service
|
|
||||||
|
|
||||||
# 3. 安装依赖
|
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
# 4. 配置环境变量
|
### 2. 配置服务
|
||||||
cp .env.example .env
|
|
||||||
# 编辑 .env 文件，配置阿里云 OSS
|
|
||||||
|
|
||||||
# 5. 启动服务
|
编辑 `config/config.yaml`：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
app:
|
||||||
|
name: "AI Alert Platform"
|
||||||
|
debug: true
|
||||||
|
host: "0.0.0.0"
|
||||||
|
port: 8000
|
||||||
|
|
||||||
|
database:
|
||||||
|
url: "sqlite:///./data/alerts.db"
|
||||||
|
|
||||||
|
mqtt:
|
||||||
|
enabled: true
|
||||||
|
host: "127.0.0.1"
|
||||||
|
port: 1883
|
||||||
|
username: ""
|
||||||
|
password: ""
|
||||||
|
topic_alert: "edge/alert/#"
|
||||||
|
topic_heartbeat: "edge/alert/heartbeat/#"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 启动服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 开发模式（自动重载）
|
||||||
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||||
|
|
||||||
|
# 生产模式
|
||||||
python -m app.main
|
python -m app.main
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 4. 访问 API 文档
|
||||||
|
|
||||||
|
启动后访问：http://localhost:8000/docs
|
||||||
|
|
||||||
## 项目结构
|
## 项目结构
|
||||||
|
|
||||||
```
|
```
|
||||||
alert_platform/
|
service/
|
||||||
├── app/
|
├── app/
|
||||||
│ ├── main.py # FastAPI 入口 + API 接口
|
│ ├── main.py # FastAPI 入口 + 路由
|
||||||
│ ├── config.py # 配置管理
|
│ ├── config.py # 配置管理（YAML + 环境变量）
|
||||||
│ ├── models.py # SQLAlchemy 告警模型
|
│ ├── models.py # SQLAlchemy 数据模型
|
||||||
│ ├── schemas.py # Pydantic 请求/响应模型
|
│ ├── schemas.py # Pydantic 请求/响应模型
|
||||||
│ ├── services/
|
│ └── services/
|
||||||
│ │ ├── alert_service.py # 告警业务逻辑
|
│ ├── mqtt_service.py # MQTT 订阅服务
|
||||||
│ │ ├── oss_storage.py # 阿里云 OSS 上传
|
│ ├── alert_service.py # 告警业务逻辑
|
||||||
│ │ └── ai_analyzer.py # 异步大模型分析
|
│ └── storage.py # 存储服务
|
||||||
│ └── utils/
|
├── config/
|
||||||
│ └── logger.py # 日志工具
|
│ └── config.yaml # 配置文件
|
||||||
├── docs/
|
|
||||||
│ └── 芋道前端对接文档.md # 芋道前端集成指南
|
|
||||||
├── data/ # SQLite 数据库
|
├── data/ # SQLite 数据库
|
||||||
├── uploads/ # 本地临时存储
|
├── logs/ # 日志文件
|
||||||
|
├── docs/ # 文档
|
||||||
├── requirements.txt
|
├── requirements.txt
|
||||||
├── .env.example
|
└── README.md
|
||||||
└── .gitignore
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## API 文档
|
## API 接口
|
||||||
|
|
||||||
启动后访问：http://localhost:8000/docs
|
### 告警管理
|
||||||
|
|
||||||
## 对接文档
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/api/v1/alerts` | 告警列表（分页、筛选） |
|
||||||
|
| GET | `/api/v1/alerts/{id}` | 告警详情 |
|
||||||
|
| PUT | `/api/v1/alerts/{id}/handle` | 处理告警 |
|
||||||
|
| GET | `/api/v1/alerts/statistics` | 告警统计 |
|
||||||
|
|
||||||
详细的前端集成指南请参考：`docs/芋道前端对接文档.md`
|
### 设备管理
|
||||||
|
|
||||||
## 边缘端对接示例
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | `/api/v1/devices` | 设备列表 |
|
||||||
|
| GET | `/api/v1/devices/{id}` | 设备详情 |
|
||||||
|
| GET | `/api/v1/devices/statistics` | 设备统计 |
|
||||||
|
|
||||||
在 ai_edge 项目中调用：
|
### WebSocket
|
||||||
|
|
||||||
```python
|
| 路径 | 说明 |
|
||||||
import requests
|
|------|------|
|
||||||
import json
|
| `/ws/alerts` | 告警实时推送 |
|
||||||
|
|
||||||
alert_data = {
|
### 健康检查
|
||||||
"camera_id": "cam-001",
|
|
||||||
"roi_id": "roi-01",
|
| 方法 | 路径 | 说明 |
|
||||||
"alert_type": "leave_post",
|
|------|------|------|
|
||||||
"algorithm": "LeavePostAlgorithm",
|
| GET | `/health` | 服务健康状态 |
|
||||||
"confidence": 85,
|
|
||||||
"duration_minutes": 5,
|
## MQTT 消息格式
|
||||||
"trigger_time": "2024-01-20T10:30:00Z",
|
|
||||||
"message": "离岗告警"
|
### 告警消息（边缘端发布）
|
||||||
|
|
||||||
|
Topic: `edge/alert/{camera_id}/{roi_id}`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"camera_id": "cam_001",
|
||||||
|
"roi_id": "roi_001",
|
||||||
|
"device_id": "edge_device_001",
|
||||||
|
"alert_type": "leave_post",
|
||||||
|
"algorithm": "YOLO",
|
||||||
|
"confidence": 0.92,
|
||||||
|
"duration_minutes": 15,
|
||||||
|
"trigger_time": "2026-02-05T12:00:00",
|
||||||
|
"message": "检测到离岗行为",
|
||||||
|
"bbox": [100, 100, 300, 400]
|
||||||
}
|
}
|
||||||
|
|
||||||
files = {
|
|
||||||
"snapshot": ("alert.jpg", image_bytes, "image/jpeg"),
|
|
||||||
"data": (None, json.dumps(alert_data), "application/json"),
|
|
||||||
}
|
|
||||||
|
|
||||||
response = requests.post(
|
|
||||||
"http://localhost:8000/api/v1/alerts",
|
|
||||||
files=files
|
|
||||||
)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 心跳消息（边缘端发布）
|
||||||
|
|
||||||
|
Topic: `edge/alert/heartbeat/{device_id}`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"device_id": "edge_device_001",
|
||||||
|
"status": "online",
|
||||||
|
"uptime": 3600,
|
||||||
|
"frames_processed": 10000,
|
||||||
|
"alerts_generated": 5,
|
||||||
|
"timestamp": "2026-02-05T12:00:00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 与 wvp-platform 集成
|
||||||
|
|
||||||
|
本服务与 wvp-platform（视频监控平台）配合使用：
|
||||||
|
|
||||||
|
1. **wvp-platform**：管理摄像头、配置 ROI 区域、推送算法配置
|
||||||
|
2. **ai_edge**：接收配置、执行推理、上报告警
|
||||||
|
3. **本服务**：接收告警、存储管理、实时推送
|
||||||
|
|
||||||
|
## 环境要求
|
||||||
|
|
||||||
|
- Python 3.8+
|
||||||
|
- MQTT Broker（推荐 EMQX）
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
|
|||||||
Reference in New Issue
Block a user