# 快速开始（使用 Java 17）

## 📋 前置要求

✅ 已安装：
- Java 17（已确认）
- Node.js（已确认）
- Docker（已确认）

⚠️ 需要安装：
- **Maven 3.3+**

## 🔧 安装 Maven

### 方法一：手动安装（推荐）

1. **下载 Maven**
   - 访问：https://maven.apache.org/download.cgi
   - 下载：`apache-maven-3.9.9-bin.zip`
   - 国内镜像：https://mirrors.aliyun.com/apache/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.zip

2. **解压到指定目录**
   ```
   解压到：C:\Program Files\apache-maven-3.9.9
   ```

3. **配置环境变量**
   - 打开"系统属性" → "高级" → "环境变量"
   - 在"系统变量"中找到 `Path`
   - 点击"编辑" → "新建"
   - 添加：`C:\Program Files\apache-maven-3.9.9\bin`
   - 点击"确定"保存

4. **验证安装**

   打开**新的** CMD 或 PowerShell：
   ```cmd
   mvn -version
   ```

   应该显示：
   ```
   Apache Maven 3.9.9
   Maven home: C:\Program Files\apache-maven-3.9.9
   Java version: 17.0.x
   ```

### 方法二：使用 Chocolatey（如果已安装）

```powershell
# 以管理员身份运行 PowerShell
choco install maven
```

### 方法三：使用 Scoop

```powershell
scoop install maven
```

---

## 🚀 启动步骤

### 第一次使用

1. **确保基础服务运行**
   ```cmd
   cd docker
   docker compose up -d polaris-redis polaris-mysql polaris-media
   cd ..
   ```

2. **编译项目**

   双击运行：`编译.bat`

   或在 CMD 中：
   ```cmd
   编译.bat
   ```

   脚本会自动：
   - ✅ 检查 Java 和 Maven
   - ✅ 编译前端（Vue）
   - ✅ 编译后端（Spring Boot）
   - ✅ 检查基础服务状态

3. **启动应用**

   双击运行：`启动.bat`

   或在 CMD 中：
   ```cmd
   启动.bat
   ```

4. **访问应用**
   - 管理后台：http://localhost:18080
   - API 文档：http://localhost:18080/doc.html
   - 默认账号：`admin` / `admin`

### 后续使用

修改代码后，只需：
```cmd
编译.bat
启动.bat
```

---

## 📂 功能模块位置

### 1. 主码流/子码流切换
```
src/main/java/com/genersoft/iot/vmp/gb28181/
├── service/impl/PlayServiceImpl.java       # 播放服务（包含码流切换逻辑）
├── controller/DeviceQuery.java             # 设备查询控制器
└── bean/DeviceChannel.java                 # 通道实体（streamType字段）
```

**API 端点：**
- 主码流：`GET /api/play/{deviceId}/{channelId}/start?streamType=0`
- 子码流：`GET /api/play/{deviceId}/{channelId}/start?streamType=1`

### 2. 云台控制（转向、拉近、拉远）
```
src/main/java/com/genersoft/iot/vmp/gb28181/
├── controller/PtzController.java           # 云台控制主接口
├── service/
│   ├── IPTZService.java                   # PTZ 服务接口
│   └── impl/PTZServiceImpl.java           # PTZ 服务实现
├── transmit/cmd/impl/SIPCommander.java    # 发送 SIP 命令
└── bean/
    ├── FrontEndControlCodeForPTZ.java     # PTZ 控制码
    └── FrontEndCode.java                   # 前端控制码
```

**API 端点：**
- 左转：`GET /api/front-end/{deviceId}/{channelId}/left`
- 右转：`GET /api/front-end/{deviceId}/{channelId}/right`
- 上转：`GET /api/front-end/{deviceId}/{channelId}/up`
- 下转：`GET /api/front-end/{deviceId}/{channelId}/down`
- 拉近：`GET /api/front-end/{deviceId}/{channelId}/zoom_in`
- 拉远：`GET /api/front-end/{deviceId}/{channelId}/zoom_out`

### 3. 无限制设备接入
```
src/main/java/com/genersoft/iot/vmp/gb28181/
├── service/impl/DeviceServiceImpl.java    # 设备管理服务
├── transmit/event/request/impl/
│   ├── RegisterRequestProcessor.java      # 设备注册处理
│   └── MessageRequestProcessor.java       # 心跳和消息处理
├── SipLayer.java                          # SIP 协议层
└── dao/
    ├── DeviceMapper.java                  # 设备数据访问
    └── DeviceChannelMapper.java           # 通道数据访问
```

**性能配置：**
```yaml
# src/main/resources/application.yml
spring:
  datasource:
    hikari:
      maximum-pool-size: 200    # 连接池大小
      minimum-idle: 10

sip:
  pool-size: 100                # SIP 线程池
```

---

## 🔍 常见问题

### 1. 编译失败：Maven 命令未找到

**原因**：Maven 未安装或环境变量未配置

**解决**：按照上面的"安装 Maven"步骤操作

### 2. 端口被占用

**错误**：`Address already in use: bind`

**解决**：修改端口
```yaml
# src/main/resources/application-dev.yml
server:
  port: 28080  # 改为其他端口
```

### 3. 数据库连接失败

**检查 MySQL 状态**：
```cmd
docker ps | findstr mysql
docker logs docker-polaris-mysql-1
```

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

### 4. Redis 连接失败

**检查 Redis**：
```cmd
docker exec -it docker-polaris-redis-1 redis-cli ping
```

应该返回 `PONG`

---

## 📝 配置文件说明

### 开发环境配置
文件：`src/main/resources/application-dev.yml`

```yaml
spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/wvp?...
    username: wvp_user
    password: wvp_password

server:
  port: 18080

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

### Docker 配置
文件：`docker/.env`

```env
# 流媒体端口
MediaRtmp=10001
MediaRtsp=10002
MediaRtp=10003

# Web 端口
WebHttp=8080

# IP 配置（公网部署时需修改）
Stream_IP=127.0.0.1
SDP_IP=127.0.0.1

# SIP 配置
SIP_Port=8160
SIP_Domain=3502000000
```

---

## 🛠️ 服务管理

### 查看服务状态
```cmd
docker ps --filter "name=polaris-"
```

### 启动基础服务
```cmd
cd docker
docker compose up -d polaris-redis polaris-mysql polaris-media
```

### 停止所有服务
```cmd
cd docker
docker compose down
```

### 查看日志
```cmd
# WVP 日志（运行时控制台输出）

# Docker 服务日志
docker compose logs -f polaris-redis
docker compose logs -f polaris-mysql
docker compose logs -f polaris-media
```

---

## 📚 相关文档

- [完整启动指南](启动指南-Java17.md)
- [快速启动说明](QUICKSTART.md)
- [官方文档](https://doc.wvp-pro.cn)
- [GitHub](https://github.com/648540858/wvp-GB28181-pro)

---

## ⚡ 快捷命令

```cmd
# 一键编译
编译.bat

# 一键启动
启动.bat

# 查看服务状态
docker ps --filter "name=polaris-"

# 重新编译并启动
编译.bat && 启动.bat
```

---

最后更新：2026-02-02