wvp-platform/CLAUDE.md

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

常用命令

本地开发

# 编译后端（需要 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 部署（生产环境）

# 构建后端镜像
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

基础服务（本地开发）

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 模式）：

docker ps | grep mysql
docker logs docker-polaris-mysql-1

Redis 连接失败

检查 Redis（Docker 模式）：

docker exec -it docker-polaris-redis-1 redis-cli ping

ZLMediaKit 流媒体服务异常

检查 ZLM 容器：

docker logs vsp-zlmedia

Git 提交规范

在修改代码后，使用中文提交信息：

git add .
git commit -m "功能：添加XXX功能

详细说明...

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

不要立即 push，等待用户指示再推送到远程。