# StreamDetect

**Repository Path**: tudengkui/stream-detection

## Basic Information

- **Project Name**: StreamDetect
- **Description**: 基于 .NET 10 + YOLOv8 ONNX 的实时视频流目标检测系统。通过 RTSP 连接任意视频源（IP 摄像头、流媒体服务器等），对视频流逐帧推理，检测到目标时自动保存带标注框的截图和元数据。检测类别由模型自动识别，上传任意 YOLOv8 训练的 ONNX 模型即可使用。提供 Web 管理界面、REST API 和 TCP 推送，支持完全离线部署。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-03
- **Last Updated**: 2026-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StreamDetect 视频流目标检测系统

基于 .NET 10 + YOLOv8 ONNX 的实时视频流目标检测系统。通过 RTSP 连接任意视频源（IP 摄像头、流媒体服务器等），对视频流逐帧推理，检测到目标时自动保存带标注框的截图和元数据。检测类别由模型自动识别，上传任意 YOLOv8 训练的 ONNX 模型即可使用。提供 Web 管理界面、REST API 和 TCP 推送，支持完全离线部署。

## 功能特性

- **多路 RTSP 取流 + 实时推理**：每路摄像头独立取流线程，推理每 500ms 一次，预览与推理解耦，流畅不卡顿
- **单张图片检测**：上传图片即时查看检测结果和标注，便于模型验证
- **Web 管理界面**（AdminLTE 3）：8 个管理页面
  - 首页仪表盘：模型数、摄像头数、今日检测量、TCP 连接状态
  - 摄像头管理：增删改查、批量启用/禁用、单个开关
  - 实时预览：多路 MJPEG 流网格布局同时预览
  - 检测记录：按摄像头/时间/置信度筛选，分页查询，图片弹窗查看
  - 图像检测：上传单张图片，原始图 vs 标注图对比展示
  - 模型管理：上传 .onnx 文件，自动读取类别标签，切换默认模型
  - TCP 推送管理：启停服务、查看连接客户端、手动广播测试消息
  - 系统设置：5 项运行参数即时生效，无需重启
- **摄像头状态管理**：未启用 / 连接中 / 运行中 / 检测中 / 连接失败，断线自动重连
- **REST API**：按条件分页查询检测记录，支持第三方系统集成
- **TCP 推送**：检测事件实时推送到连接的客户端（JSON 格式，一行一条）
- **自动清理**：每日凌晨 3 点清理过期数据和图片，保留天数可配
- **跨平台部署**：Windows 服务 / Linux systemd，自包含发布无需安装 .NET 运行时

## 技术栈

| 组件 | 技术 |
|------|------|
| 框架 | .NET 10, ASP.NET Core MVC + Razor |
| 数据库 | SQLite + EF Core（自动迁移） |
| RTSP 取流 + 图像处理 | OpenCvSharp4 |
| ONNX 推理 | Microsoft.ML.OnnxRuntime |
| 前端 UI | AdminLTE 3 + Bootstrap 5 + jQuery |
| TCP 推送 | System.Net.Sockets（Windows / Linux 跨平台） |

## 首页

![首页截图](docs/screenshots/home.png)

## 快速开始

### 环境要求

- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
- 一个 YOLOv8 ONNX 模型文件
- **Visual C++ Redistributable**（Windows 部署必需）— ONNX Runtime 依赖 VC++ 运行库加载其原生 DLL。未安装时模型上传或推理会直接崩溃。下载：[vc_redist.x64.exe](https://aka.ms/vs/17/release/vc_redist.x64.exe)

### 运行

端口在 `src/StreamDetect.Web/appsettings.json` 中通过 `"Urls"` 配置，默认 `http://0.0.0.0:5000`。

```bash
cd src/StreamDetect.Web
dotnet run
```

浏览器访问 `http://localhost:5000`，首次启动自动创建数据库。在「模型管理」页面上传 ONNX 模型，在「摄像头管理」页面添加 RTSP 视频源即可开始检测。

### 发布部署（自包含，无需安装 .NET）

```bash
dotnet publish -c Release --self-contained -o publish
```

将 `publish` 目录拷贝到目标机器，默认监听 `http://0.0.0.0:5000`。

#### Windows

- **直接运行**：双击 `StreamDetect.Web.exe`（关闭窗口则进程终止）
- **Windows 服务**（推荐，后台常驻、开机自启）：右键 `安装服务.bat` → 以管理员身份运行

| 脚本 | 说明 |
|------|------|
| `安装服务.bat` | 注册并启动服务（显示名：视频流目标检测系统） |
| `停止服务.bat` | 停止服务 |
| `卸载服务.bat` | 删除服务 |

#### Linux

```bash
chmod +x StreamDetect.Web && ./StreamDetect.Web
```

推荐配合 systemd 管理：

```ini
[Unit]
Description=StreamDetect Service
After=network.target

[Service]
Type=notify
WorkingDirectory=/opt/streamdetect
ExecStart=/opt/streamdetect/StreamDetect.Web
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable --now streamdetect
```

## 运行时配置

以下参数可在 Web 界面「系统设置」页面修改，即时生效，无需重启：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| 置信度阈值 | 0.7 | 低于此值的检测结果将被忽略 |
| 最小触发间隔 | 10 秒 | 同一摄像头两次检测记录的最小间隔 |
| 连接超时 | 5 秒 | RTSP 连接超时时间 |
| 重试间隔 | 30 秒 | RTSP 断线后重连等待时间 |
| 数据保留天数 | 30 天 | 超过此天数的检测记录和图片自动清理 |

## 目录结构

```
StreamDetect/
├── src/StreamDetect.Web/
│   ├── Controllers/           # MVC 控制器（8 个）
│   │   └── Api/               # REST API（DetectionApiController）
│   ├── Services/              # 核心服务
│   │   ├── InferenceService.cs        # ONNX 推理（单例，线程安全）
│   │   ├── CameraStreamService.cs     # 单路 RTSP 取流循环
│   │   ├── CameraServiceManager.cs    # 摄像头服务生命周期管理
│   │   ├── DetectionService.cs        # 检测记录保存与查询
│   │   ├── FrameAnnotationService.cs  # 标注框绘制
│   │   ├── TcpPushService.cs          # TCP 推送服务
│   │   ├── SettingService.cs          # 运行时设置缓存
│   │   ├── CleanupService.cs          # 定时清理
│   │   └── Config/                    # 配置类
│   ├── Data/                  # EF Core 实体与 DbContext
│   ├── Models/                # 视图模型
│   ├── Views/                 # Razor 视图（8 个页面）
│   ├── deploy/                # Windows 服务管理脚本
│   └── wwwroot/               # 静态资源（AdminLTE, Bootstrap, jQuery）
├── storage/
│   ├── models/                # ONNX 模型文件
│   └── detections/            # 检测截图（按摄像头/日期组织）
└── docs/
    └── screenshots/           # 项目截图
```

## API

### 查询检测记录

```
GET /api/detections?startTime=2026-05-09T00:00:00&endTime=2026-05-09T23:59:59&minConfidence=0.7&page=1&pageSize=20
```

**参数说明：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| startTime | datetime | 否 | 起始时间 |
| endTime | datetime | 否 | 结束时间 |
| minConfidence | float | 否 | 最低置信度 |
| page | int | 否 | 页码（默认 1） |
| pageSize | int | 否 | 每页条数（默认 20，最大 100） |

**返回格式：**

```json
{
  "total": 156,
  "page": 1,
  "pageSize": 20,
  "items": [
    {
      "id": 1,
      "label": "oil",
      "cameraName": "摄像头1",
      "deviceCode": "HK-001",
      "location": "仓库A区",
      "confidence": 0.92,
      "position": { "positionX": 120, "positionY": 80, "positionWidth": 200, "positionHeight": 150 },
      "detectedAt": "2026-05-09T14:23:05"
    }
  ]
}
```

### TCP 推送

在 Web 界面 `/Tcp` 页面启动 TCP 推送服务（默认端口 9000）。连接后每条检测事件以一行 JSON 推送：

```json
{"type":"detection","label":"oil","cameraId":1,"cameraName":"摄像头1","deviceCode":"HK-001","location":"仓库A区","confidence":0.92,"detectedAt":"2026-05-09T14:23:05"}
```

## License

[MIT](LICENSE)