# 云物联IOT平台

**Repository Path**: coding2me/cloud-iot-platform

## Basic Information

- **Project Name**: 云物联IOT平台
- **Description**: 一款轻量、高性能、易扩展的私有化部署物联网平台，专为中小微企业 / 开发者打造，支持多类型设备接入、数据采集 / 存储 / 分析、设备远程管控、告警通知等核心能力，适配工业传感器、农业物联网设备、园区智能硬件等多场景设备接入需求，开箱即用且支持二次开发。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 云物联IoT 系统架构说明书

## 版本信息
- 文档版本: 2.0
- 更新时间: 2026-03-19

---

## 1. 系统概述

### 1.1 项目简介

IoT Platform 是一款面向工业场景的物联网设备管理平台，提供设备接入、数据采集、实时监控、告警管理、规则引擎、数据可视化等核心功能。系统采用前后端分离架构，支持百万级设备接入，具备高可用、高可扩展特性。

### 1.2 设计目标

| 目标 | 描述 |
|------|------|
| 高可用 | 支持集群部署，无单点故障 |
| 高性能 | 支持百万级设备接入，毫秒级响应 |
| 可扩展 | 模块化设计，支持功能扩展 |
| 安全性 | 完整的认证授权机制，数据加密传输 |
| 易用性 | 友好的用户界面，简化运维操作 |

---

## 2. 技术架构

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              用户层 (Users)                                  │
│    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│    │   Web UI    │  │  移动端 APP │  │  第三方系统  │  │  设备终端   │     │
│    │   Vue 3     │  │   React    │  │  Open API   │  │   MQTT     │     │
│    └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           网关层 (Gateway)                                  │
│    ┌─────────────────────────────────────────────────────────────────┐     │
│    │                     Nginx / Spring Gateway                        │     │
│    │                 (负载均衡、SSL终结、路由分发)                         │     │
│    └─────────────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                     ┌────────────────┴────────────────┐
                     ▼                                 ▼
┌───────────────────────────────┐   ┌───────────────────────────────────────┐
│        前端服务 (Frontend)      │   │         后端服务 (Backend)             │
│   ┌─────────────────────────┐ │   │   ┌─────────────────────────────────┐   │
│   │     Vue 3.4 + TypeScript│ │   │   │    Spring Boot 3.3             │   │
│   │   Element Plus + ECharts│ │   │   │      MyBatis-Plus 3.5         │   │
│   │       Pinia 状态管理      │ │   │   │    Spring Security + JWT       │   │
│   │         Vite 5.2        │ │   │   │    Spring Integration MQTT     │   │
│   └─────────────────────────┘ │   │   └─────────────────────────────────┘   │
│         Port: 5173/80         │   │            Port: 8080                   │
└───────────────────────────────┘   └───────────────────────────────────────┘
                                          │
                     ┌────────────────────┼────────────────────┐
                     ▼                    ▼                    ▼
           ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
           │   消息中间件层    │ │    数据存储层     │ │    缓存层       │
           │   (MQTT Broker) │ │  (PostgreSQL)   │ │    (Redis)      │
           │     EMQX 5.x    │ │   + TimescaleDB │ │    Redis 7.x    │
           │   Port: 1883    │ │   Port: 5432    │ │   Port: 6379   │
           └─────────────────┘ └─────────────────┘ └─────────────────┘
```

### 2.2 技术栈选型

#### 后端技术栈

| 组件 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 基础框架 | Spring Boot | 3.3.x | 核心框架 |
| 数据库访问 | MyBatis-Plus | 3.5.x | ORM框架 |
| 数据库 | PostgreSQL | 16 | 关系型数据库 |
| 时序数据 | TimescaleDB | 2.x | 时序数据库扩展 |
| 消息队列 | EMQX | 5.x | MQTT Broker |
| 缓存 | Redis | 7.x | 缓存和会话存储 |
| 安全 | Spring Security + JWT | - | 认证授权 |
| MQTT集成 | Spring Integration | - | MQTT消息处理 |
| 构建工具 | Maven | 3.9 | 项目构建 |

#### 前端技术栈

| 组件 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 框架 | Vue | 3.4 | 前端框架 |
| 语言 | TypeScript | 5.4 | 类型安全 |
| UI库 | Element Plus | 2.7 | UI组件库 |
| 图表 | ECharts | 5.5 | 数据可视化 |
| 状态管理 | Pinia | 2.1 | 状态管理 |
| 路由 | Vue Router | 4.3 | 前端路由 |
| 构建工具 | Vite | 5.2 | 快速构建 |
| HTTP客户端 | Axios | 1.6 | HTTP请求 |

### 2.3 核心架构模式

#### 分层架构

```
┌──────────────────────────────────────────────────────┐
│              Controller Layer                        │
│         (REST API, 参数校验, 路由分发)                │
├──────────────────────────────────────────────────────┤
│               Service Layer                          │
│          (业务逻辑, 事务管理, 缓存处理)                │
├──────────────────────────────────────────────────────┤
│             Repository Layer                         │
│            (数据访问, SQL构建, 批量操作)               │
├──────────────────────────────────────────────────────┤
│               Cache Layer                            │
│        (Redis缓存, 会话管理, 分布式锁)                 │
├──────────────────────────────────────────────────────┤
│                Data Layer                            │
│       (PostgreSQL, Redis, MQTT, TimescaleDB)        │
└──────────────────────────────────────────────────────┘
```

#### 请求处理流程

```
设备/客户端请求
      │
      ▼
┌─────────────┐
│  Nginx      │ 负载均衡
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Backend    │ JWT验证
│  :8080      │ 限流控制
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Controller  │ 参数校验
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Service    │ 业务逻辑
│             │ 缓存处理
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Repository  │ 数据访问
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ PostgreSQL  │ 持久化存储
│ Redis       │ 缓存
│ EMQX        │ MQTT消息
└─────────────┘
```

---

## 3. 模块设计

### 3.1 模块划分

```
com.iot
├── config                  # 系统配置
│   ├── SecurityConfig      # 安全配置 (JWT, CORS)
│   ├── RedisConfig         # Redis配置 (序列化, 连接池)
│   ├── MqttConfig          # MQTT配置
│   ├── MqttIntegrationConfig # MQTT入站出站配置
│   ├── MyBatisPlusConfig   # MyBatis配置
│   └── WebSocketConfig     # WebSocket配置
│
├── controller              # 控制器层 (21个Controller)
│   ├── DeviceController            # 设备管理 (CRUD/状态/命令/遥测)
│   ├── ProductController           # 产品管理
│   ├── DeviceTemplateController    # 物模型管理 (属性/服务/事件)
│   ├── DeviceGroupController       # 设备分组
│   ├── ShadowController           # 设备影子
│   ├── RuleController             # 规则管理
│   ├── AlarmController            # 告警管理
│   ├── AlarmRuleController        # 告警规则
│   ├── OtaController              # OTA升级
│   ├── DashboardController        # 仪表盘
│   ├── NotificationController     # 通知管理
│   ├── UserController             # 用户管理
│   ├── AuthController             # 认证登录
│   ├── TenantController           # 租户管理
│   ├── SimulatorController        # 设备模拟器
│   ├── DeviceDebugController      # 设备调试
│   ├── WebSocketController        # WebSocket
│   ├── OpenApiController          # Open API
│   ├── ImportExportController     # 导入导出
│   ├── DeviceAuthController       # 设备认证
│   └── DeviceStatusController     # 设备状态
│
├── service                 # 服务层
│   ├── impl
│   │   ├── DeviceServiceImpl              # 设备服务
│   │   ├── DeviceStatusServiceImpl        # 设备状态服务
│   │   ├── DeviceSessionServiceImpl       # 设备会话服务 (Redis)
│   │   ├── TelemetryServiceImpl           # 时序数据服务 (批量入库)
│   │   ├── ShadowServiceImpl              # 设备影子服务 (Redis)
│   │   ├── AlarmServiceImpl               # 告警服务
│   │   ├── AlarmRuleServiceImpl           # 告警规则服务
│   │   ├── RuleEngineServiceImpl          # 规则引擎服务
│   │   ├── DashboardServiceImpl           # 仪表盘服务
│   │   ├── NotificationServiceImpl        # 通知服务
│   │   ├── DeviceSimulatorServiceImpl     # 设备模拟服务
│   │   ├── DeviceDebugServiceImpl         # 设备调试服务
│   │   ├── WebSocketServiceImpl           # WebSocket服务
│   │   ├── MqttGatewayServiceImpl         # MQTT网关服务
│   │   ├── TelemetryValidationServiceImpl # 数据验证服务
│   │   └── ...
│   └── interface (Service接口)
│
├── repository              # 数据访问层 (30个Mapper)
│   ├── DeviceMapper
│   ├── ProductMapper
│   ├── DeviceDataMapper   # 批量入库
│   ├── AlarmMapper
│   ├── RuleMapper
│   ├── DashboardMapper
│   └── ...
│
├── entity                 # 实体层 (37个Entity)
│   ├── Device.java
│   ├── Product.java
│   ├── DeviceData.java    # 时序数据实体
│   ├── DeviceTemplate.java
│   ├── Alarm.java
│   ├── AlarmRule.java
│   ├── Rule.java
│   ├── Dashboard.java
│   ├── User.java
│   ├── Tenant.java
│   └── ...
│
├── dto                    # 数据传输对象
│   ├── PropertyDTO.java
│   ├── ServiceDTO.java
│   ├── EventDTO.java
│   ├── DeviceStatusVO.java
│   └── ...
│
├── mqtt                   # MQTT相关
│   ├── MqttTopic.java           # Topic定义
│   ├── MqttPayload.java         # 消息载体
│   ├── MqttClientInfo.java      # 客户端信息
│   ├── DeviceMessage.java       # 设备消息
│   └── MqttGatewayService.java  # MQTT网关接口
│
├── websocket               # WebSocket相关
│   ├── IoTWebSocketHandler.java
│   └── WebSocketMessage.java
│
└── common                 # 通用组件
    ├── R.java                   # 统一响应
    ├── PageResult.java          # 分页结果
    ├── ResultCode.java          # 响应码
    ├── BusinessException.java   # 业务异常
    └── GlobalExceptionHandler.java
```

### 3.2 核心模块说明

#### 3.2.1 设备管理模块

**职责**：实现设备的全生命周期管理

**功能清单**：
- 设备注册与认证 (密钥/证书)
- 设备信息管理 (CRUD)
- 设备状态监控 (在线/离线)
- 设备命令下发 (MQTT)
- 设备分组管理
- 设备影子管理

**核心服务**：
```java
public interface DeviceService {
    Device saveDevice(Device device);
    Device getByDeviceId(String deviceId);
    PageResult<Device> listDevices(...);
    void deleteDevice(Long id);
}
```

#### 3.2.2 时序数据模块

**职责**：采集、存储、查询设备时序数据

**技术选型**：TimescaleDB 超表 + 批量入库

**核心特性**：
- 批量插入优化 (10-50x性能提升)
- 自动数据压缩 (1天后压缩)
- 连续聚合视图 (按小时/天)
- 支持实时查询和历史分析

```java
public interface TelemetryService {
    void saveDeviceData(String deviceId, Map<String, Object> data, Long timestamp);
    void saveDeviceEvent(String deviceId, DeviceMessage.Event event);
    Map<String, Object> queryDeviceLatestData(String deviceId);
    Map<String, Object> queryTelemetryHistory(String deviceId, String property, Long startTime, Long endTime, String aggregation);
}
```

#### 3.2.3 设备会话模块 (Redis)

**职责**：管理设备MQTT连接会话

**存储设计**：
| Key | 类型 | 说明 | TTL |
|-----|------|------|-----|
| `device:session:client:{clientId}` | String | 客户端→设备 | 24h |
| `device:session:device:{deviceId}` | Set | 设备→客户端 | 24h |
| `device:status:{deviceId}` | Hash | 设备状态 | 180s |
| `device:online:ids` | Set | 在线设备ID | - |

**集群优势**：
- 会话共享 (多实例共享)
- 状态一致 (实时同步)
- 自动过期 (Redis TTL)

#### 3.2.4 告警管理模块

**职责**：设备告警的检测、通知、处理

**功能清单**：
- 告警规则配置 (阈值/条件)
- 实时告警检测 (数据触发/设备状态)
- 多渠道通知 (邮件/WebSocket/Webhook/钉钉)
- 告警记录与查询
- 告警处理与关闭

**告警级别**：
| 级别 | 颜色 | 说明 |
|------|------|------|
| CRITICAL | 红色 | 严重告警，需立即处理 |
| ERROR | 橙色 | 错误告警 |
| WARNING | 黄色 | 警告，需关注 |
| INFO | 蓝色 | 提示信息 |

#### 3.2.5 规则引擎模块

**职责**：基于设备数据触发自定义业务逻辑

**条件语法**：
```
temperature >= 30          # 大于等于
humidity <= 80           # 小于等于
status == "error"       # 等于判断
voltage > 12.0          # 大于
```

**动作类型**：
| 类型 | 说明 | 实现状态 |
|------|------|----------|
| MQTT | 发送MQTT消息到指定主题 | ✅ |
| HTTP | 发起HTTP请求 | ⚠️ 部分 |
| ALARM | 触发告警 | ✅ |
| DATA_FORWARD | 数据转发到第三方 | ⚠️ 部分 |

#### 3.2.6 设备影子模块 (Redis)

**职责**：存储设备的期望状态和上报状态

**数据结构** (Hash):
```
Key: shadow:{deviceId}
Fields:
  - reported: {temperature: 25.5, humidity: 60}
  - desired: {temperature: 26, mode: "cooling"}
  - timestamp: 1699999999999
```

**同步机制**：
- 设备上报数据 → 更新 reported
- 应用下发期望 → 更新 desired
- 设备连接时 → 同步 shadow

#### 3.2.7 OTA升级模块

**职责**：设备固件远程升级

**功能清单**：
- 固件版本管理
- 单设备升级
- 批量升级任务
- 升级进度跟踪

**升级状态**：
```
PENDING → DOWNLOADING → INSTALLING → SUCCESS/FAILED
```

#### 3.2.8 仪表盘模块

**职责**：数据可视化配置与展示

**支持的图表组件** (10种):
| 组件 | 说明 |
|------|------|
| 折线图 (LineChart) | 展示数据趋势变化 |
| 柱状图 (BarChart) | 展示分类数据对比 |
| 饼图 (PieChart) | 展示数据占比 |
| 仪表盘 (GaugeChart) | 展示单个指标数值 |
| 面积图 (AreaChart) | 展示数据面积变化 |
| 散点图 (ScatterChart) | 展示数据分布 |
| 热力图 (HeatmapChart) | 展示数据密度 |
| 数字卡片 (NumberCard) | 展示单个数值 |
| 状态卡片 (StatusCard) | 展示设备状态 |
| 数据表格 (DataTable) | 展示列表数据 |

---

## 4. 数据库设计

### 4.1 存储架构

```
┌────────────────────────────────────────────────────────────────┐
│                        PostgreSQL 16                            │
├────────────────────────────────────────────────────────────────┤
│  ┌──────────────────────┐  ┌─────────────────────────────────┐ │
│  │    普通表            │  │      TimescaleDB 超表           │ │
│  │  (OLTP操作)          │  │    (时序数据, 自动分区)           │ │
│  ├──────────────────────┤  ├─────────────────────────────────┤ │
│  │  it_sys_user         │  │  it_device_data                 │ │
│  │  it_sys_role         │  │  ├─ 遥测数据 (telemetry)         │ │
│  │  it_product          │  │  └─ 事件数据 (event)             │ │
│  │  it_device          │  │                                 │ │
│  │  it_device_group     │  │  连续聚合视图:                   │ │
│  │  it_device_template  │  │  ├─ it_device_data_hourly       │ │
│  │  it_model_property   │  │  └─ it_device_data_daily        │ │
│  │  it_rule             │  │                                 │ │
│  │  it_alarm            │  │  压缩策略: 1天后自动压缩           │ │
│  │  it_alarm_rule       │  │                                 │ │
│  │  it_dashboard        │  │                                 │ │
│  │  ...                 │  │                                 │ │
│  └──────────────────────┘  └─────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────┤
│                           Redis 7.x                             │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  会话存储: 设备会话、设备状态、在线设备                    │   │
│  │  缓存存储: 设备影子、Token、热点数据                      │   │
│  │  分布式锁: 设备命令锁、OTA升级锁                          │   │
│  └─────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────┘
```

### 4.2 TimescaleDB特性

#### 自动分区
- 按时间自动分区
- 支持按设备ID分区压缩

#### 连续聚合
```sql
-- 小时聚合视图
CREATE MATERIALIZED VIEW it_device_data_hourly
WITH (timescaledb.continuous) AS
SELECT time_bucket('1 hour', device_time) AS bucket,
       device_id, property_key,
       COUNT(*) AS count,
       AVG(value) AS avg_value,
       MAX(value) AS max_value,
       MIN(value) AS min_value
FROM it_device_data
GROUP BY bucket, device_id, property_key;

-- 自动刷新策略
SELECT add_continuous_aggregate_policy(
    'it_device_data_hourly', 
    NULL,              -- 刷新起点
    INTERVAL '1 hour', -- 刷新间隔
    INTERVAL '1 hour'  -- 滞后窗口
);
```

#### 数据压缩
```sql
ALTER TABLE it_device_data SET (
    timescaledb.compress,
    timescaledb.compress_segmentby = 'device_id'
);
SELECT add_compression_policy('it_device_data', INTERVAL '1 day');
```

---

## 5. 接口设计

### 5.1 接口规范

#### 请求格式
```
POST /api/devices
Content-Type: application/json
Authorization: Bearer <token>

{
  "deviceId": "device001",
  "deviceName": "温度传感器01",
  "productId": "product001"
}
```

#### 响应格式
```json
{
  "code": 200,
  "message": "success",
  "data": { ... },
  "timestamp": 1699999999999
}
```

#### 统一响应码
| 响应码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

### 5.2 核心接口列表

#### 设备管理 API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/devices | 获取设备列表 |
| POST | /api/devices | 创建设备 |
| GET | /api/devices/{deviceId} | 获取设备详情 |
| PUT | /api/devices/{id} | 更新设备 |
| DELETE | /api/devices/{id} | 删除设备 |
| GET | /api/devices/{deviceId}/status | 获取设备状态 |
| GET | /api/devices/online | 获取在线设备 |
| GET | /api/devices/online/count | 获取在线数量 |
| POST | /api/devices/{deviceId}/command | 下发命令 |
| GET | /api/devices/{deviceId}/telemetry | 获取时序数据 |
| GET | /api/devices/{deviceId}/telemetry/latest | 获取最新数据 |
| GET | /api/devices/{deviceId}/telemetry/history | 获取历史数据 |
| POST | /api/devices/{deviceId}/debug | 设备调试 |
| POST | /api/devices/{deviceId}/simulate | 模拟数据 |
| POST | /api/devices/{deviceId}/simulate/batch | 批量模拟 |

#### 物模型 API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/templates | 获取模板列表 |
| POST | /api/templates | 创建模板 |
| GET | /api/templates/{id} | 获取模板详情 |
| PUT | /api/templates/{id} | 更新模板 |
| DELETE | /api/templates/{id} | 删除模板 |
| GET | /api/templates/{id}/properties | 获取属性列表 |
| POST | /api/templates/{id}/properties | 添加属性 |
| PUT | /api/templates/{id}/properties/{pid} | 更新属性 |
| DELETE | /api/templates/{id}/properties/{pid} | 删除属性 |

#### 规则引擎 API
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/rules | 获取规则列表 |
| POST | /api/rules | 创建规则 |
| GET | /api/rules/{id} | 获取规则详情 |
| PUT | /api/rules/{id} | 更新规则 |
| DELETE | /api/rules/{id} | 删除规则 |
| POST | /api/rules/{id}/enable | 启用规则 |
| POST | /api/rules/{id}/disable | 禁用规则 |
| POST | /api/rules/test | 测试规则 |

---

## 6. MQTT协议设计

### 6.1 Topic 规范

#### 主题结构
```
devices/{deviceId}/upload          # 属性数据上报
devices/{deviceId}/property        # 属性变化上报
devices/{deviceId}/event          # 事件上报
devices/{deviceId}/status         # 状态上报
devices/{deviceId}/download       # 平台下发数据
devices/{deviceId}/command         # 命令下发
devices/{deviceId}/command/response # 命令响应
$shadow/get/{deviceId}           # 获取影子
$shadow/update/{deviceId}        # 更新影子
```

### 6.2 消息格式

#### 属性上报消息
```json
{
  "deviceId": "device001",
  "timestamp": 1699999999999,
  "properties": {
    "temperature": 25.5,
    "humidity": 60,
    "voltage": 3.3
  }
}
```

#### 事件上报消息
```json
{
  "deviceId": "device001",
  "timestamp": 1699999999999,
  "eventType": "warning",
  "identifier": "high_temperature",
  "params": {
    "temperature": 85,
    "threshold": 80
  }
}
```

#### 命令下发消息
```json
{
  "deviceId": "device001",
  "timestamp": 1699999999999,
  "command": {
    "commandId": "cmd-001",
    "identifier": "setTemperature",
    "params": {"value": 26},
    "timeout": 30000
  }
}
```

---

## 7. 部署架构

### 7.1 开发环境部署

```
┌─────────────────────────────────────────────────────────────┐
│                      Docker Compose                          │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────┐ │
│  │ Backend │ │Frontend │ │ EMQX    │ │Postgres │ │Redis │ │
│  │ :8080   │ │ :80     │ │ :1883   │ │ :5432   │ │:6379 │ │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └──────┘ │
└─────────────────────────────────────────────────────────────┘
```

### 7.2 生产环境集群部署

```
                          ┌─────────────┐
                          │   Nginx     │
                          │  LB/SSL     │
                          └──────┬──────┘
                                 │
           ┌─────────────────────┼─────────────────────┐
           │                     │                     │
           ▼                     ▼                     ▼
     ┌───────────┐         ┌───────────┐         ┌───────────┐
     │ Backend-1 │         │ Backend-2 │         │ Backend-3 │
     │  :8080    │         │  :8080    │         │  :8080    │
     └─────┬─────┘         └─────┬─────┘         └─────┬─────┘
           │                     │                     │
           └─────────────────────┼─────────────────────┘
                                 │
           ┌─────────────────────┼─────────────────────┐
           │                     │                     │
           ▼                     ▼                     ▼
     ┌───────────┐         ┌───────────┐         ┌───────────┐
     │ PostgreSQL│         │   Redis   │         │   EMQX    │
     │ Patroni   │◄────────►│ Sentinel  │◄────────►│ Cluster   │
     │ Cluster   │         │ Cluster   │         │           │
     └───────────┘         └───────────┘         └───────────┘
```

### 7.3 Docker Compose配置

```yaml
version: '3.8'

services:
  backend:
    build: ./backend
    ports:
      - "8080:8080"
    environment:
      - DB_HOST=postgres
      - REDIS_HOST=redis
      - MQTT_BROKER_URL=tcp://emqx:1883
    depends_on:
      - postgres
      - redis
      - emqx

  frontend:
    build: ./frontend
    ports:
      - "80:80"

  postgres:
    image: timescale/timescaledb:latest-pg16
    environment:
      - POSTGRES_PASSWORD=postgres123
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  emqx:
    image: emqx/emqx:5.3
    ports:
      - "1883:1883"
      - "8083:8083"
      - "18083:18083"

volumes:
  postgres_data:
  redis_data:
```

---

## 8. 安全设计

### 8.1 认证授权

#### JWT认证流程
```
1. 用户登录 → 验证用户名密码 → 生成JWT Token
2. 前端存储Token → 请求时携带Token
3. 后端验证Token → 解析用户信息 → 权限校验
4. Token过期 → 使用Refresh Token刷新
```

#### 设备认证
```
1. 设备使用 deviceId + secret 连接MQTT
2. EMQX验证设备凭证
3. 连接建立后开始数据传输
```

### 8.2 权限控制

| 角色 | 权限说明 |
|------|----------|
| ADMIN | 管理员，拥有所有权限 |
| USER | 普通用户，拥有查看和操作权限 |
| GUEST | 访客，仅有查看权限 |

---

## 9. 性能优化

### 9.1 时序数据优化

**批量入库**：
- 支持批量插入，10-50x性能提升
- 批量大小可配置
- 异步写入，不阻塞主流程

**数据压缩**：
- 1天后自动压缩
- 按 device_id 分区压缩
- 压缩比可达 10:1

### 9.2 缓存策略

| 数据类型 | 缓存策略 | TTL |
|---------|----------|-----|
| 设备状态 | Redis Hash | 180秒 |
| 设备影子 | Redis Hash | 1小时 |
| 用户会话 | Redis String | 24小时 |
| 设备会话 | Redis Set/Hash | 24小时 |
| 在线设备 | Redis Set | - |

### 9.3 数据库优化

- 合理使用索引
- 分页查询 (默认20条)
- 读写分离 (未来支持)
- TimescaleDB分区策略

---

## 10. 监控告警

### 10.1 监控指标

| 类别 | 指标 | 告警阈值 |
|------|------|----------|
| 系统 | CPU使用率 | >80% |
| 系统 | 内存使用率 | >85% |
| 系统 | 磁盘使用率 | >90% |
| 应用 | 接口响应时间 | >3s |
| 应用 | 错误率 | >1% |
| MQTT | 连接数 | >10000 |

### 10.2 日志规范

```
日志级别:
- ERROR: 错误日志，需处理
- WARN: 警告日志，需关注
- INFO: 信息日志，正常流程
- DEBUG: 调试日志，开发使用

日志格式:
2024-01-15 10:30:45 [http-nio-8080-exec-1] INFO  c.iot.service.DeviceService - Device created: deviceId=device001
```

---

## 11. 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2024-01 | 初始版本，包含核心功能 |
| 2.0.0 | 2026-03 | 大幅更新，TimescaleDB优化，批量入库，Redis会话管理 |

---

## 12. 附录

### 12.1 术语表

| 术语 | 说明 |
|------|------|
| IoT | 物联网 (Internet of Things) |
| MQTT | 消息队列遥测传输协议 |
| OTA | 空中下载技术 (Over-The-Air) |
| DTU | 数据传输单元 (Data Transfer Unit) |
| TimescaleDB | PostgreSQL时序数据库扩展 |
| EMQX | 开源MQTT Broker |
| Shadow | 设备影子，用于存储期望状态和上报状态 |

### 12.2 参考资料

- Spring Boot: https://spring.io/projects/spring-boot
- MyBatis-Plus: https://baomidou.com/
- EMQX: https://www.emqx.io/
- TimescaleDB: https://www.timescale.com/
- Vue.js: https://vuejs.org/
- Element Plus: https://element-plus.org/

### 🤝 支持与赞助
本项目持续开源维护，若您在实际生产、教学或二次开发中受益，可通过下方二维码进行赞助。
所有收益将用于功能迭代、问题修复与平台稳定性优化。
![输入图片说明](docs/image.png)