QDAirPortBackend0122/doc/deploy/traffic-light-deployment.md

# 红绿灯信号集成系统部署指南

## 概述

本文档描述了红绿灯信号集成系统的部署步骤和配置说明。该系统通过TCP服务器接收红绿灯硬件信号，解析后通过WebSocket广播给前端客户端。

## 系统架构

```
红绿灯硬件 → TCP服务器(8082) → 信号解析器 → 数据处理服务 → WebSocket广播 → 前端客户端
                ↓
            数据库(路口/设备管理)
```

## 部署前准备

### 1. 环境要求

- **Java**: JDK 17 或更高版本
- **数据库**: PostgreSQL 12+ (已启用PostGIS扩展)
- **Redis**: 6.0+ (用于缓存)
- **网络**: 确保8082端口可用于TCP连接

### 2. 数据库初始化

执行以下SQL脚本初始化红绿灯相关表：

```bash
# 1. 创建红绿灯系统表
psql -h localhost -U postgres -d qaup_database -f sql/create_traffic_light_tables.sql

# 2. 验证数据完整性
psql -h localhost -U postgres -d qaup_database -f sql/validate_traffic_light_data.sql
```

### 3. 配置文件设置

在 `application.yml` 中配置红绿灯系统参数：

```yaml
# 红绿灯系统配置
traffic:
  light:
    tcp:
      # 是否启用TCP服务器
      enabled: true
      # TCP监听端口
      port: 8082
      # 最大连接数
      max-connections: 50
      # 连接超时时间（毫秒）
      connection-timeout: 30000
      # 心跳超时时间（分钟）
      heartbeat-timeout-minutes: 5
    
    intersection:
      # 默认路口ID（当信号中没有指定时使用）
      default-id: "DEFAULT_INTERSECTION"
      # 默认坐标
      default-latitude: 0.0
      default-longitude: 0.0
    
    processing:
      # 是否启用统计功能
      enable-statistics: true
      # 统计信息输出间隔（毫秒）
      statistics-interval: 60000
      # 是否启用调试日志
      enable-debug-log: false
```

## 部署步骤

### 1. 编译和打包

```bash
# 编译项目
mvn clean compile

# 运行测试
mvn test

# 打包应用
mvn clean package -DskipTests
```

### 2. 启动应用

```bash
# 方式1: 直接运行JAR包
java -jar qaup-admin/target/qaup-admin.jar

# 方式2: 使用Spring Boot Maven插件
mvn spring-boot:run -pl qaup-admin

# 方式3: 使用Docker (如果有Docker配置)
docker-compose up -d
```

### 3. 验证部署

#### 检查TCP服务器状态
```bash
# 检查端口是否监听
netstat -tlnp | grep 8082

# 或使用ss命令
ss -tlnp | grep 8082
```

#### 检查应用健康状态
```bash
# 访问健康检查接口
curl http://localhost:8080/health

# 检查红绿灯系统状态
curl http://localhost:8080/health/traffic-light
```

#### 检查WebSocket连接
```bash
# 访问WebSocket测试页面
http://localhost:8080/websocket-test.html
```

## 配置管理

### 1. 路口信息管理

通过REST API管理路口信息：

```bash
# 查看所有路口
curl http://localhost:8080/api/intersections

# 添加新路口
curl -X POST http://localhost:8080/api/intersections \
  -H "Content-Type: application/json" \
  -d '{
    "intersectionId": "INTERSECTION_003",
    "intersectionName": "新路口",
    "latitude": 39.9060,
    "longitude": 116.4090,
    "areaCode": "AREA_C"
  }'

# 查看特定路口
curl http://localhost:8080/api/intersections/INTERSECTION_001
```

### 2. 红绿灯设备管理

```bash
# 查看所有设备
curl http://localhost:8080/api/traffic-lights

# 添加新设备
curl -X POST http://localhost:8080/api/traffic-lights \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "TL_003",
    "deviceName": "新红绿灯设备",
    "intersectionId": "INTERSECTION_003",
    "manufacturer": "海康威视",
    "model": "DS-TL300"
  }'

# 查看设备状态
curl http://localhost:8080/api/traffic-lights/TL_001/status
```

## 测试和验证

### 1. 使用测试客户端

运行提供的Python测试客户端：

```bash
# 安装Python依赖（如果需要）
pip3 install socket json

# 运行测试客户端
python3 test_traffic_light_client.py
```

### 2. 手动发送测试信号

使用telnet或nc命令手动发送信号：

```bash
# 使用telnet
telnet localhost 8082

# 发送JSON信号（在telnet会话中）
{"device_id":"TL_001","DI-01":0,"DI-02":0,"DI-11":1,"DI-12":0,"DI-13":0,"DI-14":0,"DI-15":0,"DI-16":1,"DI-17":0,"DI-18":0}

# 使用nc命令
echo '{"device_id":"TL_001","DI-11":1,"DI-16":1}' | nc localhost 8082
```

### 3. 监控WebSocket消息

在浏览器中打开开发者工具，连接到WebSocket端点：

```javascript
const ws = new WebSocket('ws://localhost:8080/collision');
ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    if (message.type === 'intersection_traffic_light_status') {
        console.log('红绿灯状态更新:', message.payload);
    }
};
```

## 故障排除

### 1. TCP服务器无法启动

**问题**: 端口8082被占用
```bash
# 查找占用端口的进程
lsof -i :8082

# 杀死占用进程
kill -9 <PID>
```

**问题**: 权限不足
```bash
# 使用sudo运行或更改端口到1024以上
```

### 2. 数据库连接问题

**问题**: 无法连接到PostgreSQL
```bash
# 检查数据库服务状态
systemctl status postgresql

# 检查连接配置
psql -h localhost -U postgres -d qaup_database -c "SELECT 1;"
```

### 3. 信号解析错误

**问题**: JSON格式错误
- 检查发送的JSON格式是否正确
- 查看应用日志中的解析错误信息
- 使用JSON验证工具验证格式

### 4. WebSocket连接问题

**问题**: 前端无法接收消息
- 检查WebSocket连接是否建立成功
- 验证消息类型过滤是否正确
- 查看浏览器控制台错误信息

## 性能监控

### 1. 关键指标

- **TCP连接数**: 当前活跃的红绿灯设备连接数
- **信号处理速度**: 每秒处理的信号数量
- **解析成功率**: 成功解析的信号比例
- **WebSocket客户端数**: 连接的前端客户端数量

### 2. 监控接口

```bash
# 系统整体状态
curl http://localhost:8080/health

# 红绿灯系统统计
curl http://localhost:8080/api/traffic-lights/statistics

# TCP服务器状态
curl http://localhost:8080/api/traffic-lights/server/status
```

### 3. 日志监控

重要日志文件和关键字：

```bash
# 查看TCP服务器日志
grep "TrafficLightTcpServer" logs/application.log

# 查看信号解析日志
grep "TrafficLightSignalParser" logs/application.log

# 查看WebSocket广播日志
grep "TrafficLightStatusEventListener" logs/application.log
```

## 安全考虑

### 1. 网络安全

- 限制8082端口的访问来源
- 使用防火墙规则保护TCP端口
- 考虑使用TLS加密TCP连接（如果硬件支持）

### 2. 数据验证

- 验证设备ID的合法性
- 检查信号数据的合理性
- 记录异常信号和可疑连接

### 3. 访问控制

- 为管理API添加认证机制
- 限制WebSocket连接的来源
- 定期审查设备注册信息

## 维护和升级

### 1. 定期维护

- 清理过期的连接记录
- 检查数据库表的性能
- 更新设备心跳状态
- 备份路口和设备配置

### 2. 系统升级

- 在升级前备份数据库
- 测试新版本的兼容性
- 逐步升级，避免服务中断
- 验证升级后的功能完整性

### 3. 容量规划

- 监控系统资源使用情况
- 根据设备数量调整连接池大小
- 优化数据库查询性能
- 考虑水平扩展方案

## 联系支持

如遇到部署问题，请提供以下信息：

1. 系统环境信息（OS、Java版本等）
2. 错误日志和堆栈跟踪
3. 配置文件内容
4. 网络环境描述
5. 复现步骤

---

**版本**: 1.0.0  
**更新日期**: 2025-01-05  
**维护团队**: QAUP开发团队