wvp-platform/QUICKSTART.md

# WVP-PRO 快速启动指南

## 当前状态

### ✅ 已启动的服务
以下 Docker 容器已成功运行：
- **Redis** (docker-polaris-redis-1) - 端口 6379 - 健康运行
- **MySQL 8** (docker-polaris-mysql-1) - 端口 3306 - 健康运行，数据库已自动初始化
- **ZLMediaKit** (docker-polaris-media-1) - 流媒体服务 - 运行正常
  - RTMP: 10001
  - RTSP: 10002
  - RTP: 10003

### ⚠️ 待解决问题
- WVP-PRO 应用和 Nginx 前端尚未启动（Docker 镜像拉取失败）

---

## 方案 A：Docker 完整部署（推荐）

### 前提条件
需要解决 Docker Hub 网络连接问题。

### 步骤 1：配置 Docker 镜像加速

#### Windows/Mac (Docker Desktop):
1. 打开 Docker Desktop
2. 进入 Settings > Docker Engine
3. 添加以下配置：
```json
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.mirrors.ustc.edu.cn"
  ]
}
```
4. 点击 "Apply & Restart"

### 步骤 2：拉取所需镜像
```bash
cd docker

# 拉取 JDK 镜像（用于构建）
docker pull eclipse-temurin:21-jdk
docker pull eclipse-temurin:21-jre

# 拉取 Node 镜像（用于前端构建）
docker pull ubuntu:24.04
docker pull nginx:alpine
```

### 步骤 3：构建并启动所有服务
```bash
# 构建 WVP 和 Nginx
docker compose build

# 启动所有服务
docker compose up -d
```

### 步骤 4：验证服务状态
```bash
# 查看所有服务状态
docker compose ps

# 查看 WVP 日志
docker compose logs -f polaris-wvp
```

### 步骤 5：访问服务
- **管理后台**: http://localhost:8080
- **API 文档**: http://localhost:18978/doc.html
- **默认账号**: admin / admin

---

## 方案 B：本地开发模式

适用于需要频繁修改代码的开发场景。

### 前提条件
- JDK 21 ([下载地址](https://adoptium.net/temurin/releases/?version=21))
- Maven 3.3+ ([下载地址](https://maven.apache.org/download.cgi))
- Node.js 16+ ([下载地址](https://nodejs.org/))

### 步骤 1：保持基础服务运行
```bash
# 验证基础服务状态
docker ps --filter "name=polaris-redis|polaris-mysql|polaris-media"

# 如果服务未运行，启动它们
cd docker
docker compose up -d polaris-redis polaris-mysql polaris-media
```

### 步骤 2：编译前端
```bash
cd web
npm install --registry=https://registry.npmmirror.com
npm run build:prod
cd ..
```

### 步骤 3：配置应用
编辑 `src/main/resources/application-dev.yml`（已有模板），确认配置：
```yaml
spring:
  data:
    redis:
      host: 127.0.0.1  # 或 localhost
      port: 6379
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/wvp?...
    username: wvp_user
    password: wvp_password

media:
  ip: 127.0.0.1
  http-port: 8080
```

### 步骤 4：编译后端
```bash
mvn clean package -Dmaven.test.skip=true
```

### 步骤 5：运行应用
```bash
# 指定使用 dev 配置
java -jar target/wvp-pro-2.7.4-*.jar --spring.profiles.active=dev
```

### 步骤 6：访问服务
- **管理后台**: http://localhost:18080 (注意端口)
- **API 文档**: http://localhost:18080/doc.html

---

## 方案 C：混合模式（最快）

基础服务用 Docker，应用本地运行（无需编译）。

### 步骤 1：下载预编译包
如果网络允许，可以从项目 Release 页面下载预编译的 jar 包。

### 步骤 2：使用现有的 Docker 配置运行
```bash
cd docker/wvp
# 将预编译的 jar 包重命名为 wvp.jar
# 修改 wvp/application-docker.yml 中的数据库配置指向 localhost
```

---

## 常见问题

### 1. Docker 镜像拉取失败
**问题**: `failed to fetch anonymous token` 或 `EOF`
**解决**:
- 配置国内镜像源（见方案 A 步骤 1）
- 或使用代理
- 或使用方案 B 本地运行

### 2. MySQL 连接失败
**问题**: `Communications link failure`
**解决**:
```bash
# 检查 MySQL 是否健康
docker ps | grep mysql

# 查看 MySQL 日志
docker logs docker-polaris-mysql-1

# 测试连接
docker exec -it docker-polaris-mysql-1 mysql -u wvp_user -pwvp_password -e "show databases;"
```

### 3. 端口冲突
**问题**: `bind: address already in use`
**解决**: 修改 `docker/.env` 文件中的端口配置：
```env
WebHttp=18080      # 改为其他端口
SIP_Port=8160      # 改为其他端口
```

### 4. 编译失败 - Java 版本不对
**问题**: `release version 21 not supported`
**解决**:
```bash
# 检查 Java 版本
java -version

# 必须使用 JDK 21，如果不是，请升级
```

---

## 服务管理命令

### Docker 方式
```bash
cd docker

# 启动所有服务
docker compose up -d

# 停止所有服务
docker compose down

# 重启服务
docker compose restart polaris-wvp

# 查看日志
docker compose logs -f polaris-wvp

# 查看服务状态
docker compose ps

# 清理并重建
docker compose down -v
docker compose build --no-cache
docker compose up -d
```

### 本地运行方式
```bash
# 停止应用：Ctrl + C

# 后台运行
nohup java -jar target/wvp-pro-*.jar &

# 查看日志
tail -f nohup.out

# 停止后台进程
ps aux | grep wvp-pro
kill <PID>
```

---

## 配置说明

### 关键配置项 (docker/.env)
```env
# 流媒体端口
MediaRtmp=10001      # RTMP 推拉流端口
MediaRtsp=10002      # RTSP 推拉流端口
MediaRtp=10003       # RTP 端口

# Web 服务端口
WebHttp=8080         # HTTP 端口

# IP 配置（重要！）
Stream_IP=<你的服务器IP>    # 流地址中的 IP，客户端需要能访问
SDP_IP=<你的服务器IP>       # SDP 中的 IP，设备需要能访问
SIP_ShowIP=<你的服务器IP>   # SIP 显示的 IP

# SIP 配置（国标设备接入）
SIP_Port=8160                    # SIP 端口
SIP_Domain=3502000000            # SIP 域（根据实际修改）
SIP_Id=35020000002000000001      # SIP ID
SIP_Password=wvp_sip_password    # 设备认证密码
```

### 公网部署注意事项
1. 将所有 `127.0.0.1` 改为你的**公网 IP** 或**内网 IP**（根据部署场景）
2. 确保防火墙开放所需端口
3. 建议启用 HTTPS（需要配置证书）

---

## 下一步

### 测试设备接入
1. 配置国标设备（IPC/NVR）的 SIP 服务器信息：
   - 服务器 IP: `<你的 SIP_ShowIP>`
   - 服务器端口: `8160`（或你配置的 SIP_Port）
   - 服务器域: `3502000000`（或你配置的 SIP_Domain）
   - 设备 ID: 20位国标编码
   - 密码: `wvp_sip_password`（或你配置的密码）

2. 设备注册成功后，在 WVP 管理后台可以看到设备列表

### 推流测试
```bash
# 使用 FFmpeg 推流测试
ffmpeg -re -i test.mp4 -c copy -f rtsp rtsp://localhost:10002/test

# 播放地址
# HTTP-FLV: http://localhost:8080/live/test.flv
# WebSocket-FLV: ws://localhost:8080/live/test.flv
# HLS: http://localhost:8080/live/test.m3u8
```

---

## 获取帮助

- 官方文档: https://doc.wvp-pro.cn
- GitHub: https://github.com/648540858/wvp-GB28181-pro
- Gitee: https://gitee.com/pan648540858/wvp-GB28181-pro
- 问题反馈: 提交 GitHub Issue

---

最后更新: 2026-02-02