# drone-management

**Repository Path**: mas_java/drone-management

## Basic Information

- **Project Name**: drone-management
- **Description**: 一个专注于无人机管理系统的开源项目，提供高效、可靠的无人机调度与监控解决方案，适用于多种行业应用。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 无人机管理平台（Drone Management）

> 基于 DDD 多模块架构的无人机管理平台，提供无人机注册、轨迹采集、碰撞检测、轨迹预测、合规监管等全生命周期管理能力，支持 3000+ 架无人机并发监控。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.org/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.5-green.svg)](https://spring.io/projects/spring-boot)
[![MyBatis-Plus](https://img.shields.io/badge/MyBatis--Plus-3.5.5-red.svg)](https://baomidou.com/)

---

## 目录

- [项目简介](#项目简介)
- [核心特性](#核心特性)
- [技术栈](#技术栈)
- [系统架构](#系统架构)
- [模块说明](#模块说明)
- [快速开始](#快速开始)
- [接口文档](#接口文档)
- [部署指南](#部署指南)
- [项目文档](#项目文档)
- [参与贡献](#参与贡献)
- [开源许可](#开源许可)

---

## 项目简介

随着低空经济的发展和《民用无人驾驶航空器系统运行识别规范》（GB46750-2025）的强制实施，无人机管理面临轨迹分散、安全风险高、预测能力缺失、监管合规压力等痛点。本平台旨在构建一个通用无人机管理平台，实现：

- 无人机飞行轨迹的统一采集、存储、展示和管理
- 基于历史轨迹和实时数据的轨迹预测（卡尔曼滤波）
- 多无人机轨迹碰撞检测与预警
- 符合 GB46750-2025 的 Remote ID 运行识别与民航局 UOM 平台对接
- 提供 RESTful API 和可视化 Web 管理界面

### 性能指标

| 指标 | 目标值 |
|------|--------|
| 轨迹数据采集延迟 | ≤ 200ms |
| 碰撞检测响应时间 | ≤ 1s |
| 轨迹预测准确率 | ≥ 85%（10 秒预测窗口） |
| 平台可用性 | ≥ 99.5% |
| 同时管理无人机数量 | ≥ 3000 架（可扩展至 5000 架） |
| 轨迹点写入吞吐 | ≥ 30000 点/秒（3000 架 × 10Hz） |
| 90 天数据存储容量 | ≤ 150GB（TDengine 压缩后） |

---

## 核心特性

### 1. DDD 多模块架构
按业务领域划分限界上下文，每个模块采用 `interfaces / application / domain / infrastructure` 四层架构，通过 `drone-common` 定义跨模块接口契约，实现高内聚低耦合。

### 2. 双存储架构
- **PostgreSQL 16 + PostGIS 3.4**：存储业务数据、空间数据、合规数据
- **TDengine 3.3**：存储高频轨迹时序数据，支持千万级写入吞吐

### 3. 实时数据处理
- 基于 **Kafka** 的消息总线，解耦设备数据采集与业务处理
- 基于 **WebSocket** 的实时告警推送（碰撞告警、电子围栏违规、状态变更）
- 支持 **gRPC** 高性能设备数据上报（Telemetry）

### 4. 安全与合规
- **Sa-Token** 认证授权，支持 JWT + RBAC 权限模型
- **Remote ID** 注册与广播，符合 GB46750-2025 规范
- **电子围栏** 基于 PostGIS 空间计算，支持禁飞区/限制区/预警区
- **合规检查** 自动识别异常飞行行为（超速、超高、禁飞区入侵等）

### 5. 智能预测
- **卡尔曼滤波** 轨迹预测算法，支持 10-60 秒预测窗口
- 基于预测轨迹的 **碰撞检测**，提前预警潜在冲突

---

## 技术栈

### 后端

| 分类 | 技术 | 版本 |
|------|------|------|
| 基础框架 | Spring Boot | 3.2.5 |
| 开发语言 | Java | 17 |
| ORM 框架 | MyBatis-Plus | 3.5.5 |
| 数据库迁移 | Liquibase | 4.27.0 |
| 认证授权 | Sa-Token | 1.38.0 |
| 数据库 | PostgreSQL + PostGIS | 15 + 3.4 |
| 时序数据库 | TDengine | 3.3.3 |
| 消息队列 | Kafka | 3.7.0 |
| 缓存 | Redis | 7.x |
| 空间计算 | JTS + PostGIS | 1.19.0 + 2.5.1 |
| RPC 框架 | gRPC + Protobuf | 1.63.0 + 3.25.3 |
| 工具库 | Hutool | 5.8.27 |
| 接口文档 | SpringDoc OpenAPI | 2.3.0 |

### 前端

| 分类 | 技术 |
|------|------|
| 框架 | Vue 3 + TypeScript |
| 构建 | Vite |
| UI 组件 | Element Plus |
| 状态管理 | Pinia |
| 地图 | Leaflet / 高德地图 |
| HTTP | Axios |
| 实时通信 | WebSocket |

### 运维部署

| 分类 | 技术 |
|------|------|
| 容器化 | Docker + Docker Compose |
| CI/CD | Jenkins + GitHub Actions |
| 配置管理 | Ansible |
| 监控告警 | Prometheus + Alertmanager + Grafana |
| 编排 | Docker Swarm / Kubernetes |

---

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         客户端层                                 │
│   Web 管理台   │   设备模拟器   │   第三方系统   │   UOM 平台    │
└─────────┬────────────┬────────────────┬────────────┬────────────┘
          │            │                │            │
          ▼            ▼                ▼            ▼
┌─────────────────────────────────────────────────────────────────┐
│                      接入层（Nginx）                             │
│   HTTP/HTTPS   │   WebSocket   │   gRPC   │   Kafka Producer    │
└─────────┬──────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    drone-app（聚合启动模块）                     │
├─────────────────────────────────────────────────────────────────┤
│  drone-auth   │  drone-system  │  drone-device  │  drone-trajectory│
│  认证授权     │  系统管理      │  设备管理      │  轨迹管理         │
├─────────────────────────────────────────────────────────────────┤
│  drone-safety │  drone-prediction │  drone-ingestion │  drone-subscription│
│  安全合规     │  轨迹预测         │  数据接入        │  订阅管理          │
├─────────────────────────────────────────────────────────────────┤
│                       drone-common（公共契约）                   │
│   通用 DTO  │  跨模块接口  │  异常处理  │  枚举定义  │  注解      │
└─────────┬──────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                       中间件层                                   │
│   PostgreSQL + PostGIS  │  TDengine  │  Redis  │  Kafka         │
└─────────────────────────────────────────────────────────────────┘
```

---

## 模块说明

| 模块 | 说明 | 核心职责 |
|------|------|----------|
| `drone-common` | 公共模块 | 定义跨模块接口契约、通用 DTO、枚举、异常、注解 |
| `drone-auth` | 认证模块 | 用户登录、登出、Token 刷新、权限校验 |
| `drone-system` | 系统模块 | 系统配置管理、监控指标聚合、审计日志 |
| `drone-device` | 设备模块 | 无人机注册、查询、状态管理、设备令牌 |
| `drone-ingestion` | 接入模块 | Kafka 消费、gRPC 上报、数据清洗 |
| `drone-trajectory` | 轨迹模块 | 轨迹上报、查询、空间检索、实时推送 |
| `drone-safety` | 安全模块 | 碰撞检测、电子围栏、合规检查、Remote ID |
| `drone-prediction` | 预测模块 | 卡尔曼滤波轨迹预测、预测轨迹存储 |
| `drone-subscription` | 订阅模块 | 数据订阅、字段配置、推送规则 |
| `drone-app` | 聚合模块 | Spring Boot 启动入口、Bean 装配、定时任务 |
| `drone-simulator` | 模拟器 | 设备模拟器，独立部署用于压测 |

### 跨模块接口契约

为解耦模块间直接依赖，在 `drone-common` 中定义以下接口：

- `DroneInfoProvider`：无人机信息查询（由 drone-device 实现）
- `DroneStatusCacheProvider`：无人机状态缓存（由 drone-device 实现）
- `DeviceTokenValidator`：设备令牌校验（由 drone-device 实现）
- `TrajectoryQueryProvider`：轨迹查询（由 drone-trajectory 实现）
- `PredictionProvider`：轨迹预测（由 drone-prediction 实现）
- `RealtimePushService`：实时推送（由 drone-trajectory 实现）

---

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- Docker 20+ / Docker Compose 2+
- Node.js 18+（前端构建）
- PostgreSQL 15+ with PostGIS 3.4
- TDengine 3.3+
- Redis 7+
- Kafka 3.7+

### 1. 启动中间件

使用提供的 docker-compose 启动所有依赖中间件：

```bash
# 在部署服务器（如 192.168.127.128）执行
docker compose -f docker-compose.infra.yml up -d
```

包含组件：
- PostgreSQL 15 + PostGIS 3.4（端口 5432）
- TDengine 3.3（端口 6030/6041）
- Redis 7（端口 6379）
- Kafka 3.7（端口 9092）
- Zookeeper（端口 2181）

### 2. 配置数据库连接

复制环境变量模板并修改：

```bash
cp .env.example .env
```

修改 `drone-app/src/main/resources/application-dev.yml` 中的中间件地址：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://192.168.127.128:5432/drone_mgmt
    username: drone
    password: Drone@2026
  data:
    redis:
      host: 192.168.127.128
      port: 6379
  kafka:
    bootstrap-servers: 192.168.127.128:9092
  tdengine:
    url: jdbc:TAOS://192.168.127.128:6030/drone
```

### 3. 编译构建

```bash
# 编译所有模块
mvn clean install -DskipTests

# 仅编译特定模块
mvn -pl drone-app -am install -DskipTests
```

### 4. 启动后端

```bash
# 开发模式（dev profile）
mvn -pl drone-app spring-boot:run -Dspring-boot.run.profiles=dev

# 或打包后运行
java -jar drone-app/target/drone-app-1.0.0.jar --spring.profiles.active=dev
```

启动成功后访问：
- 应用首页：http://localhost:8080
- 接口文档：http://localhost:8080/swagger-ui.html
- 健康检查：http://localhost:8080/actuator/health

### 5. 启动前端

```bash
cd frontend
npm install
npm run dev
```

前端访问地址：http://localhost:5173

### 6. 默认账号

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | Admin@123 | 系统管理员 |

---

## 接口文档

### 认证接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/auth/login` | 用户登录 |
| POST | `/api/v1/auth/logout` | 用户登出 |
| POST | `/api/v1/auth/refresh` | 刷新 Token |
| POST | `/api/v1/auth/register` | 用户注册 |

### 设备管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/drones` | 无人机列表（分页） |
| GET | `/api/v1/drones/{id}` | 无人机详情 |
| POST | `/api/v1/drones` | 注册无人机 |
| PUT | `/api/v1/drones/{id}` | 更新无人机 |
| DELETE | `/api/v1/drones/{id}` | 删除无人机 |

### 轨迹管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/trajectory/report` | 上报轨迹点 |
| POST | `/api/v1/trajectory/report-batch` | 批量上报 |
| GET | `/api/v1/trajectory/{droneId}` | 查询历史轨迹 |
| GET | `/api/v1/trajectory/{droneId}/latest` | 最新轨迹点 |
| GET | `/api/v1/trajectory/spatial` | 空间范围查询 |

### 安全合规

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/collisions/detect` | 碰撞检测 |
| GET | `/api/v1/collisions` | 告警列表 |
| POST | `/api/v1/collisions/{id}/resolve` | 处理告警 |
| GET | `/api/v1/geofences` | 电子围栏列表 |
| POST | `/api/v1/geofences` | 创建围栏 |
| GET | `/api/v1/geofences/check` | 围栏合规检查 |
| POST | `/api/v1/compliance/check/{droneId}` | 触发合规检查 |
| POST | `/api/v1/compliance/remote-id/{droneId}` | 注册 Remote ID |
| GET | `/api/v1/compliance/remote-id/{droneId}` | 查询 Remote ID |

### 轨迹预测

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/predictions/{droneId}` | 查询预测轨迹 |
| POST | `/api/v1/predictions/{droneId}` | 触发轨迹预测 |

### 系统管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/system/monitor` | 系统监控指标 |
| GET | `/api/v1/system/configs` | 系统配置列表 |
| GET | `/api/v1/system/configs/{key}` | 获取配置项 |

> 完整接口文档启动后访问：http://localhost:8080/swagger-ui.html

---

## 部署指南

### Docker Compose 部署

```bash
# 部署中间件 + 应用
docker compose -f docker-compose.yml up -d

# 仅部署监控组件
docker compose -f docker-compose.monitor.yml up -d
```

### 生产环境部署

生产环境推荐使用 Docker Swarm 或 Kubernetes：

```bash
# Docker Swarm 部署
docker stack deploy -c docker-stack.yml drone

# Kubernetes 部署
# 参考 docs/12-k8s-deployment-design.md
```

详细部署指南请参考：
- [Docker 部署指南](docs/10-docker-deployment.md)
- [高级运维指南](docs/11-advanced-ops-guide.md)
- [Kubernetes 部署设计](docs/12-k8s-deployment-design.md)
- [部署 FAQ](docs/13-faq-deployment-guide.md)

---

## 项目文档

完整的项目文档位于 [`docs/`](docs/) 目录：

| 文档 | 说明 |
|------|------|
| [01-requirements.md](docs/01-requirements.md) | 需求分析文档 |
| [03-implementation-plan.md](docs/03-implementation-plan.md) | 实施计划 |
| [04-db-design.md](docs/04-db-design.md) | 数据库设计 |
| [05-api-design.md](docs/05-api-design.md) | API 设计文档 |
| [06-backend-report.md](docs/06-backend-report.md) | 后端开发报告 |
| [08-frontend-report.md](docs/08-frontend-report.md) | 前端开发报告 |
| [09-deployment-ops.md](docs/09-deployment-ops.md) | 部署运维指南 |
| [14-微服务架构拆分设计.md](docs/14-微服务架构拆分设计.md) | 微服务架构拆分设计 |
| [22-主工程DDD多模块拆分方案.md](docs/22-主工程DDD多模块拆分方案.md) | DDD 多模块拆分方案 |
| [gRPC深度解析-从原理到Telemetry实战.md](docs/gRPC深度解析-从原理到Telemetry实战.md) | gRPC 技术实战 |

---

## 参与贡献

1. Fork 本仓库
2. 新建特性分支：`git checkout -b feat/your-feature`
3. 提交代码：`git commit -m 'feat: add some feature'`
4. 推送分支：`git push origin feat/your-feature`
5. 提交 Pull Request

### 提交规范

遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

- `feat`：新功能
- `fix`：Bug 修复
- `docs`：文档更新
- `style`：代码格式（不影响功能）
- `refactor`：重构（既不是新增功能，也不是修复 Bug）
- `perf`：性能优化
- `test`：增加测试
- `chore`：构建工具或辅助工具变动

---

## 开源许可

本项目基于 [MIT License](LICENSE) 开源，欢迎自由使用和传播。