# visi-watch

**Repository Path**: pg_apps/visi-watch

## Basic Information

- **Project Name**: visi-watch
- **Description**: 远程对接海康摄像头，对接GB28181协议
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VisiWatch GB28181 视频监控平台

> 版本 **4.0.0** ｜ 后端 Java 17 + Spring Boot 3.5 ｜ 前端 Vue 3 + Vite 6 + Element Plus
>
> 通过 **WVP-PRO（SIP 信令） + ZLMediaKit（媒体分发）** 接入海康 NVR/IPC，提供实时预览、
> 录像回放、按起止时间导出 MP4、摄像头分组管理、云台/预置位/抓图、导出任务中心与系统诊断。

> [!IMPORTANT]
> **GB28181 必须有 SIP 信令服务。** 本仓库不自研 SIP 协议栈，而是集成开源的
> [WVP-PRO](https://github.com/648540858/wvp-GB28181-pro) 完成设备注册、目录、点播、回放与录像下载；
> [ZLMediaKit](https://github.com/ZLMediaKit/ZLMediaKit) 负责 RTP 收流和 FLV/HLS 分发。
> 本仓库只负责摄像头业务编排、浏览器页面与 FFmpeg 转封装。
>
> 本项目**不包含登录、RBAC、租户隔离与操作日志**，前端使用假登录；
> 预览要求摄像头/NVR 使用 **H.264 子码流**（浏览器对 H.265 的 FLV/HLS 支持很差）。
>
> **版权与授权**：本项目仅供**个人学习、研究**使用，**禁止任何形式的商业用途**。
> 如需商用，请先联系 **pg_tech@163.com** 获取书面授权。完整条款见 [LICENSE.md](./LICENSE.md)。

---

## 功能特性

| 模块 | 能力 |
|---|---|
| 实时预览 | 1/4/9 宫格、HTTP-FLV 优先、HLS 兜底、心跳保活、离开自动停止、全屏 |
| 云台控制 | 八方向、放大/缩小、速度调节、预置位查询/设置/调用/删除 |
| 抓图 | 通过 ZLM 直接截取 JPEG，保存到本地并记录历史 |
| 录像回放 | 按摄像头与时间范围查询设备录像段，暂停/恢复/倍速/偏移拖动 |
| 录像导出 | 调用 WVP 设备录像下载，ZLM 下载 MP4，FFmpeg 转封装为浏览器友好的 MP4；支持进度、取消、重试、删除 |
| 云端录像 | 查询 WVP 云端录像，按应用名/流ID/CallId/时间/节点筛选，支持播放、ZIP 下载、详情与删除 |
| 摄像头管理 | 分组树、分页查询、编辑、启用/停用、WVP 设备/通道同步导入、目录缺失标记 |
| 在线状态 | 定时按 WVP 设备级在线状态刷新，手动刷新按钮 |
| 系统诊断 | WVP / ZLM / MySQL / FFmpeg / 存储 / 磁盘状态，配置提示 |
| 仪表盘 | 摄像头在线率、分组数、预览会话、导出任务统计、最近任务 |
| 文档 | Swagger UI 接口文档、Windows/Linux/Docker 部署文档、海康 GB28181 配置指南 |

## 系统架构

```text
海康 NVR / IPC ──SIP REGISTER/INVITE/Catalog──▶ WVP-PRO ──REST──▶ visi-watch (本仓库)
       │                                          │
       └──────────── RTP(PS) ────────────────────▶ ZLMediaKit
                                                  │
浏览器 ◀── 同源 /zlm/ HTTP-FLV / HLS ── Nginx ────┘
浏览器 ◀── REST /api/na-upms/** ──▶ visi-watch ──▶ MySQL(visi_watch)
```

- **WVP-PRO**：SIP 注册、设备目录、点播/回放/录像下载、云台指令。
- **ZLMediaKit**：RTP 收流、PS 解复用、HTTP-FLV/HLS/WebSocket 分发、录像文件落盘。
- **visi-watch**：摄像头台账、预览/回放会话、导出任务、FFmpeg 转封装、浏览器接口。
- 浏览器不直接访问 WVP API；播放地址统一改写为同源 `/zlm/**`，由 Nginx 反代 ZLM。

## 技术栈

| 分类 | 组件 |
|---|---|
| 后端 | Java 17、Spring Boot 3.5.16、Undertow、Spring RestClient |
| 持久层 | MyBatis-Plus 3.5.9、MySQL 8.x、Druid |
| 接口文档 | SpringDoc OpenAPI 3 + Swagger UI |
| 视频接入 | WVP-PRO 2.7.x / 3.0.x（SIP 信令）、ZLMediaKit（媒体） |
| 视频处理 | FFmpeg / FFprobe |
| 前端 | Vue 3.5、Vite 6、TypeScript 5.7、Element Plus 2.9、Pinia |
| 播放器 | mpegts.js（HTTP-FLV/WS-FLV）、hls.js（HLS） |
| 公共返回结构 | 外部 `io.github.na-tool:na-common`（Result / 异常 / Jackson） |

## 目录结构

```text
visi-watch/
├── pom.xml                         # 父 POM，只聚合 na-upms
├── na-upms/
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/na/
│       │   ├── admin/              # Controller / Service / DTO / 配置 / WVP/ZLM 客户端
│       │   ├── core/mapper/        # 4 个业务 Mapper
│       │   └── entity/             # 4 张 dev_* 表实体
│       └── resources/application.yml
├── web/                            # Vue 3 前端（假登录 + 静态路由）
├── doc/
│   ├── visi_watch.sql              # 业务库初始化脚本
│   ├── usage-guide.md              # 海康接入与页面使用指南
│   └── deployment.md               # Windows / Linux / Docker 部署
├── deploy/                         # Dockerfile / Nginx / Compose
├── scripts/                        # Windows / Linux 启停脚本
└── README.md
```

## 快速开始

### 1. 环境要求

| 组件 | 版本 |
|---|---|
| JDK | 17+ |
| Maven | 3.9+ |
| MySQL | 8.x |
| Node.js | 20+（仅前端构建需要） |
| WVP-PRO | 2.7.x（JDK 8/11，联调基线）或 3.0.x（JDK 21，需冒烟验证） |
| ZLMediaKit | 与 WVP 配套版本 |
| FFmpeg | 4.x+（导出转封装需要） |

### 2. 初始化业务库

```bash
mysql -uroot -p < doc/visi_watch.sql
```

脚本会创建 `visi_watch` 库、4 张 `dev_*` 表与演示分组/摄像头。
**演示摄像头的 GB 编号不是真实设备**，请在平台中通过 WVP 同步真实通道。

WVP-PRO 使用它自己的数据库（官方镜像通常内置），不要与 `visi_watch` 混用。

### 3. 启动 WVP-PRO + ZLMediaKit

推荐先按 [WVP-PRO 官方文档](https://doc.wvp-pro.cn) 或
[Docker 镜像说明](https://hub.docker.com/r/648540858/wvp_pro) 启动。常用端口：

| 服务 | 端口 | 说明 |
|---|---|---|
| WVP Web/API | `18080` | 管理页面与 REST API |
| SIP | `5060/udp`、`5060/tcp` | 海康设备注册 |
| ZLM HTTP | `9092` 或 `80` | FLV/HLS 与后端 API |
| RTP | `30000-30500/udp+tcp` | 设备推流，按实际配置开放 |

详细步骤、海康侧参数和 Docker/原生部署见 [doc/deployment.md](./doc/deployment.md)。

### 4. 配置本服务

```bash
# 必改：数据库
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_DATABASE=visi_watch
export MYSQL_USERNAME=root
export MYSQL_PASSWORD=123456

# 必改：WVP / ZLM
export WVP_BASE_URL=http://127.0.0.1:18080
export WVP_AUTH_ENABLED=false
export WVP_USERNAME=admin
export WVP_PASSWORD=admin
export ZLM_API_BASE_URL=http://127.0.0.1:9092
export ZLM_SECRET=你的ZLM api.secret

# 可选：存储与浏览器播放地址
export VISI_STORAGE_LINUX_ROOT=/data/visi-watch
export VISI_STREAM_PUBLIC_BASE_URL=/zlm
export VISI_FFMPEG_PATH=ffmpeg
```

Windows 下对应 `VISI_STORAGE_WINDOWS_ROOT=D:/visi-watch-data`。
完整配置见 `na-upms/src/main/resources/application.yml`。

### 5. 启动后端

```bash
# Windows / Linux 通用
mvn clean package -DskipTests
java -jar na-upms/target/na-upms.jar
```

- 后端端口：`10061`
- 接口文档：`http://127.0.0.1:10061/swagger-ui.html`（兼容旧入口 `/doc.html`）
- 日志：`logs/visi-watch/application.log`

Windows 本机 Maven 路径示例：

```bat
C:\Users\w10\.aoci-install\tools\apache-maven-3.9.11\bin\mvn.cmd clean package -DskipTests
```

也可使用 `scripts/start.sh`、`scripts/start.bat`、`scripts/start.ps1`。

### 6. 启动前端（开发）

```bash
npm install
npm run dev
```

打开 `http://localhost:5173`，任意账号密码进入。

Vite 代理：

- `/api/na-upms/**` → `http://localhost:10061`
- `/na-upms/**` → `http://localhost:10061`（剥离 `/na-upms`）
- `/zlm/**` → `VITE_ZLM_TARGET`（默认 `http://localhost:9092`，含 WebSocket）

### 7. 生产构建

```bash
npm run build
# web/dist 由 Nginx 托管
```

生产 Nginx 示例见 `deploy/nginx-visi-watch.conf`，必须：

- 同源反代 `/api/na-upms/**`、`/na-upms/**`；
- 反代 `/zlm/**` 到 ZLM（含 WebSocket、关闭 buffering、长超时）；
- **拒绝** `/zlm/index/api/`，不要把 ZLM 管理 API 暴露给浏览器。

## 页面

| 路径 | 页面 | 说明 |
|---|---|---|
| `/login` | 登录 | 假登录，任意账号密码 |
| `/dashboard` | 运行概览 | 摄像头、在线率、导出任务、组件状态 |
| `/monitor` | 实时预览 | 1/4/9 宫格、云台、预置位、抓图 |
| `/playback` | 录像回放 | 录像段查询、暂停/倍速/拖动、带入导出 |
| `/camera` | 摄像头管理 | 分组、台账、WVP 同步导入、在线刷新 |
| `/export` | 录像导出 | 创建任务、进度、取消/重试/下载 |
| `/cloud-record` | 云端录像 | WVP 云端录像查询、播放、ZIP 下载、删除 |
| `/system` | 系统状态 | WVP/ZLM/FFmpeg/MySQL/存储诊断 |

## 主要接口

统一前缀 `/api/na-upms`，完整参数以 `/swagger-ui.html` 为准（兼容 `/doc.html`）。

| 功能 | 接口 |
|---|---|
| 摄像头分页 | `POST /cameras/list-paging` |
| 摄像头选项 | `GET /cameras/options` |
| WVP 设备/通道 | `GET /sync/wvp/devices`、`GET /sync/wvp/devices/{deviceId}/channels` |
| 导入通道 | `POST /sync/wvp/import` |
| 实时预览 | `POST /live/start`、`POST /live/heartbeat`、`POST /live/stop` |
| 回放 | `POST /playback/start`、`POST /playback/records`、`POST /playback/pause|resume|seek|speed` |
| 云台/预置位 | `POST /ptz/control`、`GET /ptz/presets`、`POST /ptz/presets/add|call|delete` |
| 抓图 | `POST /snapshots/capture`、`POST /snapshots/list-paging` |
| 导出任务 | `POST /export/tasks`、`POST /export/tasks/list-paging`、`POST /export/tasks/{id}/cancel|retry` |
| 云端录像 | `GET /cloud/record/list`、`GET /cloud/record/play`、`POST /cloud/record/delete`、`GET /cloud/record/download/zip` |
| 系统/仪表盘 | `GET /system/status`、`GET /dashboard/summary` |

## 录像导出流程

```text
创建任务(PENDING)
  -> 调度器原子置为 QUEUED
  -> 优先查询 WVP 云端录像（与请求时间段相交且完整覆盖）
       -> 从 ZLM downloadFile 下载各片段
       -> FFmpeg concat 合并
       -> FFmpeg 按起止时间 -c copy 剪切
       -> SUCCESS
  -> 云端录像缺失/不完整时回退：
       WVP gb_record/download/start（GB28181 设备录像下载）
       -> 轮询 progress + downLoadFilePath
       -> 从 ZLM downloadFile 流式拉取 MP4（带 secret）
       -> FFmpeg 转封装（-c copy + faststart）
       -> SUCCESS，file_url 静态下载
```

- 云端录像来自 WVP/ZLM 对平台预览、回放的录制，受 WVP 保留天数限制；
  没有云端录像的时间段会自动回退到设备录像下载。
- 设备录像优先按 NVR 上报的录像段（RecordInfo）下载，段内再按 10 分钟切分，最后合并/剪切；
  避免跨录像文件边界下载导致设备超时/断流，也避免长片段 INVITE 无响应（WVP `-1024`）。
  设备段不可用时回退固定时长分段。
- 每段下载后用 ffprobe 校验时长，不足 95% 自动降为 1 倍速重试；仍不完整则自动对半拆分继续下载，
  直到最小 2 分钟；达到最小段仍不完整才失败并明确提示，不会把设备中途断流的残缺文件当作成功。
- 分段之间默认等待 2 秒、重试前等待 10 秒，给设备释放 SIP 下载会话，避免连续请求收流超时。
- 设备录像下载默认 4 倍速，失败自动降为 1 倍速重试一次。
- 下载文件约 4GB 上限，可通过 `zlm.max-download-bytes` 调整。
- FFmpeg 未安装时，如果原始文件已是合法 MP4，会直接使用原始文件。
- 任务支持取消、重试、删除；服务重启时进行中的任务会标记失败，`PENDING` 自动重新入队。

## Windows / Linux 适配

- 存储根目录：`visi.storage.windows-root` / `linux-root` 按操作系统自动选择。
- FFmpeg：可配置命令名或绝对路径；Windows 可指向 `ffmpeg.exe`。
- 启动脚本：`scripts/start.sh`（Linux）、`scripts/start.bat` / `start.ps1`（Windows）。
- 路径处理：数据库中只保存相对路径，下载/静态访问前统一做路径越界校验。
- Docker：`deploy/docker-compose.yml` 提供业务库 + 后端 + Nginx；WVP/ZLM 按官方镜像单独启动。

## 已知限制

- 不实现登录、RBAC、租户隔离、操作日志；由外部系统负责。
- 首版单实例：预览/回放会话保存在内存，不支持多实例共享。
- 不支持自研 SIP、ONVIF、海康 SDK 私有协议。
- 浏览器预览要求 H.264 子码流；不做 H.265 全量转码（可配置可选转码，但不作为默认能力）。
- 首版不支持“下载失败回退到回放实时录制”。
- 无 HTTPS 证书自动管理；生产环境请由 Nginx 终止 TLS。
- 本项目未内置 WVP/ZLM/MySQL/FFmpeg 的安装包。

## 安全说明

- 系统本身**没有登录鉴权**，请部署在可信内网或由外部网关统一鉴权。
- 不要将 WVP、ZLM、MySQL、Druid 监控页直接暴露公网。
- 建议开启 WVP `user-settings.interface-authentication` 并修改默认密码；
  本服务配置 `wvp.auth-enabled=true` 后会自动登录并刷新 token。
- Nginx 必须拒绝 `/zlm/index/api/`；ZLM `api.secret` 仅配置在后端。
- 生产环境修改数据库默认密码、WVP 默认密码和 ZLM secret，并使用环境变量注入。
- 第三方组件（WVP-PRO、ZLMediaKit、FFmpeg、mpegts.js、hls.js）遵循各自许可证。

## 相关文档

- [海康 GB28181 接入与页面使用指南](./doc/usage-guide.md)
- [Windows / Linux / Docker 部署文档](./doc/deployment.md)
- [数据库初始化脚本](./doc/visi_watch.sql)
- [WVP-PRO](https://github.com/648540858/wvp-GB28181-pro)
- [WVP-PRO 文档](https://doc.wvp-pro.cn)
- [ZLMediaKit](https://github.com/ZLMediaKit/ZLMediaKit)
- [ZLMediaKit 配置](https://docs.zlmediakit.com/guide/media_server/config_file.html)
- [FFmpeg](https://ffmpeg.org/download.html)

## 版权声明

版权所有 © 2025-2026 pg_tech。保留所有权利。

本项目仅供 **个人学习、研究** 使用，**禁止任何形式的商业用途**（含企业内部生产使用）。
如需商用，请先联系 **pg_tech@163.com** 取得书面授权。完整条款见 [LICENSE.md](./LICENSE.md)。