UltraConsole：基于 YOLOv8 的 Web 端工业级目标检测推理控制台

GitHub: github.com/WangQvQ/ultraconsole | License: MIT | 中文文档 / English README

项目简介

UltraConsole 是一个面向工业质检、安防监控、算法调优场景的 Web 端目标检测可视化推理控制台。基于 Ultralytics YOLOv8，提供从前端到后端的完整全栈解决方案，支持图像、视频、摄像头、RTSP 流、多路监控墙等输入方式，覆盖目标检测、实例分割、姿态估计、多目标跟踪等任务，具备实时 OSD 可视化、越线/区域计数事件、告警推送、系统监控、配置迁移等完整功能链路。

核心特性

多源输入

• 图像推理：支持上传与拖拽，参数变更自动重跑
• 视频推理：本地视频文件抽帧推理，可配置目标 FPS
• Webcam 实时推理：基于浏览器 getUserMedia + WebSocket 推帧
• RTSP 流接入：后端 OpenCV 拉流，JPEG 编码后经 WebSocket 实时推送
• 多路监控墙：1×1 至 3×3 网格布局，单条 WebSocket 多路复用 streamId，支持多路 RTSP 同屏展示

推理任务支持

• 目标检测（Detection）
• 实例分割（Instance Segmentation）
• COCO-17 姿态估计（Pose Estimation）
• ByteTrack 多目标跟踪（Multi-Object Tracking）

可视化与交互

• BBox、标签、实例分割 Mask、姿态关键点骨架、跟踪轨迹尾迹
• 按 trackId 哈希生成稳定颜色，跨帧一致
• ROI（感兴趣区域）多边形/矩形绘制，支持"仅显示 ROI 内目标"过滤
• 计数线 / 计数区绘制，自动统计穿越 in/out 与进出 enter/leave
• 空间热力图（Spatial Heatmap）
• Telemetry HUD：FPS、预处理/推理/后处理耗时

监控与告警

• 系统资源监控：CPU、内存、多 GPU 利用率/显存/温度/功耗
• 推理延迟 P50 / P95 / P99 + sparkline 迷你图
• 结构化事件日志 + CSV 导出
• 告警引擎：类别连续 N 帧触发，界面红色呼吸边框 + 蜂鸣
• Webhook 推送：钉钉、企业微信、飞书、Slack、通用 JSON 五种格式，按 (kind, ref) 维度冷却去重

配置管理

• 全应用状态一键导出为 JSON（参数、引擎、OSD、ROI、计数线区、告警、Webhook）
• 拖拽 JSON 到面板即导入，跨机器配置迁移

国际化

• 中文 / English 双语界面，一键切换，默认中文

技术架构

层级	技术选型
前端框架	React 19 + TypeScript 6 + Vite 8
状态管理	Zustand 5（单全局 Store）
样式方案	CSS Modules + CSS Custom Properties（Neo-Skeuomorphism 暗黑主题）
后端框架	Python 3.10 + FastAPI 0.115 + Uvicorn
推理引擎	Ultralytics YOLOv8（支持 .pt / .onnx / .engine）
视频处理	OpenCV（RTSP 解码、JPEG 编码）
通信协议	REST API + WebSocket（/ws/infer、/ws/stream）

架构设计要点

• Canvas OSD 渲染：所有高频图形更新（BBox、Mask、Keypoint、轨迹、热力图）均在 HTML Canvas 绘制，与 React 渲染周期完全解耦
• 非阻塞推理链路：YOLO 推理通过 asyncio.to_thread 放入线程池，REST 与多路 WebSocket 互不阻塞；threading.Lock 保证 Ultralytics 调用线程安全
• 丢帧策略：实时源采用"仅处理最新帧"模式，配合 WebSocket bufferedAmount 背压控制
• WebSocket 自动重连：指数退避（1s 至 15s）+ ping/pong 心跳，断线后自动续播 RTSP
• 可选依赖降级：psutil、pynvml、httpx 均为可选，安装失败不影响核心推理功能
• 安全：模型路径白名单校验，防止路径穿越攻击

快速部署

后端

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001

前端

cd frontend
npm install
npm run dev

Vite 开发服务器自动代理 /api 与 /ws 至后端，打开浏览器即可使用。

适用场景

• 工业质检：生产线摄像头接入，实时缺陷检测与可视化
• 安防监控：多路摄像头同屏监控，越线/进区事件计数与告警推送
• 算法调优：模型热切换、参数热更新、BadCase 一键导出、配置迁移
• 技术验证：零代码上手的 YOLOv8 推理可视化 Demo

开源信息

• 仓库：github.com/WangQvQ/ultraconsole
• 许可证：MIT
• 欢迎 Star / Issue / Pull Request