# AI监控系统帮助文档

## 📖 项目简介

AI监控系统是一个基于Python的实时视频监控解决方案，支持RTSP视频流接入、AI智能检测、实时告警和Web界面展示。系统集成YOLOv8目标检测模型，支持昇腾NPU加速，可广泛应用于安防监控、生产安全等场景。

## 🚀 快速开始

### 环境要求

- **Python**: 3.7+
- **操作系统**: Linux/macOS/Windows
- **硬件**: 支持昇腾NPU（可选，也支持CPU推理）
- **内存**: 建议4GB+
- **存储**: 根据视频录制需求配置

### 安装依赖

```bash
# 克隆项目（如果从git仓库）
git clone <repository_url>
cd AIMonitor

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

### 依赖包说明

```
opencv-python>=4.9.0      # 计算机视觉库
PyYAML>=6.0              # YAML配置文件解析
websockets>=12.0         # WebSocket服务器
Flask>=3.0.0            # Web框架
onnxruntime             # ONNX模型推理（支持昇腾NPU）
```

### 启动系统

#### 方式一：使用启动脚本（推荐）

```bash
# 简单启动（推荐新手使用）
python3 simple_start.py

# 完整启动器（功能更多）
python3 start.py

# Shell脚本启动
./run.sh
```

#### 方式二：手动启动

```bash
# 终端1：启动RTSP视频流处理服务
python3 rtsp_service_ws.py

# 终端2：启动静态文件服务
python3 static_server.py
```

### 验证启动

启动成功后，可以看到以下输出：

```
=== 系统启动完成 ===
RTSP WebSocket服务: ws://localhost:8765
静态文件服务: http://localhost:5000
```

使用以下命令验证端口监听：

```bash
netstat -an | grep -E "(8765|5000)"
```

## ⚙️ 配置说明

### 摄像头配置 (`config.yaml`)

```yaml
cameras:
  - id: 1
    name: "入口监控"
    rtsp_url: "rtsp://username:password@ip:port/stream"
  - id: 2
    name: "车间监控"
    rtsp_url: "rtsp://8.130.165.33:8554/test"
```

**参数说明：**
- `id`: 摄像头唯一标识符
- `name`: 摄像头显示名称
- `rtsp_url`: RTSP视频流地址

### 系统参数配置 (`rtsp_service_ws.py`)

```python
RTSP_TARGET_FPS = 10.0           # 视频处理帧率
FRAMES_PER_SEGMENT = 600         # 每个视频片段帧数（约1分钟）
VIDEO_OUTPUT_DIR = "./videos"    # 视频输出目录
WS_HOST = "0.0.0.0"              # WebSocket监听地址
WS_PORT = 8765                   # WebSocket端口
```

## 🔧 核心功能

### 1. RTSP视频流处理

- 支持多路RTSP视频流同时接入
- 自动重连机制
- 视频分段录制（每600帧一个文件）
- 智能抽帧处理，保证系统性能

### 2. AI智能检测

基于YOLOv8模型的目标检测：
- **模型位置**: `YOLO_Weight/` 目录
- **支持类别**: supervisor（监督员）、suspect（嫌疑人员）
- **推理加速**: 支持昇腾NPU和CPU推理
- **自定义扩展**: 可修改`user_process_frame`函数添加自定义算法

### 3. 实时告警系统

- 基于WebSocket的实时告警推送
- 支持不同级别的告警分类
- 自动关联视频录像
- 告警信息包含时间戳、摄像头ID、事件类型

### 4. Web访问接口

#### WebSocket接口 (`ws://localhost:8765`)

**消息类型：**

1. **实时帧数据**
```json
{
  "msg_type": "frame",
  "camera_id": 1,
  "timestamp": 1672531200.123,
  "result_type": 0,
  "image_base64": "base64编码的图像数据"
}
```

2. **告警消息**
```json
{
  "msg_type": "alert",
  "camera_id": 1,
  "event_type": 1,
  "video_file": "./videos/20231201_120000_cam1.mp4",
  "timestamp": 1672531200.123
}
```

#### HTTP文件服务 (`http://localhost:5000`)

**访问格式：**
```
http://localhost:5000/{camera_id}/{video_filename}
```

**示例：**
```
http://localhost:5000/1/20231201_120000_cam1.mp4
```

## 📁 项目结构

```
AIMonitor/
├── config.yaml              # 摄像头配置文件
├── requirements.txt          # Python依赖列表
├── rtsp_service_ws.py       # 主服务程序
├── static_server.py          # 静态文件服务
├── npu_yolo_onnx.py         # YOLO模型推理
├── start.py                  # 完整启动器
├── simple_start.py           # 简单启动脚本
├── run.sh                    # Shell启动脚本
├── videos/                   # 录制视频目录
├── YOLO_Weight/              # YOLO模型权重
├── ONNX_Weight/              # ONNX模型文件
├── YOLO_Pipe_results/        # YOLO处理结果
└── __pycache__/              # Python缓存
```

## 🔄 使用流程

### 1. 配置摄像头

编辑 `config.yaml` 文件，添加您的RTSP摄像头信息：

```yaml
cameras:
  - id: 1
    name: "前门"
    rtsp_url: "rtsp://admin:password@192.168.1.100:554/stream1"
```

### 2. 启动系统

```bash
python3 simple_start.py
```

### 3. 检查运行状态

查看日志输出确认服务正常启动：

```
[INFO] WebSocket server started at ws://0.0.0.0:8765
[INFO] Start capturing: id=1, name=前门
[INFO] FrameProcessorWorker started
 * Running on http://0.0.0.0:5000
```

### 4. 访问服务

- **WebSocket客户端**: 连接 `ws://localhost:8765` 接收实时数据
- **视频回放**: 访问 `http://localhost:5000/{camera_id}/{filename}` 查看录制视频

## 🎯 自定义开发

### 添加自定义AI算法

修改 `rtsp_service_ws.py` 中的 `user_process_frame` 函数：

```python
def user_process_frame(image, camera_id: int, timestamp: float) -> Dict[str, Any]:
    """
    自定义AI处理函数
    
    Args:
        image: numpy.ndarray (BGR格式)
        camera_id: 摄像头ID
        timestamp: 时间戳
    
    Returns:
        {
            "image": processed_image,  # 处理后的图像
            "type": result_type       # 结果类型（0=正常，>0=告警）
        }
    """
    # 在这里实现您的自定义算法
    result_type = 0
    
    # 示例：调用YOLO检测
    yolo = YOLOv8_ONNX("YOLO_Weight/yolov8n.onnx")
    detections = yolo(image)
    
    # 根据检测结果设置告警类型
    if len(detections) > 0:
        result_type = 1  # 检测到目标
    
    return {
        "image": image,
        "type": result_type,
    }
```

### 扩展告警逻辑

在检测结果处理部分添加自定义告警逻辑：

```python
# 在FrameProcessorWorker.run()方法中
if result_type != 0:
    # 自定义告警处理
    alert_msg = {
        "msg_type": "alert",
        "camera_id": camera_id,
        "event_type": result_type,
        "video_file": video_filepath,
        "timestamp": ts,
        "custom_data": "您可以添加的自定义数据"
    }
    self.ws_send_queue.put(alert_msg)
```

## 🐛 故障排除

### 常见问题

#### 1. RTSP连接失败

**错误**: `Cannot open RTSP stream`

**解决方案**:
- 检查RTSP地址格式是否正确
- 验证摄像头用户名密码
- 确认网络连接正常
- 检查摄像头是否支持RTSP协议

#### 2. 端口被占用

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

**解决方案**:
```bash
# 查找占用端口的进程
lsof -i :8765
lsof -i :5000

# 终止进程
kill -9 <PID>
```

#### 3. 依赖安装失败

**解决方案**:
```bash
# 更新pip
pip install --upgrade pip

# 使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
```

#### 4. YOLO模型加载失败

**错误**: `Failed to load model`

**解决方案**:
- 检查模型文件路径是否正确
- 确认模型文件完整性
- 验证ONNX模型格式

### 性能优化

#### 1. 降低处理帧率

```python
RTSP_TARGET_FPS = 5.0  # 从10降到5fps
```

#### 2. 调整视频片段长度

```python
FRAMES_PER_SEGMENT = 300  # 从600降到300帧（30秒）
```

#### 3. 限制并发连接数

```python
# 在WebSocket处理中添加连接数限制
MAX_CLIENTS = 10
if len(ws_clients) >= MAX_CLIENTS:
    websocket.close()
```

## 📊 性能监控

### 系统资源监控

```bash
# 监控CPU和内存使用
top -p $(pgrep -f "rtsp_service_ws|static_server")

# 监控网络连接
netstat -an | grep -E "(8765|5000)"

# 监控磁盘空间
df -h ./videos
```

### 日志查看

系统日志实时输出包含：
- `[INFO]`: 正常运行信息
- `[WARN]`: 警告信息（如队列满、丢帧）
- `[ERROR]`: 错误信息（如连接失败）

## 🔒 安全建议

### 1. 网络安全
- 限制WebSocket访问IP范围
- 使用HTTPS/WSS加密传输
- 定期更新依赖包

### 2. 数据安全
- 定期备份重要配置
- 设置视频文件访问权限
- 合理配置视频保留期限

### 3. 系统安全
- 使用非root用户运行
- 配置防火墙规则
- 监控异常访问

## 📞 技术支持

### 日志收集
遇到问题时，请提供以下信息：
1. 系统环境信息（操作系统、Python版本）
2. 错误日志输出
3. 配置文件内容（请脱敏）
4. 系统资源使用情况

### 联系方式
如需技术支持，请通过以下方式联系：
- 提交Issue到项目仓库
- 发送邮件到技术支持邮箱
- 加入技术交流群

## 📄 许可证

本项目遵循MIT许可证，详见LICENSE文件。

---

**最后更新**: 2024-12-10
**版本**: v1.0.0