16337
827daebcf4
新增内容： - 项目概述和生产部署信息 - 本地开发和 Docker 部署命令 - 架构概览（核心模块、配置文件） - AIoT 关键接口说明（配置管理、ROI、截图、视频播放） - 数据库表结构说明 - 开发工作流指引 - 常见问题排查 - Git 提交规范 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
226 lines
6.0 KiB
Markdown
226 lines
6.0 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
WVP-PRO 是一个基于 GB28181-2016 标准的开箱即用网络视频平台。负责实现核心信令与设备管理后台，支持 NAT 穿透，支持海康、大华、宇视等品牌的 IPC、NVR 接入。集成 ZLMediaKit 流媒体服务器。
|
||
|
||
**生产部署信息：**
|
||
- **容器名称：** `vsp-wvp`（后端）、`vsp-frontend`（前端）、`vsp-zlmedia`（流媒体）
|
||
- **端口映射：**
|
||
- 后端：18080:18080
|
||
- SIP: 8116:8116 (TCP/UDP)
|
||
- 前端：8088:80
|
||
- **部署位置：** 腾讯云服务器 `/opt/vsp-platform`
|
||
- **存储：** 腾讯云 MySQL + 腾讯云 Redis
|
||
- **访问地址：**
|
||
- WVP 后端：http://服务器IP:18080
|
||
- WVP 前端：http://服务器IP:8088
|
||
- API 文档：http://服务器IP:18080/doc.html
|
||
|
||
## 常用命令
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 编译后端（需要 Maven 3.3+ 和 Java 17）
|
||
mvn clean package -DskipTests
|
||
|
||
# 或使用 Windows 批处理脚本
|
||
编译.bat
|
||
|
||
# 运行后端
|
||
mvn spring-boot:run
|
||
启动.bat
|
||
|
||
# 编译前端（Vue 2）
|
||
cd web
|
||
npm install
|
||
npm run dev # 开发服务器
|
||
npm run build:prod # 生产构建
|
||
```
|
||
|
||
### Docker 部署（生产环境）
|
||
|
||
```bash
|
||
# 构建后端镜像
|
||
docker build -t vsp-wvp:latest .
|
||
|
||
# 运行后端容器
|
||
docker run -d \
|
||
--name vsp-wvp \
|
||
-p 18080:18080 \
|
||
-p 8116:8116 \
|
||
-p 8116:8116/udp \
|
||
-e SPRING_PROFILES_ACTIVE=prod \
|
||
-e MYSQL_HOST=腾讯云MySQL地址 \
|
||
-e REDIS_HOST=腾讯云Redis地址 \
|
||
vsp-wvp:latest
|
||
|
||
# 构建前端镜像
|
||
cd web
|
||
docker build -t vsp-frontend:latest .
|
||
|
||
# 运行前端容器
|
||
docker run -d \
|
||
--name vsp-frontend \
|
||
-p 8088:80 \
|
||
vsp-frontend:latest
|
||
|
||
# 查看日志
|
||
docker logs -f vsp-wvp
|
||
docker logs -f vsp-frontend
|
||
|
||
# 重启容器
|
||
docker restart vsp-wvp
|
||
docker restart vsp-frontend
|
||
|
||
# 进入容器调试
|
||
docker exec -it vsp-wvp /bin/bash
|
||
```
|
||
|
||
### 基础服务（本地开发）
|
||
|
||
```bash
|
||
cd docker
|
||
docker compose up -d polaris-redis polaris-mysql polaris-media
|
||
docker compose down
|
||
docker compose logs -f polaris-media
|
||
```
|
||
|
||
## 架构概览
|
||
|
||
### 核心模块（src/main/java/com/genersoft/iot/vmp/）
|
||
|
||
- **gb28181/** — GB28181 协议实现
|
||
- `transmit/` — SIP 信令传输层
|
||
- `service/` — 设备管理、播放服务、PTZ 控制
|
||
- `bean/` — GB28181 实体类
|
||
|
||
- **jt1078/** — JT1078 协议支持（部标808/1078）
|
||
|
||
- **media/** — ZLMediaKit 集成
|
||
- 流媒体代理、录像管理
|
||
- RTSP/RTMP/HLS/FLV 输出
|
||
|
||
- **aiot/** — AIoT 功能模块
|
||
- `controller/` — AI 配置、ROI 管理、告警接口
|
||
- `service/` — 配置推送、截图服务
|
||
- `dao/` — ai_camera、ai_roi、ai_roi_algo_bind 数据访问
|
||
|
||
- **vmanager/** — REST API 控制器
|
||
- 设备管理、通道查询、云台控制等
|
||
|
||
- **web/** — Vue 2 前端（独立目录）
|
||
|
||
### 配置文件
|
||
|
||
- `src/main/resources/application.yml` — 主配置
|
||
- `src/main/resources/application-dev.yml` — 开发环境配置
|
||
- server.port: 18080
|
||
- MySQL: localhost:3306
|
||
- Redis: localhost:6379
|
||
- ZLM: localhost:6080
|
||
|
||
### AIoT 关键接口
|
||
|
||
**配置管理：**
|
||
- `POST /api/ai/config/push` — 推送配置到边缘端（Redis Stream）
|
||
- `GET /api/ai/config/export` — 导出摄像头完整配置
|
||
- `POST /api/ai/config/push-all` — 一次性推送全部配置（本地调试）
|
||
|
||
**ROI 管理：**
|
||
- `POST /api/ai/roi/create` — 创建 ROI 区域
|
||
- `PUT /api/ai/roi/update` — 更新 ROI 区域
|
||
- `DELETE /api/ai/roi/delete` — 删除 ROI 区域
|
||
- `GET /api/ai/roi/list` — 查询 ROI 列表
|
||
|
||
**截图服务：**
|
||
- `POST /api/ai/roi/snap` — 请求边缘端截图（Redis Stream）
|
||
- `POST /api/ai/roi/snap/callback` — 边缘端截图回调
|
||
|
||
**摄像头管理：**
|
||
- `GET /api/ai/camera/list` — 获取摄像头列表
|
||
- `POST /api/ai/camera/sync` — 同步摄像头配置
|
||
|
||
**视频播放：**
|
||
- `GET /api/play/{deviceId}/{channelId}` — 播放视频流
|
||
- `GET /api/play/{deviceId}/{channelId}/stop` — 停止播放
|
||
|
||
### 数据库表（MySQL）
|
||
|
||
**AIoT 核心表：**
|
||
- `ai_camera` — 摄像头配置（camera_id, camera_name, rtsp_url）
|
||
- `ai_roi` — ROI 区域配置（roi_id, camera_id, polygon, roi_name）
|
||
- `ai_roi_algo_bind` — 算法绑定（bind_id, roi_id, algorithm_code, threshold）
|
||
- `ai_edge_device` — 边缘设备管理
|
||
- `ai_config_snapshot` — 配置版本快照
|
||
|
||
**GB28181 核心表：**
|
||
- `device` — 国标设备表
|
||
- `device_channel` — 设备通道表
|
||
- `stream_proxy` — 流代理配置
|
||
|
||
## 开发工作流
|
||
|
||
### 修改后端代码
|
||
1. 修改 Java 代码
|
||
2. `mvn clean package -DskipTests`
|
||
3. `启动.bat` 或 `mvn spring-boot:run`
|
||
4. 访问 http://localhost:18080/doc.html 测试
|
||
|
||
### 修改前端代码
|
||
1. 修改 Vue 代码（web/src/）
|
||
2. `cd web && npm run build:prod`
|
||
3. 重新构建 Docker 镜像或直接运行 `npm run dev`
|
||
|
||
### 修改 AIoT 配置推送逻辑
|
||
- 配置推送服务：`aiot/service/impl/AiConfigServiceImpl.java`
|
||
- Redis Stream 写入：使用 RedisTemplate 的 `opsForStream().add()`
|
||
- 配置格式：JSON 包含 cameras、rois、bindings 数组
|
||
|
||
### GB28181 设备处理
|
||
- 设备注册处理：`gb28181/transmit/event/request/impl/RegisterRequestProcessor.java`
|
||
- 心跳处理：`gb28181/transmit/event/request/impl/MessageRequestProcessor.java`
|
||
- SIP 命令发送：`gb28181/transmit/cmd/impl/SIPCommander.java`
|
||
|
||
## 常见问题
|
||
|
||
### 启动失败：端口被占用
|
||
检查 18080 端口：`netstat -ano | findstr 18080`
|
||
|
||
### 数据库连接失败
|
||
检查 MySQL 状态（Docker 模式）：
|
||
```bash
|
||
docker ps | grep mysql
|
||
docker logs docker-polaris-mysql-1
|
||
```
|
||
|
||
### Redis 连接失败
|
||
检查 Redis（Docker 模式）：
|
||
```bash
|
||
docker exec -it docker-polaris-redis-1 redis-cli ping
|
||
```
|
||
|
||
### ZLMediaKit 流媒体服务异常
|
||
检查 ZLM 容器：
|
||
```bash
|
||
docker logs vsp-zlmedia
|
||
```
|
||
|
||
## Git 提交规范
|
||
|
||
在修改代码后，使用中文提交信息：
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "功能：添加XXX功能
|
||
|
||
详细说明...
|
||
|
||
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
|
||
```
|
||
|
||
**不要立即 push**，等待用户指示再推送到远程。
|