# gwiot

**Repository Path**: hotyuo987/gwiot

## Basic Information

- **Project Name**: gwiot
- **Description**: 本项目开始原因是由于学习嵌入式班级进行过物联网系统的开发，并且发现存在重复封装及研究mqtt服务的问题，在实习后在公司iot部门，故而萌发了，通过研究和学习的思想。收集网络上相关资料，简易实现一个物联网中台系统。本系统后端使用了java+springboot+es+influxdb+emqx等技术，前端使用了vue3.x+elementui-plus+echarts+ts等技术。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 30
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 物联网中台系统 (gwiot)

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-2.7.18-blue.svg" alt="Spring Boot">
  <img src="https://img.shields.io/badge/Vue3-Element%20Plus-green.svg" alt="Vue3">
  <img src="https://img.shields.io/badge/MQTT-EMQ%20X-orange.svg" alt="MQTT">
  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
</p>

## 项目简介

gwiot 是一套基于 Spring Boot 构建的物联网中台系统，采用前后端分离架构：后端为 Spring Boot 单体应用，前端使用 Vue3 + Element Plus。系统覆盖设备接入、指标采集与存储、告警判定、地理位置检索到可视化看板的完整链路。

本项目作为毕业设计项目开源，可供物联网开发者参考企业级物联网平台的常见架构实现。

## 核心特性

### 设备管理
- 设备分页检索（按 SN、标签）
- 在线 / 离线状态（对接 EMQ X 上下线 WebHook）
- 设备标签维护与启停状态控制
- 设备指标实时视图

### 数据采集与处理
- 基于 MQTT（Eclipse Paho）接入设备报文
- 按指标主题解析 JSON，写入 InfluxDB 时序库
- 设备元数据、告警状态、地理坐标写入 Elasticsearch
- 共享订阅 `$queue/{subject}`，支持多实例消费

### 告警系统
- 按指标配置阈值、运算符、告警级别与沉默周期
- 实时阈值比对并记录告警日志
- 支持告警 WebHook 透传与 MQTT 告警主题推送

### 可视化报表
- 首页设备数量、告警数量与状态分布统计
- 告警趋势、TOP10 告警设备
- 自定义看板（指标趋势 / 累计）
- 基于 Elasticsearch Geo 查询的附近设备检索

### 安全认证
- Spring Security + JWT（Bearer Token）
- Redis 存储登录会话
- `/login`、`/device/clientAction`、`/actuator/**` 免鉴权

## 技术架构

### 后端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Spring Boot | 2.7.18 | 应用框架 |
| Spring Security | 2.7.x | 认证鉴权 |
| MyBatis Plus | 3.3.1 | ORM 持久层 |
| MySQL | 8.0 | 业务元数据（用户、指标、告警、看板、GPS 配置） |
| InfluxDB | 1.8 | 时序指标与告警日志 |
| Elasticsearch | 7.7.1 | 设备检索与地理位置 |
| Redis | 6.x | Token / 缓存 / 告警沉默周期 |
| Eclipse Paho MQTT | 1.2.5 | MQTT 客户端 |
| EMQ X | 4.1.0 | MQTT Broker |
| JJWT | 0.9.1 | JWT 签发与解析 |

### 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue | 3.x | 前端框架 |
| Element Plus | 1.2.x | UI 组件库 |
| TypeScript | 4.1.5 | 类型安全 |
| Vuex | 4.x | 状态管理 |
| Vue Router | 4.x | 路由管理 |
| Axios | 0.24.0 | HTTP 客户端 |
| ECharts | 5.3.2 | 图表可视化 |
| Vue CLI | 4.5 | 工程构建 |

### 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                        前端展示层                            │
│           Vue3 + Element Plus + ECharts + Vuex              │
├─────────────────────────────────────────────────────────────┤
│                        API 层                                │
│         Spring Boot RESTful API + JWT + Security            │
├───────────────┬───────────────┬───────────────┬─────────────┤
│   设备管理     │   指标采集     │   告警系统     │   报表看板   │
│ DeviceService │ QuotaService  │ AlarmService  │Report/Board │
├───────────────┴───────────────┴───────────────┴─────────────┤
│                     消息处理层 (MQTT)                        │
│              EmqClient + EmqMsgProcess + NoticeService       │
├─────────────────────────────────────────────────────────────┤
│                     数据持久层                               │
│     MySQL  │  InfluxDB 1.x  │  Elasticsearch  │  Redis       │
└─────────────────────────────────────────────────────────────┘
```

## 项目结构

```
gwiot/
├── gwiot-backend/                 # 后端 Spring Boot 项目
│   └── src/main/java/com/lhg/
│       ├── GwIoTApplication.java  # 启动类
│       ├── config/                # EMQ、WebHook、Redis 缓存等配置
│       ├── constant/              # 常量定义
│       ├── controller/            # REST 控制器
│       ├── exception/             # 业务 / 用户异常
│       ├── framework/             # 框架核心
│       │   ├── emq/               # MQTT 客户端与报文处理
│       │   ├── es/                # Elasticsearch 仓储
│       │   ├── influx/            # InfluxDB 仓储
│       │   ├── security/          # JWT 过滤器与登出处理
│       │   ├── config/            # Security、CORS
│       │   └── core/              # 运行时监控相关
│       ├── mapper/                # MyBatis Mapper
│       ├── pojo/                  # dto / entity / model / vo
│       ├── service/               # 业务服务
│       ├── utils/                 # 工具类
│       └── web/                   # 登录、Token、全局异常
├── gwiot-ui/                      # 前端 Vue3 项目
│   └── src/
│       ├── api/                   # 接口封装
│       ├── assets/                # 静态资源
│       ├── components/            # 公共组件
│       ├── layout/                # 布局与侧边栏
│       ├── router/                # 路由
│       ├── store/                 # Vuex
│       ├── utils/                 # 请求封装、鉴权工具
│       └── views/                 # 页面
│           ├── index.vue          # 首页看板
│           ├── deviceMetrics/     # 设备指标
│           ├── deviceManage/      # 设备管理
│           ├── metricManage/      # 指标管理
│           ├── alarmManage/       # 告警管理
│           └── alarmLog/          # 告警日志
├── docs/
│   ├── images/                    # 效果截图
│   ├── docker-compose.yaml        # 中间件编排
│   └── init.sql                   # MySQL 初始化脚本
├── pom.xml                        # Maven 父工程
└── LICENSE                        # MIT
```

## 快速开始

### 环境要求

**后端**
- JDK 1.8+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.x+
- InfluxDB 1.8
- Elasticsearch 7.7.x
- EMQ X Broker 4.x

**前端**
- Node.js 14+ / 16.x（推荐）
- npm 或 yarn

### 1. 启动中间件（推荐）

```bash
cd docs
docker-compose up -d
```

`docker-compose.yaml` 将拉起 MySQL、Redis、EMQ X、Elasticsearch、InfluxDB。其中 EMQ X MQTT 端口映射为宿主机 `11883`（容器内 `1883`），与后端默认配置一致。

> 注意：编排仅包含基础设施，不包含后端 / 前端应用本身。MySQL、Redis 等数据卷路径为 Linux 示例路径，Windows 本地部署时请按实际情况修改 `volumes`。

### 2. 初始化数据库

1. 创建数据库（与配置文件一致，默认库名 `ykk`）：

```sql
CREATE DATABASE ykk DEFAULT CHARACTER SET utf8mb4;
```

2. 执行 `docs/init.sql` 建表并写入默认管理员。

默认账号：

| 用户名 | 密码说明 |
|--------|----------|
| `admin` | 密码为 BCrypt 加密存储于 `t_user`，初始化脚本中已写入默认哈希；如无法登录，请用 BCrypt 重新生成后更新该表 |

创建 InfluxDB 数据库（与 `spring.influx.db` 一致，默认 `ykk`）：

```bash
# 进入 InfluxDB 容器或客户端后执行
CREATE DATABASE ykk;
```

### 3. 后端配置

编辑 `gwiot-backend/src/main/resources/application.yml`：

```yaml
spring:
  influx:
    db: ykk
    url: http://127.0.0.1:8086
    user: root
    password: root
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/ykk?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
  redis:
    host: 127.0.0.1
    port: 6379
    password:

server:
  port: 9093

token:
  header: Authorization
  secret: abcdefghijklmnopqrstuvwxyz
  expireTime: 30   # 分钟

emq:
  mqttServerUrl: tcp://127.0.0.1:11883

# 可选：设备上下线 / GPS 透传 WebHook
# webhook:
#   online: http://your-server/online
#   gps: http://your-server/gps
```

Elasticsearch 使用 Spring Boot 默认客户端，默认连接 `localhost:9200`。若需自定义，可增加：

```yaml
spring:
  elasticsearch:
    rest:
      uris: http://127.0.0.1:9200
```

### 4. 启动后端

在项目根目录或模块目录执行：

```bash
cd gwiot-backend
mvn spring-boot:run
```

或先从根工程安装：

```bash
mvn clean install
cd gwiot-backend
mvn spring-boot:run
```

服务默认监听：`http://localhost:9093`

### 5. 启动前端

```bash
cd gwiot-ui
npm install
# 或 yarn
npm run serve
```

开发服务器默认端口 `8001`，通过 `/dev-api` 代理到 `http://localhost:9093`（见 `vue.config.js` 与 `.env.development`）。

浏览器访问：`http://localhost:8001`

### 6. EMQ X 上下线回调（可选）

将 EMQ X WebHook 指向后端：

```
POST http://your-host:9093/device/clientAction
```

请求体需包含 `clientid`、`action`（`client_connected` / `client_disconnected`），用于同步设备在线状态并触发上下线透传。

## 页面功能

| 路由 | 说明 |
|------|------|
| `/login` | 登录 |
| `/index` | 首页：监控数据、状态分布、告警趋势、设备分布 |
| `/deviceMetrics` | 设备指标列表与详情 |
| `/deviceManage` | 设备管理（标签、状态等） |
| `/metricManage` | 指标（配额）配置 |
| `/alarmManage` | 告警规则配置 |
| `/alarmLog` | 告警历史日志 |

## API 接口概览

除特别说明外，接口需在 Header 携带：`Authorization: Bearer <token>`。

### 认证

| 接口 | 方法 | 鉴权 | 描述 |
|------|------|------|------|
| `/login` | POST | 匿名 | 登录，返回 JWT |
| `/logout` | POST | 已登录 | 退出登录 |

### 设备管理 `/device`

| 接口 | 方法 | 描述 |
|------|------|------|
| `/device` | GET | 分页查询设备（`page` / `pageSize` / `sn` / `tag`） |
| `/device/deviceQuota` | GET | 分页查询设备指标视图 |
| `/device/status` | PUT | 更新设备启停状态 |
| `/device/tags` | PUT | 更新设备标签 |
| `/device/clientAction` | POST | EMQ 上下线回调（匿名） |

### 指标管理 `/quota`

| 接口 | 方法 | 描述 |
|------|------|------|
| `/quota` | POST | 创建指标 |
| `/quota` | GET | 分页查询指标 |
| `/quota` | PUT | 更新指标 |
| `/quota/numberQuota` | GET | 查询数值型指标 |
| `/quota/{id}` | DELETE | 删除指标 |

### 告警管理 `/alarm`

| 接口 | 方法 | 描述 |
|------|------|------|
| `/alarm` | POST | 创建告警规则 |
| `/alarm` | GET | 分页查询告警规则 |
| `/alarm` | PUT | 更新告警规则 |
| `/alarm/{id}` | DELETE | 删除告警规则 |
| `/alarm/log` | GET | 查询告警日志 |

### 看板管理 `/board`

| 接口 | 方法 | 描述 |
|------|------|------|
| `/board` | POST | 新建看板 |
| `/board` | GET | 查询非系统看板 |
| `/board/systemBoard` | GET | 查询系统看板 |
| `/board` | PUT | 更新看板 |
| `/board/status` | PUT | 设置看板显示 / 隐藏 |
| `/board/{id}` | DELETE | 删除看板 |

### 报表统计 `/report`

| 接口 | 方法 | 描述 |
|------|------|------|
| `/report/statusCollect` | GET | 设备状态分布 |
| `/report/monitor` | GET | 设备总数 / 告警数监控 |
| `/report/trend/{startTime}/{endTime}/{type}` | GET | 告警趋势 |
| `/report/top10Alarm/{startTime}/{endTime}` | GET | TOP10 告警 |
| `/report/devices` | GET | 按指标查设备列表 |
| `/report/preview` | POST | 报表预览 |
| `/report/boardData/{id}/{start}/{end}/{type}` | GET | 看板数据 |

### 位置服务 `/gps`

| 接口 | 方法 | 描述 |
|------|------|------|
| `/gps` | GET | 获取 GPS 解析配置 |
| `/gps` | PUT | 更新 GPS 解析配置 |
| `/gps/deviceList/{lat}/{lon}/{distance}` | GET | 附近设备搜索 |

## 核心流程

### 设备数据接入

```
设备发布 MQTT 报文
  → EmqClient 订阅 $queue/{subject}
  → EmqMsgProcess.messageArrived
  → QuotaService 解析指标
  → AlarmService 阈值判定
  → DeviceService 更新 ES 设备信息
  → QuotaService 写入 InfluxDB
  → NoticeService WebHook / MQTT 告警透传
  →（可选）GpsService 解析坐标并写入 ES
```

### 告警触发

```
指标解析完成
  → 运算符 + 阈值比对
  → 命中后写入告警字段 / 日志
  → Redis 控制沉默周期
  → WebHook HTTP 回调 / MQTT 告警主题推送
```

### 指标报文约定（示例）

在「指标管理」中配置主题、设备识别字段、指标值字段后，设备向该主题发布 JSON，例如：

```json
{
  "sn": "100001",
  "temp": 28
}
```

其中 `sn`、`temp` 需与指标配置的 `sn_key`、`value_key` 一致。

> 后端提供可选模拟类 `com.lhg.framework.emq.Mock`（默认注释掉 `@Component`），开启后可按已配置指标每 10 秒向 MQTT 注入模拟数据。

## 效果展示

![设备管理](./docs/images/img.png)
![数据监控](./docs/images/img_1.png)
![告警管理](./docs/images/img_2.png)
![地理分布](./docs/images/img_3.png)

## 项目初衷

本项目作为毕业设计作品，旨在将物联网平台的核心技术进行整合实践，实现从设备接入到数据可视化展示的完整链路。

> **声明**：本项目主要用于学习参考。商业使用请自行评估合规与稳定性；默认配置中的口令、密钥请务必在部署前更换。

## License

本项目采用 [MIT License](./LICENSE)。