Prachi5791/VigilAI
GitHub: Prachi5791/VigilAI
基于 YOLOv8 的智能视频监控分析系统，能够自动检测安全事件并生成视频片段。
Stars: 1 | Forks: 0
# VigilAI：智能监控事件检测与分析系统
## 🔗 在线部署
| 服务 | 链接 | 状态 |
|---------|-----|--------|
| 🌐 前端 (React) | [https://vigil-ai-five.vercel.app](https://vigil-ai-five.vercel.app) | 在线 |
| ⚙️ 后端 (Node.js) | [https://vigilai-ytg4.onrender.com](https://vigilai-ytg4.onrender.com) | 在线 |
| 🐍 Python 引擎 (Flask + YOLOv8) | [https://vigilai-1-njnz.onrender.com](https://vigilai-1-njnz.onrender.com) | 在线 |
## 📑 目录
1. [系统架构](#-system-architecture)
2. [ADBMS 概念与特性](#-adbms-concepts--features)
3. [事件类型与检测规则](#-event-types--detection-rules)
4. [快速开始 — Docker](#-quick-start--docker)
5. [快速开始 — 本地开发](#-quick-start--local-dev)
6. [项目结构](#-project-structure)
7. [API 参考](#-api-reference)
8. [关键设计规则](#-key-design-rules)
9. [故障排除](#-troubleshooting)
## 🏗 系统架构
```
Browser :3000 → nginx (frontend) → /api proxy → backend :4000
│
┌────────────┼─────────────┐
▼ ▼ ▼
MongoDB Python shared
:27017 :5000 volumes
(Flask+YOLO)
```
### 服务端口
| 服务 | 端口 | 描述 |
|---------|------|-------------|
| `frontend` | 3000 | 通过 nginx 提供服务的 React 应用 |
| `backend` | 4000 | Node.js / Express REST API |
| `python-engine` | 5000 | Flask + YOLOv8 + OpenCV |
| `mongodb` | 27017 | MongoDB 7.0 数据库 |
## 🗄 ADBMS 概念与特性
本系统融合了多种**高级数据库管理系统（ADBMS）**概念，以确保高效查询、高可用性和大规模场景下的最佳性能。
### 1. 索引与查询优化
- 在 `event_type`、`video_id` 和 `timestamp` 上建立的**复合索引**支持在大型事件集合中进行快速过滤，无需全表扫描。
- `/api/adbms/index-comparison` 端点允许你实时比较**有索引和无索引**的查询执行计划，展示可量化的性能提升。
- 过滤参数（`min_duration`、`min_confidence`、`zone`）经过设计，可利用这些索引实现亚毫秒级查询。
### 2. 缓存层
- **NodeCache** 被用作 Node.js 后端中的内存缓存层。
- 频繁访问的聚合结果（事件计数、摘要、统计信息）被缓存，以避免重复执行 MongoDB 聚合管道。
- `/api/adbms/cache-stats` 和 `/api/adbms/cache-test` 端点提供**实时未命中 → 命中演示**，展示缓存效果。
### 3. 复制与容错
- 系统设计考虑了 **MongoDB 副本集**概念。
- `/api/adbms/replication-test` 端点模拟主节点故障和恢复场景（`fail_primary` / `restore`），展示系统在节点故障期间如何保持可用性。
- `/api/adbms/server-selection` 演示读写路由 — 写入操作发送到主节点，读取操作可分发到从节点。
### 4. 批量写入操作（Upsert 模式）
- 来自 Python 引擎的所有事件通过 `POST /api/events/bulk` 提交，该端点使用 MongoDB 的 `bulkWrite` 并采用 **upsert 语义**。
- 通过确定性 `event_id = MD5(video_id:type:track:frame)` 哈希实现事件去重，即使在重新处理时也能防止重复记录。
### 5. 查询日志与可观测性
- 每个重要的数据库查询都会被记录到 `QueryLog` 集合中，记录执行时间、查询类型和结果大小。
- `/api/adbms/query-logs` 端点展示这些日志及聚合统计信息，支持**数据库性能长期监控**。
### 6. 顺序与并行处理
- 系统支持顺序和并行两种视频处理管道。
- `/api/adbms/processing-comparison` 比较两种策略的吞吐量，展示并发如何影响数据库写入模式和整体性能。
## 🚨 事件类型与检测规则
| 事件 | 触发条件 | 优先级 |
|-------|-------------------|----------|
| `zone_entry` | 人员进入定义的区域多边形 | 3 |
| `zone_loitering` | 人员在区域内停留超过 8 秒 | 8 |
| `loitering` | 人员在超过 10 秒内移动距离小于 80 像素 | 6 |
| `abandoned_object` | 包/物体在超过 15 秒内移动距离小于 30 像素 | 10 |
| `vehicle_stop` | 车辆速度在超过 8 秒内低于 2 像素/帧 | 5 |
| `crowd_formation` | 在区域内检测到 3 人以上且持续超过 1 秒 | 9 |
## 🐳 快速开始 — Docker
### 前置条件
- Docker >= 24
- Docker Compose >= 2.20
- 建议 8 GB 内存（用于 YOLOv8 large 模型）
### 运行完整技术栈
```
docker compose up --build
```
### 停止与清理
```
# 停止所有容器
docker compose down
# 完全清理包括卷（重置所有数据）
docker compose down -v
```
## 💻 快速开始 — 本地开发
```
# 1. 启动 MongoDB
docker run -d -p 27017:27017 mongo:7.0
# 2. 启动 Python Engine（Flask + YOLOv8）
cd python-engine
pip install -r requirements.txt
python3 app.py # Runs on :5000
# 3. 启动 Backend（Node.js）
cd backend
npm install
npm run dev # Runs on :4000
# 4. 启动 Frontend（React）
cd frontend
npm install
npm start # Runs on :3000
```
## 📁 项目结构
```
surveillance-system/
├── docker-compose.yml
├── README.md
│
├── backend/ # Node.js / Express API
│ ├── Dockerfile
│ ├── .env
│ ├── server.js
│ ├── package.json
│ ├── models/
│ │ ├── Event.js
│ │ ├── Video.js
│ │ └── QueryLog.js
│ ├── routes/
│ │ ├── videos.js
│ │ ├── events.js
│ │ ├── clips.js
│ │ └── adbms.js
│ └── public/
│ ├── uploads/
│ └── clips/
│
├── python-engine/ # Flask + YOLOv8 Processing
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── app.py # Flask HTTP service
│ ├── pipeline.py # Processing orchestrator
│ ├── rule_engine.py # 6 event detection rules
│ ├── tracker.py # TrackStore + DetectionFilter
│ ├── detector.py # YOLOv8 + MockDetector
│ ├── models.py # Shared dataclasses
│ ├── backend_client.py
│ └── generate_clip.py # On-demand clip renderer
│
└── frontend/ # React UI
├── Dockerfile
├── nginx.conf
├── package.json
└── src/
├── App.js
├── index.css
├── services/api.js
└── pages/
├── UploadPage.js
├── EventsPage.js
├── ClipViewer.js
└── AdbmsPage.js # ADBMS analytics dashboard
```
## 📡 API 参考
### 视频
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `POST` | `/api/videos/upload` | 上传单个视频（`multipart: video, zones, processing_mode`） |
| `POST` | `/api/videos/upload-multiple` | 上传多个视频（`multipart: videos[], zones, processing_mode`） |
| `POST` | `/api/videos/:id/process` | 启动视频的顺序处理 |
| `POST` | `/api/videos/process-parallel` | 并发处理（`{ video_ids: [] }`） |
| `GET` | `/api/videos` | 列出所有视频 |
| `GET` | `/api/videos/:id` | 获取单个视频及事件计数 |
| `DELETE` | `/api/videos/:id` | 删除视频及所有关联事件 |
### 事件
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `POST` | `/api/events/bulk` | Upsert 事件数组（由 Python 引擎调用） |
| `GET` | `/api/events` | 列出事件，支持过滤：`video_id`、`event_type`、`min_duration`、`min_confidence`、`zone` |
| `GET` | `/api/events/:id` | 获取单个事件 |
| `GET` | `/api/events/stats/summary` | 聚合事件计数和摘要 |
### 视频片段
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/api/events/:id/clip` | 生成或返回缓存的视频片段 |
| `DELETE` | `/api/events/:id/clip` | 删除已生成的视频片段 |
### ADBMS 分析
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/api/adbms/index-comparison` | 索引与无索引查询基准测试（`?event_type=loitering`） |
| `GET` | `/api/adbms/query-logs` | 所有查询日志及聚合统计 |
| `GET` | `/api/adbms/cache-stats` | NodeCache 命中/未命中计数器 |
| `GET` | `/api/adbms/cache-test` | 实时缓存未命中 → 命中演示 |
| `GET` | `/api/adbms/server-selection` | 读写路由演示（`?type=read\|write`） |
| `POST` | `/api/adbms/replication-test` | 模拟复制事件（`{ action: "fail_primary" \| "restore" }`） |
| `GET` | `/api/adbms/processing-comparison` | 顺序与并行处理统计 |
### Python 引擎（内部）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| `GET` | `/health` | 存活探针 |
| `GET` | `/status/:video_id` | 视频任务状态 |
| `POST` | `/process` | 启动处理（`{ video_id, video_path, zones, backend_url }`） |
| `POST` | `/generate-clip` | 渲染视频片段（`{ event, video_path, clip_dir, clip_fname, buffer }`） |
## 📐 关键设计规则
| 规则 | 实现方式 |
|------|----------------|
| **无重复事件** | `event_id = MD5(video_id:type:track:frame)` + MongoDB upsert |
| **Python 中不生成视频片段** | `generate_clip.py` 仅在 Node.js POST 到 `/generate-clip` 时调用 |
| **仅批量插入** | `POST /api/events/bulk` → MongoDB `bulkWrite` upsert |
| **一致的视频片段命名** | `_.mp4` |
| **共享文件卷** | `shared_uploads`（Python 只读）+ `shared_clips`（双方读写） |
## 🛠 故障排除
```
# 查看所有服务的日志
docker compose logs -f
# Python engine 启动较慢（正在下载 YOLOv8 权重）
docker compose logs python-engine
# 检查 MongoDB 事件计数
docker compose exec mongodb mongosh surveillance \
--eval "db.events.countDocuments()"
# 列出所有生成的片段
docker compose exec backend ls /app/public/clips
# 手动 pipeline 测试（本地，无需 backend）
cd python-engine
python3 pipeline.py /path/to/video.mp4 \
--video_id test-123 \
--no_backend \
--zones '[{"name":"A","polygon":[[0,0],[300,0],[300,300],[0,300]]}]'
```
## 🧑💻 作者
**Prachi Maruti Patil**
Vidyalankar Institute of Technology
*基于 YOLOv8 · Flask · Node.js · React · MongoDB · Docker 构建*
标签：ADBMS, AI视频分析, Docker, Express, Flask, GNU通用公共许可证, MITM代理, MongoDB, MongoDB 7.0, nginx, Node.js, OpenCV, OSV, Python引擎, React, Render, REST API, Syscalls, Vercel, YOLOv8, 事件分析, 事件分析系统, 事件检测, 事件触发, 云计算, 全栈项目, 前后端分离, 多引擎聚合, 多服务架构, 多端口服务, 安全防御评估, 安防AI, 安防监控, 实时检测, 异常事件检测, 按需视频剪辑, 智能事件响应, 智能分析, 智能安防, 智能视频监控, 深度学习, 生产就绪, 生产级系统, 监控系统, 目标检测, 目标识别, 自定义脚本, 规则引擎, 规则检测, 视频分析, 视频流处理, 视频片段生成, 计算机视觉, 请求拦截, 逆向工具, 部署, 高可用性, 高效查询, 高级数据库管理系统