# vision-train

**Repository Path**: fuxm0818_admin/vision-train

## Basic Information

- **Project Name**: vision-train
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VisionTrain - AI 视觉检测训练平台

VisionTrain 是一个基于 Web 的 AI 视觉检测训练平台，帮助您快速完成目标检测模型的训练和部署，无需编写代码。支持**图片检测**、**视频检测**、**摄像头实时检测**和**RTSP 流检测**。

## 目录

- [系统简介](#系统简介)
- [快速开始（本地开发）](#快速开始本地开发)
- [配置说明](#配置说明)
- [使用指南](#使用指南)
- [生产部署（Docker / Podman）](#生产部署docker--podman)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [常见问题](#常见问题)

---

## 系统简介

VisionTrain 让您通过可视化界面完成以下工作：

1. **创建训练场景** — 场景是数据隔离的基本单位，例如"交通监控"和"安防检测"是两个独立场景
2. **定义检测标签** — 在每个场景中定义要检测的目标类别，如"车辆"、"行人"
3. **上传并标注图片** — 上传图片后，在图片上画框标注目标位置
4. **训练 AI 模型** — 配置训练参数，一键启动训练
5. **使用模型检测** — 训练完成后，用模型对新图片、视频或实时流进行目标检测

### 工作流程

```
创建场景 → 定义标签 → 上传图片 → 标注图片 → 训练模型 → 部署检测
```

### 核心能力

| 能力 | 说明 |
|------|------|
| 图片标注 | 上传图片，画框标注目标，支持 AI 预标注 |
| 模型训练 | 配置超参数，启动 YOLOv8 训练任务 |
| 图片检测 | 用训练好的模型对单张图片进行检测 |
| 视频检测 | 上传视频文件，按帧率抽帧检测，生成标注视频并支持在线播放/下载 |
| 摄像头检测 | 通过本地摄像头实时捕获画面，YOLOv8 检测并叠加检测框，支持录像导出 |
| 流检测与推流输出 | 支持 RTSP/RTMP/Camera/File 多输入源，实时推理 + Canvas 渲染，可选 RTMP 推流输出带标注的视频流（集成 MediaMTX 多协议分发） |

---

## 快速开始（本地开发）

> **当前方案**：本地只运行前后端代码，MySQL 和 Redis 使用远程服务器上的共享实例。
> 本地无需安装 MySQL/Redis/Docker。

### 前置条件

| 软件 | 版本 | 用途 |
|------|------|------|
| Python | 3.10+ | 运行后端 |
| Node.js | 18+ | 运行前端 |
| uv | 最新版 | Python 依赖管理 |

> 验证：`python3 --version` / `node --version` / `uv --version`

### 第一步：配置数据库连接

MySQL 和 Redis 部署在远程服务器上，配置通过 `backend/.env` 文件管理：

```bash
# backend/.env
DATABASE_URL=mysql+aiomysql://root:Admin123%21%40%23@180.76.227.117:13306/vision_train
REDIS_URL=redis://:Admin123%21%40%23@180.76.227.117:16379/0
```

> 密码中的特殊字符（`!@#`）已做 URL 编码：`!` → `%21`，`@` → `%40`，`#` → `%23`

### 第二步：启动后端

```bash
cd backend

# 安装 Python 依赖（首次约 2-3 分钟）
uv sync

# 创建数据库表（首次执行）
uv run python -c "
from models.base import Base
from database import _get_engine
import asyncio

async def init():
    engine, _ = _get_engine()
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

asyncio.run(init())
"

# 启动后端（开发模式，代码修改自动重启）
PYTHONPATH=. uv run uvicorn main:app --reload --port 8000
```

启动成功后：
- API 服务：http://localhost:8000
- API 文档（Swagger）：http://localhost:8000/docs
- 健康检查：http://localhost:8000/api/health

### 第三步：启动前端

打开**新终端**（保留后端运行）：

```bash
cd frontend

# 安装依赖（首次执行）
npm install

# 启动前端开发服务器
npm run dev
```

浏览器访问 **http://localhost:3000** 即可使用。

### 第五步：注册账号

系统**没有默认账号**，首次使用需要注册：

1. 打开 http://localhost:3000，看到登录/注册页面
2. 点击 **"注册"** 标签
3. 输入用户名和密码，点击注册
4. 切换到 **"登录"** 标签，用刚注册的账号登录

---

## 配置说明

所有配置集中在 `backend/config.py`，通过环境变量或直接修改文件来配置：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `DATABASE_URL` | `mysql+aiomysql://root:root@localhost:3306/vision_train` | MySQL 连接地址，格式：`mysql+aiomysql://用户:密码@主机:端口/数据库名` |
| `REDIS_URL` | `redis://localhost:6379/0` | Redis 连接地址 |
| `SECRET_KEY` | `dev-secret-change-in-production` | JWT 签名密钥，**生产环境必须更换**（生成：`openssl rand -hex 32`） |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `1440`（24 小时） | 登录过期时间，超时后需重新登录 |
| `DATA_DIR` | `./data` | 数据存储目录（图片、标注、模型权重等） |

### 环境变量覆盖

你也可以通过环境变量覆盖配置，无需修改代码：

```bash
export DATABASE_URL="mysql+aiomysql://myuser:mypass@192.168.1.100:3306/vision_train"
export REDIS_URL="redis://192.168.1.100:6379/0"
export SECRET_KEY="your-production-secret-key"
```

---

## 使用指南

首次登录后，系统会弹出**新手引导**，带你逐步了解每个功能模块。以下是完整使用流程：

### 完整流程

```
登录 → 仪表盘 → 创建场景 → 定义标签 → 上传图片 → 标注图片 → 训练模型 → 使用模型检测（图片/视频/摄像头/流检测与推流）
```

### 1. 仪表盘

登录后看到的第一个页面，展示系统概览统计数据（场景数、标签数、模型数、已标注图片数）。

### 2. 训练场景（场景管理）

场景是数据隔离的基本单位。例如，你可以创建"交通监控"和"安防检测"两个独立场景，它们的标签、图片、模型互不干扰。

- 点击左侧 **"训练场景"** → 点击 **"新建场景"**
- 输入场景名称和描述，点击确认

### 3. 标签管理

为场景定义要检测的目标类别。

- 点击左侧 **"标签管理"**
- 选择一个场景，输入标签名称（如"车辆"、"行人"、"红绿灯"）
- 支持添加多个标签

### 4. 图片标注

上传图片并用矩形框标注目标位置。

- 点击左侧 **"图片标注"**
- 选择一个场景，上传图片
- 在图片上拖拽绘制矩形框，选择对应的标签
- 支持 AI 预标注：选择一个已训练的模型，自动标注后再人工修正

### 5. 模型训练

配置训练参数，启动 YOLOv8 训练。

- 点击左侧 **"模型训练"**
- 选择训练场景（必填）
- 预训练模型（可选）：选择已有的模型作为基础进行迁移学习，不选则使用 YOLO 默认权重从头训练
- 配置训练参数（epochs、batch_size、学习率等），或使用默认参数
- 点击 **"开始训练"**，等待训练完成

> 训练参数也可以在 **"参数配置"** 页面统一管理，多个训练任务可复用同一套参数。
> 预训练模型来自「模型管理」中已训练完成的模型，训练完成后即可在后续训练中作为基础模型使用。

### 6. 模型管理

查看训练产出的模型，启用/禁用模型。

- 点击左侧 **"模型管理"**
- 查看所有模型的训练状态、精度指标
- 训练完成的模型可**启用**，启用的模型才能用于检测

### 7. 使用模型检测

训练并启用模型后，可通过以下方式使用：

| 检测方式 | 路径 | 适用场景 |
|----------|------|---------|
| 图片检测 | 在图片标注页选择模型后检测 | 单张图片分析 |
| 视频检测 | 左侧 **"视频检测"** | 上传视频文件，批量检测 |
| 摄像头检测 | 左侧 **"摄像头检测"** | 本地摄像头实时检测 |
| RTSP 流检测 | 左侧 **"实时流检测"** | IPC 摄像头 RTSP 流实时检测 |

### 视频检测

1. 进入 **"视频检测"** 页面
2. 上传视频文件（支持 mp4/avi/mov/mkv/flv/wmv，最大 500MB）
3. 选择模型、设置检测帧率（1-30 fps）和置信度阈值（0.1-0.9）
4. 点击 **"开始检测"**，实时查看进度
5. 检测完成后可在线播放标注视频或下载

### 摄像头检测

1. 进入 **"摄像头检测"** 页面
2. 浏览器会请求摄像头权限，点击允许
3. 选择检测模型、设置帧率和置信度
4. 点击 **"开始检测"**，画面实时显示检测框
5. 支持录像导出

> 摄像头功能需要 `https` 或 `localhost` 访问，通过 IP 访问会被浏览器阻止。

### RTSP 流检测

1. 进入 **"实时流检测"** 页面
2. 输入 RTSP 地址（如 `rtsp://192.168.1.100:554/stream`）
3. 选择模型、设置帧率和置信度
4. 点击 **"开始检测"**
5. Canvas 实时绘制视频帧和检测框，支持截图保存

---

## 生产部署（Docker / Podman）

使用容器编排一键部署所有服务（5 个容器）：

| 容器 | 说明 | 端口 |
|------|------|------|
| mysql | MySQL 8.0 数据库 | 3306 |
| redis | Redis 7 缓存 | 6379 |
| backend | FastAPI 后端 | 8000 |
| frontend | Nginx + 前端静态文件 | 80 |
| mediamtx | MediaMTX 流媒体中转（RTSP/HLS/RTMP 多协议分发） | 8554 / 1935 / 8888 / 8889 |

> MediaMTX 用于流检测的推流输出：后端把标注后的画面以 RTMP 推到 MediaMTX，前端再通过 RTSP/HLS 拉流播放。如不使用流检测推流功能，可在 `docker-compose.yml` 中移除该服务。

### 一键部署

```bash
# Docker 方式
docker compose up -d

# Podman 方式
podman compose up -d
```

部署完成后，直接访问 **http://你的服务器IP** 即可使用。

### 生产环境配置（部署前必读）

1. **修改数据库密码**：编辑 `docker-compose.yml`，修改 `MYSQL_ROOT_PASSWORD`
2. **修改 JWT 密钥**：编辑 `backend/config.py`，修改 `SECRET_KEY`
   - 生成方式：`openssl rand -hex 32`
3. **挂载数据目录**：在 `docker-compose.yml` 中配置 `data_volume` 指向持久化存储路径

---

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端框架 | React 19 + TypeScript | 使用 Vite 构建 |
| UI 组件库 | Ant Design 5 | 企业级 UI 组件 |
| 状态管理 | Zustand | 轻量级状态管理 |
| 后端框架 | FastAPI (Python 3.10+) | 异步 Web 框架 |
| ORM | SQLAlchemy 2.0 | 异步数据库操作 |
| 数据库 | MySQL 8.0 | 主数据存储 |
| 缓存 | Redis 7 | 训练参数缓存 |
| AI 引擎 | YOLOv8 (ultralytics) | 目标检测模型 |
| 视频处理 | OpenCV + FFmpeg | 视频抽帧和标注 |
| 实时通信 | WebSocket | 视频检测进度推送 |
| 认证 | JWT + bcrypt | 用户认证和权限 |
| 部署 | Docker Compose / Podman | 容器化部署 |

---

## 项目结构

```
vision-train/
├── backend/                    # 后端（Python FastAPI）
│   ├── main.py                # 应用入口，注册路由、中间件、WebSocket
│   ├── config.py              # 配置文件（数据库、Redis、JWT、DATA_DIR 等）
│   ├── database.py            # 数据库连接管理（异步引擎）
│   ├── redis_client.py        # Redis 连接管理
│   ├── init_admin.py          # 初始化/重置管理员账号脚本
│   ├── api/                   # API 路由
│   │   ├── auth.py            # 用户认证（注册/登录）
│   │   ├── scene.py           # 场景管理（增删改查）
│   │   ├── label.py           # 标签管理
│   │   ├── annotation.py      # 图片上传/标注/图片文件读取
│   │   ├── training.py        # 模型训练
│   │   ├── model.py           # 模型管理
│   │   ├── detection.py       # 图片检测 + 摄像头单帧检测（/api/detect/frame）
│   │   ├── params.py          # 参数配置
│   │   ├── video.py           # 视频上传/检测任务创建
│   │   ├── video_task.py      # 视频任务查询/删除/播放/下载
│   │   └── stream.py          # RTSP/RTMP/摄像头/文件 流检测任务
│   ├── models/                # 数据库模型（SQLAlchemy）
│   │   ├── base.py            # 基类和时间戳混入
│   │   ├── user.py            # 用户/角色/权限
│   │   ├── scene.py           # 场景/标签/图片/标注
│   │   ├── training.py        # 训练任务/参数
│   │   ├── model.py           # 模型
│   │   ├── detection.py       # 检测结果
│   │   ├── video.py           # 视频/视频检测任务
│   │   └── stream.py          # 流检测任务（含推流字段）
│   ├── schemas/               # 请求/响应 Schema（Pydantic）
│   │   ├── auth.py · scene.py · label.py · annotation.py
│   │   ├── training.py · model.py · detection.py · params.py
│   │   └── video.py · stream.py
│   ├── services/              # 业务逻辑层
│   │   ├── auth_service.py    # 认证服务（密码哈希/JWT/权限）
│   │   ├── yolo_service.py    # YOLOv8 推理服务（模型缓存）
│   │   ├── video_service.py   # 视频检测引擎（抽帧/推理/标注）
│   │   ├── video_processor.py # 视频处理工具（OpenCV 封装）
│   │   ├── stream_service.py  # 流检测引擎（基于 VideoSource）
│   │   ├── video_source.py    # 多输入源抽象（RTSP/RTMP/摄像头/文件）
│   │   ├── push_service.py    # FFmpeg RTMP 推流引擎
│   │   ├── websocket_manager.py # WebSocket 连接管理
│   │   └── task_manager.py    # 异步任务管理（支持取消）
│   ├── middleware/            # 中间件
│   │   └── auth.py            # JWT 认证和权限校验
│   └── tests/                 # 单元测试（21 个测试文件，108 用例）
├── frontend/                   # 前端（React + TypeScript）
│   ├── src/
│   │   ├── main.tsx           # 应用入口
│   │   ├── App.tsx            # 路由和权限守卫
│   │   ├── api/
│   │   │   ├── client.ts      # API 客户端（axios 封装）
│   │   │   ├── auth 通过 stores 管理，其余按模块拆分
│   │   │   ├── scene.ts · label.ts · annotation.ts · model.ts
│   │   │   ├── training.ts · params.ts · video.ts · camera.ts
│   │   ├── stores/
│   │   │   └── auth.ts        # 认证状态管理（Zustand）
│   │   ├── components/
│   │   │   └── OnboardingTour.tsx  # 新手引导组件
│   │   └── pages/
│   │       ├── Login.tsx       # 登录/注册页
│   │       ├── AppLayout.tsx   # 主布局（侧边栏+顶栏+内容）
│   │       ├── Dashboard.tsx   # 仪表盘
│   │       ├── ScenePage.tsx   # 场景管理
│   │       ├── LabelPage.tsx   # 标签管理
│   │       ├── AnnotationPage.tsx # 图片标注
│   │       ├── TrainingPage.tsx   # 模型训练
│   │       ├── ModelPage.tsx      # 模型管理
│   │       ├── ParamsPage.tsx     # 参数配置
│   │       ├── VideoDetectionPage.tsx  # 视频检测
│   │       ├── CameraDetectionPage.tsx # 摄像头检测（前端 getUserMedia）
│   │       └── StreamDetectionPage.tsx # 流检测（RTSP/RTMP/摄像头/文件 + 推流）
│   └── package.json
├── data/                       # 数据存储目录
│   └── videos/                 # 视频文件（原始+标注）
├── docker-compose.yml          # 容器编排（mysql/redis/backend/frontend/mediamtx）
├── Dockerfile.backend          # 后端镜像
├── Dockerfile.frontend         # 前端镜像
├── nginx.conf                  # Nginx 配置（生产部署）
├── mediamtx.yml                # MediaMTX 流媒体中转配置
└── README.md                   # 本文件
```

> 说明：摄像头检测不单独设后端路由，而是在 `CameraDetectionPage` 前端通过 `getUserMedia` 抓帧，调用 `POST /api/detect/frame`（`detection.py`）做 YOLOv8 推理后回传检测框。

---

## 常见问题

### Q: 系统有默认账号吗？
A: 没有。需要在登录页点击"注册"创建账号。忘记密码可通过重置数据库重新注册。

### Q: 启动后端报错 `ModuleNotFoundError: No module named 'xxx'`
A: 确认在 `backend` 目录下执行了 `uv sync` 安装依赖。

### Q: 启动后端报错数据库连接失败
A:
1. 确认 MySQL 服务已启动，可正常连接
2. 检查 `backend/config.py` 中 `DATABASE_URL` 的地址、端口、用户名、密码是否正确
3. 确认数据库 `vision_train` 已创建（或首次运行时自动创建表）

### Q: 前端页面空白或接口报错
A: 确认后端服务已启动在 8000 端口。前端开发服务器会自动代理 `/api` 请求到后端。

### Q: 视频检测任务一直卡在"等待中"
A: 检查后端日志，常见原因：
- 模型权重文件不存在（检查 Model 表的 weight_path）
- 视频文件损坏（重新上传）
- OpenCV 无法读取视频（确认视频格式支持）

### Q: 视频检测很慢
A: 降低检测帧率（如从 5 改为 1-2），或缩短视频时长。帧率越高耗时越长。

### Q: 如何重置数据库？
A: 连接到 MySQL 后执行 `DROP DATABASE vision_train; CREATE DATABASE vision_train;`，然后重新运行创建表命令。

### Q: 如何修改默认端口？
A:
- 后端端口：修改启动命令 `--port 8000` 为其他端口
- 前端端口：修改 `frontend/vite.config.ts` 中的 `server.port`

### Q: 摄像头检测页面无法开启摄像头
A: 摄像头功能（getUserMedia）需要安全上下文，仅在以下环境可用：
- `https://` 协议访问
- `http://localhost` 或 `http://127.0.0.1`（本地开发）

如果通过 `http://<服务器IP>` 访问，浏览器会阻止摄像头访问。请配置 HTTPS（如 Nginx + SSL 证书）或使用 localhost 访问。

### Q: 摄像头检测画面卡顿
A: 降低检测帧率（如从 5 改为 1-2 fps），或降低摄像头分辨率。检测帧率越高，对后端推理压力越大。