# its-backend

**Repository Path**: yimeng812/its-backend

## Basic Information

- **Project Name**: its-backend
- **Description**: 基于 Spring Boot 4.1 的智能交通系统后端服务，为 3D 前端 提供 WebSocket 实时推流、MQTT 车辆通信、Valhalla 路网代理和行政区划查询等能力。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-22
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ITS — 3D 智能交通仿真系统（后端）

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

基于 Spring Boot 4.1 的智能交通系统后端服务，为 [3D 前端](../frontend) 提供 WebSocket 实时推流、MQTT 车辆通信、Valhalla 路网代理和行政区划查询等能力。

## 技术栈

| 类别 | 技术 |
|------|------|
| 运行时 | Java 17 |
| 框架 | Spring Boot 4.1 |
| 构建 | Maven |
| 实时通信 | Jakarta WebSocket + Eclipse Paho MQTT v3 |
| HTTP 客户端 | Apache HttpClient 5 |
| JSON | Fastjson2 |
| 工具库 | Hutool、Lombok |
| 加密 | Bouncy Castle（SM4-GCM） |
| 空间计算 | JTS Topology Suite 1.20 |

## 模块概览

```
com.loser.its
├── ItsApplication              # 启动类
├── config/                     # CORS、MQTT、WebSocket、Valhalla 等配置
├── map/                        # 地图服务
│   ├── MapController           #   天地图 Token 下发、坐标→行政区划
│   └── AdminLocatorManager     #   基于 DataV GeoJSON + JTS 的行政区划定位
├── valhalla/                   # Valhalla 路网引擎代理
│   ├── ValhallaController      #   路线 / 等时线 / 路网匹配 / MVT 瓦片等 REST API
│   └── ValhallaProxy           #   请求转发（文本 & 二进制）
├── mqtt/                       # MQTT 车辆通信
│   ├── MqttManager             #   消息发布、下行事件订阅与 WS 转发
│   ├── MqttLocEnvelope         #   上行定位信封（SM4-GCM 加密）
│   ├── Sm4GcmUtil              #   SM4-GCM 加解密工具
│   └── ...                     #   配置、DTO、健康监控
├── cheluyunting/               # 车路云听开放平台对接
│   ├── CheLuYunTingController  #   交通事件上报 API
│   ├── CheLuYunTingClient      #   签名鉴权 + HTTP 转发
│   └── dto/                    #   请求/响应 DTO
└── ws/                         # WebSocket 服务端
    ├── WebSocketServer         #   多车 WebSocket 端点 /websocket/client/{vehicleId}
    └── VehicleWSData           #   车辆上行数据 DTO
```

## API 一览

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/map/token` | 获取天地图 Token |
| GET | `/api/v1/map/location?lon=&lat=` | 坐标→省/市/区行政区划 |
| POST | `/api/v1/valhalla/route` | 路线规划代理 |
| POST | `/api/v1/valhalla/isochrone` | 等时线计算代理 |
| POST | `/api/v1/valhalla/trace_attributes` | GPS 轨迹路网匹配（属性） |
| POST | `/api/v1/valhalla/trace_route` | GPS 轨迹路网匹配（路线） |
| POST | `/api/v1/valhalla/locate` | 路网定位 |
| POST | `/api/v1/valhalla/status` | Valhalla 引擎状态 |
| POST | `/api/v1/valhalla/tile` | MVT 路网瓦片（二进制） |
| POST | `/api/v1/event/trafficMessage/upload` | 上报交通事件至车路云听 |
| WS | `/websocket/client/{vehicleId}` | 车辆双向实时通道 |

## 数据流

```
前端 (Cesium 3D)
  │
  ├─ WebSocket ─▶ WebSocketServer ─▶ MqttManager ─▶ MQTT Broker (上行定位)
  │                                                    │
  │                                                    ▼
  │                                               MQTT Broker (下行事件)
  │                                                    │
  │◀─ WebSocket ◀── WebSocketServer ◀── MqttManager ◀─┘
  │
  ├─ HTTP ─▶ ValhallaController ─▶ Valhalla ─▶ Valhalla 路网引擎
  ├─ HTTP ─▶ MapController ─▶ AdminLocatorManager ─▶ 阿里 DataV GeoJSON
  └─ HTTP ─▶ CheLuYunTingController ─▶ 车路云听开放平台
```

## 配置

编辑 `src/main/resources/application.yaml`，关键配置项：

```yaml
server:
  port: 8088                      # 服务端口

geo:
  Valhalla:
    enabled: true                 # 是否启用 Valhalla 代理
    base-url: http://localhost:8002

tian-di-tu:
  tk: ${TIAN_DI_TU_TK}           # 天地图 API Key（环境变量注入）

mqtt:
  broker-url: ${BROKER_URL:tcp://127.0.0.1:1883}
  client-id: ${CLIENT_ID:ws-client}
  topic-prefix: VehicleUplink    # 上行主题前缀
  event-topic-prefix: VehicleDownlink  # 下行事件主题前缀
```

## 运行

```bash
# 编译
mvn package -DskipTests

# 运行（需要 Java 17+）
java -jar target/its.jar

# 或开发模式
mvn spring-boot:run
```

### 外部依赖

| 依赖 | 用途 | 默认地址 | 关闭/配置 | 部署参考 |
|------|------|----------|-----------|----------|
| [Valhalla](https://github.com/valhalla/valhalla) | 路线规划、等时线、路网匹配、MVT 路网瓦片 | `localhost:8002` | `geo.Valhalla.enabled=false` | [Docker 部署](https://github.com/valhalla/valhalla/blob/master/docs/docker.md)，需加载 OSM 地图数据 |
| [MQTT Broker](https://mqtt.org/) (Mosquitto/EMQX/阿里云 MQTT) | 车辆上行定位推送、下行事件下发 | `localhost:1883` | `mqtt.broker-url` | 本地开发: `docker run -p 1883:1883 eclipse-mosquitto`；生产: 阿里云 MQTT 实例 |
| [天地图](https://lbs.tianditu.gov.cn/) | 3D 地图底图（影像/矢量/标注） | — | `tian-di-tu.tk` | [申请 API Key](https://lbs.tianditu.gov.cn/home.html)，免费注册 |
| [阿里 DataV](https://datav.aliyun.com/portal/school/atlas/area_selector) | 行政区划边界 GeoJSON（省/市/区定位） | — | 无需配置，按需在线加载 | 无需部署，公共 API |
| [车路云听](https://www.cheluyunting.com/) | 交通事件上报开放平台 | — | `mqtt.server-app-id` / `mqtt.server-secret-key` | [接入文档](https://www.cheluyunting.com/open)，需申请渠道密钥 |

## 关联项目

| 仓库 | 说明 |
|------|------|
| [its-frontend](https://gitee.com/yimeng812/its-frontend) | Vue 3 + CesiumJS 3D 前端 |

## 许可证

本项目基于 [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0) 开源。详见 [LICENSE](LICENSE) 文件。

本项目采用双重许可模式：AGPL-3.0（开源）+ 商业许可。贡献者需签署 [贡献者许可协议（CLA）](CLA.md)，授权项目维护者将其贡献同时用于商业许可版本。