diff --git a/README.md b/README.md index 4638f99..2575d2f 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,210 @@ # 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 | -| 数据库 | SQLite（轻量）或 MySQL | -| 图片存储 | 阿里云 OSS | -| 异步任务 | asyncio（预留 Celery） | +| Web 框架 | FastAPI + Uvicorn | +| 消息队列 | MQTT (paho-mqtt) | +| 实时推送 | WebSocket | +| 数据库 | SQLite / MySQL | +| ORM | SQLAlchemy | +| 配置管理 | Pydantic Settings + YAML | ## 快速开始 +### 1. 安装依赖 + ```bash -# 1. 激活 yolo 环境 -conda activate yolo - -# 2. 进入项目目录 -cd c:\Users\16337\PycharmProjects\service - -# 3. 安装依赖 pip install -r requirements.txt +``` -# 4. 配置环境变量 -cp .env.example .env -# 编辑 .env 文件，配置阿里云 OSS +### 2. 配置服务 -# 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 ``` +### 4. 访问 API 文档 + +启动后访问：http://localhost:8000/docs + ## 项目结构 ``` -alert_platform/ +service/ ├── app/ -│ ├── main.py # FastAPI 入口 + API 接口 -│ ├── config.py # 配置管理 -│ ├── models.py # SQLAlchemy 告警模型 +│ ├── main.py # FastAPI 入口 + 路由 +│ ├── config.py # 配置管理（YAML + 环境变量） +│ ├── models.py # SQLAlchemy 数据模型 │ ├── schemas.py # Pydantic 请求/响应模型 -│ ├── services/ -│ │ ├── alert_service.py # 告警业务逻辑 -│ │ ├── oss_storage.py # 阿里云 OSS 上传 -│ │ └── ai_analyzer.py # 异步大模型分析 -│ └── utils/ -│ └── logger.py # 日志工具 -├── docs/ -│ └── 芋道前端对接文档.md # 芋道前端集成指南 +│ └── services/ +│ ├── mqtt_service.py # MQTT 订阅服务 +│ ├── alert_service.py # 告警业务逻辑 +│ └── storage.py # 存储服务 +├── config/ +│ └── config.yaml # 配置文件 ├── data/ # SQLite 数据库 -├── uploads/ # 本地临时存储 +├── logs/ # 日志文件 +├── docs/ # 文档 ├── requirements.txt -├── .env.example -└── .gitignore +└── README.md ``` -## 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", - "confidence": 85, - "duration_minutes": 5, - "trigger_time": "2024-01-20T10:30:00Z", - "message": "离岗告警" +### 健康检查 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/health` | 服务健康状态 | + +## MQTT 消息格式 + +### 告警消息（边缘端发布） + +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