# videoTestDemo

**Repository Path**: work_project_item/video-test-demo

## Basic Information

- **Project Name**: videoTestDemo
- **Description**: 视频人体目标跟踪系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-10-14
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 人体目标跟踪系统

## 项目简介

基于 YOLOv8 的人体目标检测与跟踪系统，提供简洁的 RESTful API 服务，专注于核心检测功能。

## 核心特性

- **智能检测与跟踪**：基于 YOLOv8l 的高精度人体检测和 BoT-SORT 多目标跟踪
- **运动分析**：自动分析目标运动方向和轨迹
- **RESTful API**：简洁的 Web 服务接口
- **无状态设计**：轻量级，专注核心功能
- **性能监控**：实时监控 CPU 和内存使用情况
- **同步响应**：立即返回检测结果
- **灵活部署**：支持前台/后台运行模式
- **环境兼容**：经过全面测试，可在不同Linux环境下稳定运行

## 环境兼容性

本项目经过严格的环境兼容性测试，确保在不同环境下都能稳定运行：

✅ **已验证环境**：
- 无GUI服务器（云服务器）
- 有GUI桌面环境
- x86_64和ARM64架构
- 不同Linux发行版

📋 **测试工具**：
- 镜像兼容性测试：`docker/test_docker_image.sh`

⚠️ **最低系统要求**：
- CPU: 2核心
- 内存: 2GB（推荐4GB）
- 存储: 5GB可用空间
- 架构: x86_64 (AMD64)

## 项目结构

```
peopleDemo01/
├── api/                               # API路由层
│   └── routes/
│       ├── system.py                  # 系统管理接口
│       ├── tasks.py                   # 检测任务接口
│       └── files.py                   # 文件管理接口
├── services/                          # 业务逻辑层
│   ├── detect_service.py              # 检测服务（核心）
│   ├── file_service.py                # 文件服务
│   └── system_service.py              # 系统服务
├── docker/                            # Docker 部署配置
│   ├── Dockerfile                     # 镜像构建文件
│   ├── docker-compose.yml             # 编排配置
│   ├── build_docker_release.sh        # 一键打包脚本
│   ├── test_docker_image.sh           # 镜像兼容性测试脚本
│   ├── DOCKER_COMMANDS.md             # Docker命令参考文档
│   ├── README.md                      # Docker 说明
│   └── README_DOCKER.md               # 用户部署文档
├── test_video/                        # 测试视频文件
├── output/                            # 输出结果（自动创建）
├── uploads/                           # 上传文件（自动创建）
├── logs/                              # 后台运行日志（自动创建）
├── venv/                              # Python虚拟环境（自动创建）
├── api_server.py                      # API服务主程序
├── start_api.py                       # API启动脚本（支持前台/后台）
├── stop_api.py                        # 停止后台服务脚本
├── deploy.sh                          # 一键部署脚本（Linux原生）
├── people_tracker.py                  # 核心跟踪算法
├── tracker_utils.py                   # 工具类库
├── demo_detect.py                     # 本地直接调用演示脚本
├── test_from_url_api.py               # API测试脚本
├── performance_monitor.py             # 性能监控模块
├── performance_report_generator.py    # 性能报告生成器
├── video_repair.py                    # 视频修复工具
├── install_python3.12.sh              # Python 3.12 安装脚本（CentOS 7.9）
├── yolov8l.pt                         # YOLO模型文件
├── requirements.txt                   # Python依赖包
└── README.md                          # 项目文档
```

## 快速开始

### 方式一：Docker 部署（推荐）

使用 Docker 快速部署，无需配置 Python 环境：

```bash
# 在项目根目录执行
bash docker/build_docker_release.sh

# 生成分发包: peopleDemo01-docker-release-v3.0.0.tar.gz
# 发送给用户后，用户只需：
tar -xzf peopleDemo01-docker-release-v3.0.0.tar.gz
cd peopleDemo01-docker-release/
docker load -i people-tracker-v3.0.0.tar.gz
docker-compose up -d
```

详细说明请查看 [docker/README.md](docker/README.md) 和 [docker/README_DOCKER.md](docker/README_DOCKER.md)

### 方式二：Linux 原生部署（传统方式）

使用部署脚本自动完成环境检测、依赖安装和服务启动：

```bash
# 交互式部署（推荐）
bash deploy.sh

# 自动部署（使用默认配置）
bash deploy.sh --auto

# 指定端口和运行模式
bash deploy.sh --port 8001 --background
```

部署脚本会自动完成：
- Python 环境检测（>= 3.8）
- 系统依赖检查（OpenCV 所需库）
- 虚拟环境创建和激活
- Python 依赖包安装
- 必要目录创建（uploads, output, logs, temp）
- 服务启动（交互式选择端口和运行模式）

### 方式三：手动安装

#### 1. 安装依赖

```bash
# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
```

### 2. 启动 API 服务

#### 前台运行（默认）

```bash
# 使用默认端口 8000（前台运行，Ctrl+C 停止）
python start_api.py

# 自定义端口
python start_api.py --port 8001

# 生产环境启动（禁用自动重载）
python start_api.py --host 0.0.0.0 --port 8000 --no-reload
```

#### 后台运行

```bash
# 后台运行（关闭终端后继续运行）
python start_api.py --background

# 后台运行并自定义端口
python start_api.py --background --port 8001

# 后台运行并指定主机
python start_api.py --background --host 0.0.0.0 --port 8000
```

#### 服务管理

```bash
# 停止后台服务
python stop_api.py

# 检查服务状态
python stop_api.py --status

# 强制删除 PID 文件
python stop_api.py --force
```

**注意**：
- 前台运行：终端关闭时服务停止，适合开发调试
- 后台运行：服务独立运行，适合生产环境
- 后台运行时日志输出到 `logs/api_server_*.log` 文件
- PID 文件保存在 `api_server.pid`

### 3. 访问服务

- **API 文档**：http://localhost:8000/docs
- **ReDoc 文档**：http://localhost:8000/redoc
- **健康检查**：http://localhost:8000/api/system/health

## API 使用指南

### API测试脚本

项目提供了API测试脚本（`test_api.py`），方便在宿主机上测试Docker部署的服务。

#### 配置方式

**方式1：修改脚本配置（推荐）**

直接编辑 `test_api.py` 文件顶部的默认配置：

```python
# 服务器配置
DEFAULT_HOST = "10.14.215.35"  # 修改为你的服务器IP
DEFAULT_PORT = 16001           # 服务端口

# 测试视频配置
DEFAULT_VIDEO = "test_video/Video_people_02.mp4"  # 默认测试视频
```

配置后直接运行：

```bash
# 安装依赖
pip install requests

# 直接运行（使用脚本中的默认配置）
python test_api.py

# 健康检查
python test_api.py --health-only

# 生成标注视频
python test_api.py --generate-video
```

**方式2：使用命令行参数（覆盖默认配置）**

```bash
# 指定服务器和视频
python test_api.py --host 192.168.1.100 --video test_video/Video_people_02.mp4

# 自定义检测参数
python test_api.py --fps 3 --conf 0.3 --timeout 1200

# 查看所有参数
python test_api.py --help
```

**参数说明**：
- `--host`：服务器IP或域名
- `--port`：服务端口（默认16001）
- `--video`：测试视频文件路径
- `--health-only`：只执行健康检查
- `--generate-video`：生成标注视频
- `--performance`：启用性能监控
- `--fps`：处理帧率（默认5）
- `--conf`：置信度阈值（默认0.5）
- `--timeout`：请求超时时间（秒，默认600）

### 核心接口

#### 1. 系统管理

```bash
# 健康检查
GET /api/system/health
```

#### 2. 文件管理

```bash
# 上传视频文件
POST /api/files/upload
  - file: 视频文件
  
返回: file_url（用于检测）

# 下载结果文件
GET /api/files/download/{filename}

# 获取文件列表
GET /api/files/list
```

#### 3. 视频检测

```bash
# 执行检测（从URL或本地路径）
POST /api/tasks/from-url
  - video_url: 视频URL或文件路径（必填）
  - target_fps: 处理帧率（默认：5）
  - conf_threshold: 置信度阈值（默认：0.5）
  - generate_video: 是否生成视频（默认：false）
  - streaming_mode: 流式处理（默认：true）
  - enable_performance_monitoring: 性能监控（默认：false）
  - enable_video_repair: 视频修复（默认：false）

返回: 同步返回检测结果和文件下载链接
```

### 使用示例

### 本地直接调用（推荐用于脚本和批量处理）

使用 `demo_detect.py` 脚本直接调用检测方法，无需启动API服务：

#### 方法1：直接运行脚本

```bash
# 修改 demo_detect.py 中的视频路径
python demo_detect.py
```

#### 方法2：在代码中调用

```python
from demo_detect import detect_video

# 执行检测
result = detect_video(
    video_path="test_video/Video_people_02.mp4",
    output_dir="output",
    target_fps=5,
    conf_threshold=0.5,
    generate_video=True
)

# 获取结果
if result:
    stats = result.get('statistics', {})
    print(f"检测到 {stats.get('total_targets', 0)} 个目标")
    print(f"移出画面: {stats.get('exited_targets', 0)} 个")
```

### 通过API调用

#### Python 调用

```python
import requests

# 步骤1：上传视频文件
with open('test_video/Video_people_02.mp4', 'rb') as f:
    upload_response = requests.post(
        'http://localhost:8000/api/files/upload',
        files={'file': f}
    )
    upload_result = upload_response.json()
    file_url = upload_result['data']['file_url']
    print(f"文件上传成功: {file_url}")

# 步骤2：执行检测（同步返回）
detect_response = requests.post(
    'http://localhost:8000/api/tasks/from-url',
    json={
        'video_url': file_url,
        'target_fps': 5,
        'conf_threshold': 0.5
        # 可选参数（已使用默认值）：
        # 'generate_video': False,  # 不生成标注视频
        # 'streaming_mode': True,   # 流式处理
        # 'enable_performance_monitoring': False,  # 不监控性能
        # 'enable_video_repair': False  # 不启用视频修复
    }
)
detect_result = detect_response.json()

# 步骤3：获取检测结果（直接在响应中）
detection = detect_result['data']['detection_result']
stats = detection['statistics']
print(f"检测到 {stats['total_targets']} 个目标")
print(f"移出画面: {stats['exited_targets']} 个")

# 可选：下载标注视频（如果generate_video=True）
result_files = detect_result['data'].get('result_files', {})
if 'tracked_video' in result_files:
    video_url = result_files['tracked_video']['download_url']
    print(f"标注视频: {video_url}")
```

#### cURL 调用

```bash
# 1. 上传视频文件
curl -X POST "http://localhost:8000/api/files/upload" \
  -F "file=@test_video/Video_people_02.mp4"

# 返回的 file_url: uploads/20241015_xxx_Video_people_02.mp4

# 2. 执行检测
curl -X POST "http://localhost:8000/api/tasks/from-url" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "uploads/20241015_xxx_Video_people_02.mp4",
    "target_fps": 5,
    "conf_threshold": 0.5
  }'

# 3. 下载结果
curl "http://localhost:8000/api/files/download/{filename}" -o result.json
```

## 输出说明

### JSON 结果格式

```json
{
  "video_info": {
    "width": 1920,
    "height": 1080
  },
  "exited_targets": [
    {
      "target_id": 0,
      "movement_direction": "up"
    }
  ],
  "statistics": {
    "total_targets": 5,
    "exited_targets": 2,
    "targets_moved_up": 1,
    "targets_moved_down": 1
  }
}
```

### 输出文件类型

- **tracked_video**：带标注的跟踪视频（MP4）
- **json_result**：跟踪结果数据（JSON）
- **performance_data**：性能监控数据（JSON）
- **performance_report**：性能分析报告（Markdown）

## 技术架构

### 核心技术栈

- **Web 框架**：FastAPI（异步、高性能）
- **目标检测**：YOLOv8l（Ultralytics）
- **目标跟踪**：BoT-SORT（高精度多目标跟踪）
- **视频处理**：OpenCV

### 架构设计

```
┌─────────────┐
│   Client    │  HTTP 请求
└──────┬──────┘
       │
┌──────▼──────────────────────┐
│     API Layer (routes/)     │  路由层：请求处理、参数验证
├─────────────────────────────┤
│   Service Layer (services/) │  服务层：业务逻辑、检测处理
└──────┬──────────────────────┘
       │
┌──────▼──────┐
│  File System │  文件存储
└─────────────┘
```

### 处理流程

1. **文件上传**：客户端上传视频 → 保存到 uploads/ 目录 → 返回文件路径
2. **执行检测**：传入文件路径 → 执行检测和跟踪 → 同步返回结果
3. **下载结果**：客户端根据返回的链接下载结果文件

## 开发指南

### 工具类库

项目提供了完整的工具类库（`tracker_utils.py`），便于二次开发：

- `VideoProcessor`：视频读写和处理
- `TrajectoryAnalyzer`：轨迹分析和运动方向判断
- `Visualizer`：可视化绘制
- `ResultExporter`：结果导出
- `FrameAnnotator`：帧标注

### 扩展开发

```python
from tracker_utils import VideoProcessor, TrajectoryAnalyzer
from ultralytics import YOLO

# 自定义处理逻辑
processor = VideoProcessor('input.mp4')
analyzer = TrajectoryAnalyzer(1920, 1080)
model = YOLO('yolov8l.pt')

# 实现自定义功能
# ...
```

## 常见问题

### 部署相关

#### 如何在 Linux 服务器上快速部署？

使用一键部署脚本：
```bash
bash deploy.sh
```

#### 部署脚本支持哪些参数？

```bash
bash deploy.sh --help         # 查看帮助
bash deploy.sh --auto         # 自动部署（默认配置）
bash deploy.sh --port 8001    # 指定端口
bash deploy.sh --background   # 后台运行
```

#### 如何使用国内镜像加速依赖安装？

如果部署脚本安装依赖较慢，可以手动安装：
```bash
source venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

#### 无GUI服务器能否部署OpenCV？

**可以**，项目已针对无GUI服务器环境优化。

**技术说明**：
- 项目使用 `opencv-python-headless` 版本（无GUI依赖）
- 不依赖X11、GTK、Qt等图形界面库
- 适用于所有无GUI的Linux服务器环境（如Docker容器、云服务器）

**功能说明**：
- 视频读写、图像处理功能完全正常
- `show_display` 参数默认为 `False`（不影响使用）
- 所有API接口和核心检测功能不受影响

**部署建议**：
```bash
# 在无GUI服务器上正常部署即可
bash deploy.sh --auto --background

# 或手动安装
pip install -r requirements.txt
```

**注意**：如果你需要在开发环境使用实时显示功能（`show_display=True`），请手动安装有GUI支持的版本：
```bash
pip uninstall opencv-python-headless
pip install opencv-python>=4.8.0
```

### 服务运行

#### 端口冲突

**错误**：`Address already in use`

**解决**：
```bash
# 使用其他端口
python start_api.py --port 8001
# 或使用部署脚本
bash deploy.sh --port 8001
```

### 处理速度慢

**优化方案**：
- 降低处理帧率：`target_fps=3`
- 降低置信度阈值：`conf_threshold=0.3`
- 使用更小的模型：`yolov8m.pt` 或 `yolov8s.pt`
- 启用 GPU 加速（需要 CUDA）

### 内存占用高

**优化方案**：
- 启用流式处理：`streaming_mode=true`
- 降低处理帧率
- 禁用视频生成：`generate_video=false`

## 设计理念

### v3.0 - 简化版设计思想

1. **专注核心功能**：只做检测，不做任务管理
2. **无状态设计**：不维护任务状态，调用即返回
3. **轻量级**：移除数据库、队列等重型组件
4. **业务解耦**：任务调度交给业务层实现

### 为什么简化？

- **单一职责**：这是一个检测服务，不是任务管理系统
- **更灵活**：业务层可以自由选择任务调度方案
- **易维护**：代码更简洁，依赖更少
- **易部署**：无需配置数据库等外部依赖

## 环境要求

- Python 3.8+
- 推荐 Python 3.12.10（项目开发版本）
- 最低兼容 Python 3.8

### CentOS 7.9 安装 Python 3.12.10

如果您的系统是 CentOS 7.9，可以使用项目提供的一键安装脚本：

```bash
# 使用 root 权限运行安装脚本（使用国内镜像源，速度快）
sudo bash install_python3.12.sh
```

脚本会自动完成（约 15-30 分钟）：
- 安装编译所需依赖
- 从阿里云等国内镜像下载 Python 3.12.10 源码
- 编译并安装到项目目录 `python3.12/`（项目私有，不影响系统）
- 自动创建虚拟环境 `venv/`
- 可选：自动安装项目依赖

安装完成后使用虚拟环境：

```bash
# 方式一：使用虚拟环境（推荐）
cd peopleDemo01
source venv/bin/activate
python --version          # Python 3.12.10
bash deploy.sh            # 部署项目

# 方式二：直接使用项目Python
source activate_python.sh
python3 --version
pip3 install -r requirements.txt
```

## 许可证

本项目仅供学习和研究使用。

## 更新日志

### v3.0.0 (当前版本)
- **架构简化**：移除任务管理、数据库、队列等复杂组件
- **专注核心**：只保留文件管理和检测功能
- **同步返回**：检测完成立即返回结果
- **无状态设计**：不维护任务状态，更轻量
- **保持兼容**：`/api/tasks/from-url` 接口路径不变
- **更易维护**：代码量减少60%+，依赖更少

### v2.1.0
- 架构重构：遵循单一职责原则
- 拆分上传和任务创建接口
- 支持URL和本地路径

### v2.0.0
- 三层架构设计（DAO/Service/API）
- SQLite 数据库持久化
- 异步任务处理队列

### v1.0.0
- 基础的视频处理和目标跟踪功能