# hyhPocProject

**Repository Path**: agent-project/hyh-poc-project

## Basic Information

- **Project Name**: hyhPocProject
- **Description**: 红沿河poc 演示项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-11
- **Last Updated**: 2025-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视频检测告警系统

## 项目概述

这是一个基于Flask的视频检测告警系统，支持多视频播放、算法配置管理和实时检测功能。

## 视频唯一标识系统

### 统一后端维护架构

项目采用**统一后端维护**的视频标识系统，确保数据一致性和架构简洁性。

#### 架构设计原则

- **后端统一管理**：所有视频文件扫描、MD5标识生成、数据存储都在后端完成
- **前端只负责展示**：前端通过API获取后端维护的视频信息，不重复维护数据
- **数据一致性**：避免前后端数据不一致的问题
- **视频ID优先**：算法配置中优先使用视频ID存储，避免文件名变更导致的问题

#### 视频ID生成策略

**基于文件名的ID生成**：
```python
# 基于文件名生成MD5标识
def generate_video_id(filename: str) -> str:
    return hashlib.md5(filename.encode('utf-8')).hexdigest()
```

#### 视频ID生成特点

- **简单高效**：直接使用文件名生成MD5，无需读取文件内容
- **稳定可靠**：相同文件名总是生成相同的ID
- **性能优秀**：计算速度快，资源消耗低
- **易于理解**：逻辑简单，便于维护和调试
- **防文件名变更**：即使文件名变更，只要重新生成相同文件名，ID保持一致

#### 数据结构

**后端视频数据结构：**
```python
video_info = {
    'filename': filename,      # 视频文件名
    'video_id': video_id,     # 后端生成的MD5标识
    'file_path': file_path,   # 文件路径
    'file_size': file_size,   # 文件大小
    'duration': duration,     # 视频时长
    'resolution': resolution, # 分辨率
    'created_at': timestamp,  # 创建时间
    'last_accessed': timestamp # 最后访问时间
}
```

**前端视频数据结构：**
```javascript
videoData[videoId] = {
    id: videoId,           // 后端提供的MD5标识
    filename: filename,    // 视频文件名
    name: videoName,       // 显示名称
    path: videoPath,       // 视频路径
    index: index,          // 页面索引
    page: currentPage,     // 页码
    assignedTime: timestamp,
    lastPlayTime: timestamp,
    playCount: 0
}
```

**数据库视频文件表结构：**
```sql
CREATE TABLE video_files (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    filename TEXT UNIQUE NOT NULL,      -- 文件名
    video_id TEXT UNIQUE,               -- MD5格式的视频唯一标识
    file_path TEXT NOT NULL,
    file_size INTEGER,
    duration REAL,
    resolution TEXT,
    created_at TEXT NOT NULL,
    last_accessed TEXT,
    is_active BOOLEAN DEFAULT 1
)
```

**算法配置表结构（支持视频ID存储）：**
```sql
CREATE TABLE algorithm_configs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    algorithm_id TEXT UNIQUE NOT NULL,        -- 算法唯一标识
    algorithm_name TEXT,                      -- 算法名称
    algorithm_description TEXT,               -- 算法描述
    api_key TEXT,                            -- 算法API密钥
    selected_video_ids TEXT NOT NULL,         -- JSON格式存储视频ID列表（统一字段名）
    created_at TEXT NOT NULL,                 -- 创建时间
    updated_at TEXT NOT NULL,                 -- 更新时间
    is_active BOOLEAN DEFAULT 1,              -- 是否激活
    metadata TEXT                            -- 额外的元数据，JSON格式，包含存储类型信息
)
```

#### API接口

**1. 根据文件名获取视频信息**
```
GET /api/video/{filename}/info
```

**2. 根据视频ID获取视频信息**
```
GET /api/video/id/{video_id}/info
```

**3. 获取视频列表（包含视频ID）**
```
GET /api/videos?page=1&per_page=9
```

**4. 保存算法配置（使用视频ID）**
```
POST /api/algorithms/config
Content-Type: application/json

{
    "algorithm_id": "app-xxx",
    "selected_video_ids": ["video_id_1", "video_id_2"],  // 统一使用 selected_video_ids 字段
    "algorithm_name": "算法名称",
    "algorithm_description": "算法描述",
    "api_key": "api_key"
}
```

**5. 获取算法配置（返回视频ID）**
```
GET /api/algorithms/config/{algorithm_id}
```

#### 优势

1. **架构简洁**：后端统一管理，前端只负责展示
2. **数据一致性**：避免前后端数据不一致的问题
3. **维护简单**：前端不需要实现复杂的MD5生成逻辑
4. **性能优化**：减少前端计算负担，提高页面加载速度
5. **可追溯性**：通过视频ID可以快速定位视频文件
6. **扩展性好**：后端可以轻松添加更多视频管理功能
7. **防文件名变更**：使用视频ID存储，避免文件名变更导致的配置失效

#### 使用示例

**前端获取视频ID：**
```javascript
// 从后端获取视频ID
const videoId = await getVideoIdFromBackend(filename);

// 根据文件名查找本地缓存的视频ID
const existingVideoId = findVideoIdByFilename(filename);

// 保存算法配置时使用视频ID（统一字段名）
const saveData = {
    algorithm_id: selectedAlgorithm.id,
    selected_video_ids: Array.from(selectedVideos),  // 统一使用 selected_video_ids
    algorithm_name: selectedAlgorithm.name,
    algorithm_description: selectedAlgorithm.description,
    api_key: selectedAlgorithm.api_key
};
```

**后端查询视频信息：**
```python
# 根据视频ID获取信息
video_info = algorithm_db.get_video_by_id(video_id)

# 根据文件名获取信息
video_info = algorithm_db.get_video_by_filename(filename)

# 扫描视频文件并自动生成MD5标识
video_files = scan_video_files()  # 自动调用_update_video_file_record

# 验证视频ID存在性
valid_video_ids, invalid_video_ids = algorithm_db.validate_video_ids(video_ids)
```

## 主要功能

### 1. 视频播放管理
- 九宫格视频播放界面
- 分页显示支持
- 视频播放状态记录
- 播放统计信息

### 2. 算法配置管理
- 支持多种算法配置
- 视频选择功能
- 配置历史记录
- API密钥管理

### 3. 数据库存储
- SQLite数据库存储
- 视频文件信息管理
- 算法配置持久化
- 数据完整性验证

### 4. API接口
- RESTful API设计
- 视频信息查询
- 算法配置管理
- 系统状态监控

### 5. 工具库
- **哈希工具** (`utils/hash_utils.py`)：提供MD5、SHA等哈希算法工具
- **视频处理工具** (`utils/video_utils.py`)：视频缩略图生成、信息提取等
- **文件上传工具** (`utils/minio_upload.py`)：文件上传到MinIO存储服务

## 技术栈

- **后端**：Flask, Python, SQLite
- **前端**：JavaScript, Video.js, HTML5, CSS3
- **数据库**：SQLite
- **视频处理**：OpenCV
- **文件存储**：本地文件系统
- **工具库**：哈希工具、视频处理工具、文件上传工具

## 安装和运行

### 环境要求
- Python 3.7+
- 现代浏览器支持

### 安装步骤

1. 克隆项目
```bash
git clone <repository-url>
cd hyhPocProject
```

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

3. 运行应用

#### 方式1: 直接运行（开发环境）
```bash
python app.py
```

#### 方式2: 使用服务脚本（生产环境）
```bash
# 给脚本添加执行权限
chmod +x scripts/*.sh

# 启动服务
./scripts/start_service.sh

# 查看服务状态
./scripts/status_service.sh

# 停止服务
./scripts/stop_service.sh
```

4. 访问系统
```
http://localhost:15015
```

## 配置说明

### 视频目录配置
```python
app.config['UPLOAD_FOLDER'] = 'test_video'  # 视频文件存储目录
```

### 分页配置
```python
VIDEOS_PER_PAGE = 9  # 每页显示视频数量
```

### 数据库配置
```python
db_path = "data/algorithm_configs.db"  # 数据库文件路径
```

## 服务管理脚本

### 启动脚本 (`scripts/start_service.sh`)

最简单的服务启动方式，自动处理环境检查和后台运行。

#### 功能特点
- ✅ 自动检查Python环境和虚拟环境
- ✅ 防止重复启动
- ✅ 后台运行，不占用终端
- ✅ 自动生成PID文件和日志文件
- ✅ 启动状态验证

#### 使用方法
```bash
# 添加执行权限
chmod +x scripts/start_service.sh

# 启动服务
./scripts/start_service.sh
```

#### 启动成功后会显示
```
✅ 服务启动成功!
进程ID: 12345
日志文件: /path/to/project/app.log

=== 访问地址 ===
本地访问: http://localhost:15015
局域网访问: http://192.168.1.100:15015

=== 常用命令 ===
查看日志: tail -f app.log
查看状态: ./status_service.sh
停止服务: ./stop_service.sh
配置防火墙: ./setup_firewall.sh
```

### 停止脚本 (`scripts/stop_service.sh`)

安全地停止服务，不会影响其他进程。

#### 功能特点
- ✅ 优雅停止（先尝试SIGTERM）
- ✅ 强制停止（如果优雅停止失败）
- ✅ 自动清理PID文件
- ✅ 状态验证

#### 使用方法
```bash
# 添加执行权限
chmod +x scripts/stop_service.sh

# 停止服务
./scripts/stop_service.sh
```

### 状态检查脚本 (`scripts/status_service.sh`)

查看服务运行状态和详细信息。

#### 功能特点
- ✅ 进程状态检查
- ✅ 端口监听检查
- ✅ 日志文件信息
- ✅ 最新日志显示

#### 使用方法
```bash
# 添加执行权限
chmod +x scripts/status_service.sh

# 查看服务状态
./scripts/status_service.sh
```

#### 状态信息包括
- 进程ID和运行时间
- CPU和内存使用情况
- 端口15015监听状态
- 日志文件大小和修改时间
- 最新5行日志内容

### 脚本文件说明

- `app.pid`: 存储服务进程ID的文件
- `app.log`: 服务运行日志文件
- 所有文件都存储在项目根目录下

## 局域网访问配置

### 支持局域网访问
项目默认配置支持局域网访问，服务启动后可以通过以下方式访问：

#### 1. 获取服务器IP地址
```bash
# 查看本机IP地址
ip addr show

# 或者使用ifconfig
ifconfig
```

#### 2. 局域网访问地址
```
http://服务器IP:15015
```

例如：
- 服务器IP: `192.168.1.100`
- 访问地址: `http://192.168.1.100:15015`

#### 3. 防火墙配置
如果无法访问，可能需要配置防火墙：

```bash
# 给防火墙配置脚本添加执行权限
chmod +x scripts/setup_firewall.sh

# 运行防火墙配置脚本
./scripts/setup_firewall.sh
```

#### 4. 手动防火墙配置

**Ubuntu/Debian (UFW):**
```bash
sudo ufw allow 15015/tcp
```

**CentOS/RHEL (firewalld):**
```bash
sudo firewall-cmd --permanent --add-port=15015/tcp
sudo firewall-cmd --reload
```

#### 5. 测试局域网访问
```bash
# 在局域网其他设备上测试
curl -I http://服务器IP:15015

# 或者使用浏览器访问
http://服务器IP:15015
```

## 工具库使用说明

### 数据库清空工具 (`utils/clear_database.py`)

提供清空算法配置数据库的工具。

#### 主要功能

1. **查看数据库信息**
```bash
# 查看数据库当前状态
python utils/clear_database.py --action info
```

2. **清空所有数据**
```bash
# 清空所有数据（会提示确认）
python utils/clear_database.py --action clear-all

# 跳过确认提示
python utils/clear_database.py --action clear-all --confirm

# 不创建备份
python utils/clear_database.py --action clear-all --no-backup
```

3. **只清空算法配置**
```bash
# 只清空算法配置表
python utils/clear_database.py --action clear-configs
```

4. **只清空视频文件记录**
```bash
# 只清空视频文件表
python utils/clear_database.py --action clear-videos
```

#### 清空特点

- **自动备份**：清空前自动创建数据库备份
- **安全确认**：提供确认提示，防止误操作
- **选择性清空**：支持清空全部或部分数据
- **详细统计**：提供清空结果统计信息

### 哈希工具 (`utils/hash_utils.py`)

提供各种哈希算法工具函数，包括MD5、SHA等。

#### 主要功能

1. **视频ID生成**
```python
from utils.hash_utils import generate_video_id

# 生成视频唯一标识
video_id = generate_video_id("video.mp4")
```

2. **文件哈希计算**
```python
from utils.hash_utils import generate_file_md5, generate_file_sha256

# 计算文件MD5
md5_hash = generate_file_md5("path/to/file.mp4")

# 计算文件SHA256
sha256_hash = generate_file_sha256("path/to/file.mp4")
```

3. **字符串哈希计算**
```python
from utils.hash_utils import generate_string_md5, generate_sha256

# 计算字符串MD5
md5_hash = generate_string_md5("hello world")

# 计算字符串SHA256
sha256_hash = generate_sha256("hello world")
```

4. **文件完整性验证**
```python
from utils.hash_utils import verify_file_integrity

# 验证文件完整性
is_valid = verify_file_integrity("path/to/file.mp4", "expected_md5_hash")
```

5. **唯一标识符生成**
```python
from utils.hash_utils import generate_unique_id

# 生成唯一标识符
unique_id = generate_unique_id(prefix="video_", suffix="_hash")
```

#### 支持的哈希算法
- MD5
- SHA1
- SHA256
- SHA512

### 视频处理工具 (`utils/video_utils.py`)

提供视频处理相关功能。

#### 主要功能

1. **视频缩略图生成**
```python
from utils.video_utils import generate_video_thumbnail

# 生成视频缩略图
thumbnail = generate_video_thumbnail("path/to/video.mp4", "output.jpg")
```

2. **默认缩略图创建**
```python
from utils.video_utils import create_default_thumbnail

# 创建默认缩略图
thumbnail = create_default_thumbnail("视频标题")
```

### 算法密钥配置 (`api/algorithm_keys.py`)

提供算法密钥配置管理和inputs格式构建功能。

#### 主要功能

1. **算法配置管理**
```python
from api.algorithm_keys import algorithm_keys_config

# 获取所有有效密钥
keys = algorithm_keys_config.get_valid_keys()

# 获取指定密钥的算法配置
config = algorithm_keys_config.get_algorithm_config("app-6N9CZdGyZLgDIveyaxhBWtZP")

# 根据密钥获取inputs格式
inputs = algorithm_keys_config.get_algorithm_inputs_format("app-6N9CZdGyZLgDIveyaxhBWtZP", "http://example.com/image.jpg")
```

2. **算法配置结构**
```python
ALGORITHM_CONFIGS = {
    "app-6N9CZdGyZLgDIveyaxhBWtZP": {
        "name": "周界入侵检测算法",
        "description": "基于AI的周界入侵检测算法",
        "alarmDes": "检测到有人员进入防护区域",  # 告警描述
        "inputs_format": {
            "source": None,  # 运行时替换为实际文件URL
            "region_coordinate": None
        }
    },
    "app-Ua1HFb6owdFdz0iohOUK9tBf": {
        "name": "未设置安全网检测算法", 
        "description": "检测安全网未设置的情况",
        "alarmDes": "检测到安全网未设置",  # 告警描述
        "inputs_format": {
            "source": None  # 运行时替换为实际文件URL
        }
    }
}
```

3. **动态inputs构建**
- 根据配置的密钥自动构建对应的inputs格式
- 支持不同算法使用不同的参数结构
- 自动处理未知密钥的默认格式

4. **告警描述功能**
- 每个算法配置包含`alarmDes`字段，用于定义告警时的固定描述文案
- 告警信息自动包含算法配置中的告警描述
- 支持自定义告警描述，提高用户体验

### 文件上传工具 (`utils/minio_upload.py`)

提供文件上传到MinIO存储服务的功能。

## API文档

### 视频相关API

#### 获取视频列表
```
GET /api/videos?page=1&per_page=9
```

#### 获取视频信息
```
GET /api/video/{filename}/info
GET /api/video/id/{video_id}/info
```

#### 获取视频统计
```
GET /api/video-stats
```

### 算法配置API

#### 获取算法列表
```
GET /api/algorithms
```

#### 保存算法配置
```
POST /api/algorithms/config
```

#### 获取算法配置
```
GET /api/algorithms/config/{algorithm_id}
```

## 数据迁移

如果从旧版本升级，系统会自动处理数据迁移：

1. 数据库表结构自动升级
2. 现有视频文件自动生成MD5标识
3. 前端数据自动适配新格式



## 注意事项

1. **文件命名**：确保视频文件名唯一，避免冲突
2. **数据备份**：定期备份数据库文件
3. **性能优化**：大量视频文件时注意性能影响
4. **安全考虑**：生产环境请配置适当的安全措施

## 更新日志

### v2.8.0 (最新)
- **新增告警描述功能**：在告警信息中添加算法配置中的alarmDes字段作为固定描述文案
- **优化告警信息显示**：告警信息现在包含算法名称、视频名称、告警描述和时间戳
- **增强用户体验**：告警描述使用红色文字显示，突出显示异常行为的具体描述
- **完善算法配置**：为所有算法配置添加了相应的告警描述字段

### v2.7.0
- **重构算法配置系统**：使用配置的密钥来判断算法类型，而不是通过算法ID中的字符串
- **集中化算法配置**：将算法配置和inputs格式定义集中在`api/algorithm_keys.py`中
- **动态inputs构建**：根据算法密钥自动构建对应的inputs格式，支持不同算法使用不同的参数结构
- **增强可维护性**：简化算法配置管理，提高代码的可维护性和扩展性

### v2.6.0
- **完全统一字段命名**：数据库、API、前端代码全部使用 `selected_video_ids` 字段名
- **数据库迁移**：将数据库字段从 `selected_videos` 迁移为 `selected_video_ids`
- **简化代码逻辑**：移除字段名兼容处理代码，提高代码可维护性
- **优化数据一致性**：确保数据库、API、前端使用完全一致的字段名

### v2.5.0
- **修复算法配置弹窗视频选择问题**：解决右侧视频列表没有正确选中已配置视频的问题
- **统一字段命名**：确保前端和后端API使用一致的字段名（selected_video_ids）
- **增强兼容性**：支持新旧字段名的兼容处理
- **优化调试体验**：添加详细的错误处理和日志记录
- **修复数据库清空工具错误**：解决清空数据库时出现的TypeError错误

### v2.4.0
- **移除向后兼容**：完全使用视频ID存储，移除文件名存储支持
- **新增数据库清空工具**：提供安全的数据库清空功能
- **优化视频检测流程**：使用视频ID进行视频检测，避免文件名变更问题
- **简化API接口**：移除复杂的向后兼容逻辑，提高代码可维护性

### v2.3.0
- **简化视频ID生成策略**：移除复杂的基于文件内容的ID生成方案
- **统一使用基于文件名的MD5生成**：简化逻辑，提高性能
- **优化系统架构**：减少代码复杂度，提高可维护性

### v2.2.0
- **修复告警信息显示问题**：解决告警画面与视频名称不匹配的问题
- 优化告警信息展示：简化告警信息结构
- 移除调试功能：清理调试相关代码，保持系统简洁

### v2.1.0
- 重构MD5生成功能，抽取到独立的哈希工具文件
- 新增多种哈希算法支持（MD5、SHA1、SHA256、SHA512）
- 新增文件完整性验证功能
- 新增唯一标识符生成功能
- 优化代码结构，提高可维护性

### v2.0.0
- 新增MD5格式视频唯一标识系统
- 统一前后端数据标识
- 优化数据库结构
- 增强API接口功能

### v1.0.0
- 基础视频播放功能
- 算法配置管理
- 数据库存储支持