# cloud-platform-fence-server

**Repository Path**: chenqian1995/cloud-platform-fence-server

## Basic Information

- **Project Name**: cloud-platform-fence-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cloud Platform Fence Server

电子围栏告警系统 - 基于 Java8 + Spring Boot 2.7 + MySQL + Redis + Kafka

## 项目简介

支持 50 万辆车、10000 个围栏的实时电子围栏告警后端服务。

### 核心功能

- 📍 **位置上报**：车辆每 10 秒上报经纬度位置
- 🔔 **实时告警**：驶入/驶出围栏实时告警
- 📊 **连续判断**：支持连续 N 次触发才告警（可配置）
- 🔗 **N:N 关联**：围栏与车辆多对多关联
- ⚡ **高性能**：支持 5 万 TPS 位置上报处理

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| Java | 1.8 | 运行环境 |
| Spring Boot | 2.7.18 | 应用框架 |
| MySQL | 8.0 | 数据持久化 |
| Redis | 7.x | 缓存/状态存储 |
| Kafka | 3.4 | 消息队列 |
| MyBatis Plus | 3.5.3 | ORM 框架 |

## 快速开始

### 环境要求

- JDK 1.8+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+
- Kafka 3.0+

### 1. 初始化数据库

```bash
mysql -u root -p < src/main/resources/schema.sql
```

### 2. 配置环境变量

```bash
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USERNAME=root
export MYSQL_PASSWORD=root

export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_PASSWORD=

export KAFKA_SERVERS=localhost:9092
```

### 3. 启动应用

```bash
mvn clean package -DskipTests
java -jar target/cloud-platform-fence-server-1.0.0-SNAPSHOT.jar
```

### 4. 访问 API 文档

启动后访问：http://localhost:8080/api/doc.html

## 项目结构

```
cloud-platform-fence-server/
├── src/main/java/com/cloudfence/
│   ├── FenceServerApplication.java    # 启动类
│   ├── algorithm/                      # 核心算法
│   │   ├── GeoUtils.java              # 地理计算工具
│   │   └── FenceMatcher.java          # 围栏匹配器
│   ├── config/                         # 配置类
│   ├── controller/                     # REST 接口
│   │   ├── LocationController.java    # 位置上报
│   │   ├── FenceController.java       # 围栏管理
│   │   └── AlertController.java       # 告警查询
│   ├── kafka/                          # Kafka 配置
│   ├── mapper/                         # MyBatis Mapper
│   ├── model/                          # 数据模型
│   │   ├── entity/                    # 实体类
│   │   ├── dto/                       # 数据传输对象
│   │   ├── vo/                        # 视图对象
│   │   └── enums/                     # 枚举
│   ├── redis/                          # Redis 服务
│   └── service/                        # 业务服务
├── src/main/resources/
│   ├── application.yml                 # 应用配置
│   ├── application-prod.yml           # 生产配置
│   ├── mapper/                         # MyBatis XML
│   ├── scripts/                        # Lua 脚本
│   └── schema.sql                      # 数据库初始化脚本
└── pom.xml                             # Maven 配置
```

## 核心 API

### 位置上报

```bash
POST /api/v1/terminal/location/report
Content-Type: application/json

{
  "vin": "LSVAV64R7JN123456",
  "latitude": 39.9042,
  "longitude": 116.4074,
  "speed": 60.5,
  "direction": 180
}
```

### 创建围栏

```bash
POST /api/v1/fences?name=测试围栏&centerLat=39.9042&centerLon=116.4074&radius=1000
```

### 绑定车辆到围栏

```bash
POST /api/v1/fences/1/vehicles/bind
Content-Type: application/json

{
  "vehicleIds": [1, 2, 3],
  "enterAlert": true,
  "exitAlert": false,
  "consecutiveCnt": 3
}
```

### 查询告警列表

```bash
GET /api/v1/alerts?vin=LSV123&startTime=2026-03-01 00:00:00&endTime=2026-03-31 23:59:59
```

## 架构设计

详见 [resource](../resource) 目录下的设计文档：

- [系统架构设计文档](../resource/01-系统架构设计文档.md)
- [数据库设计文档](../resource/02-数据库设计文档.md)
- [API 接口设计文档](../resource/03-API 接口设计文档.md)
- [核心算法设计文档](../resource/04-核心算法设计文档.md)
- [部署与扩容方案](../resource/05-部署与扩容方案.md)
- [性能优化指南](../resource/06-性能优化指南.md)

## 性能指标

| 指标 | 目标值 |
|------|--------|
| 位置上报 TPS | 50,000 |
| 告警延迟 | < 3 秒 (P99) |
| 系统可用性 | 99.9% |

## 部署方案

### Docker 部署

```bash
docker build -t fence-server:1.0.0 .
docker run -d -p 8080:8080 \
  -e MYSQL_HOST=mysql \
  -e REDIS_HOST=redis \
  -e KAFKA_SERVERS=kafka:9092 \
  fence-server:1.0.0
```

### Kubernetes 部署

参考 [部署与扩容方案](../resource/05-部署与扩容方案.md) 中的 K8s 配置。

## 开发指南

### 添加新的围栏匹配策略

1. 在 `algorithm/` 目录创建新的匹配器
2. 在 `FenceMatchServiceImpl` 中集成
3. 添加单元测试

### 添加新的告警推送渠道

1. 实现 `AlertPushService` 接口
2. 在 `AlertEvent` 处理中添加推送逻辑
3. 配置推送开关

## 测试

```bash
# 单元测试
mvn test

# 集成测试
mvn verify

# 性能测试
# 使用 JMeter 或 wrk 进行压测
```

## 监控

- Actuator 端点：`/actuator/health`, `/actuator/metrics`, `/actuator/prometheus`
- 集成 Prometheus + Grafana 监控

## License

MIT License

## 联系方式

- Gitee: https://gitee.com/chenqian1995/cloud-platform-fence-server