From 827daebcf49d28e73b41c58f190c7068caae3762 Mon Sep 17 00:00:00 2001 From: 16337 <1633794139@qq.com> Date: Thu, 5 Mar 2026 16:27:38 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E5=88=9B=E5=BB=BA?= =?UTF-8?q?=20CLAUDE.md=20=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增内容： - 项目概述和生产部署信息 - 本地开发和 Docker 部署命令 - 架构概览（核心模块、配置文件） - AIoT 关键接口说明（配置管理、ROI、截图、视频播放） - 数据库表结构说明 - 开发工作流指引 - 常见问题排查 - Git 提交规范 Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 225 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..b8d7b7a6b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,225 @@ +# 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 " +``` + +**不要立即 push**，等待用户指示再推送到远程。