# iot-platform

**Repository Path**: tianmacgw/iot-platform

## Basic Information

- **Project Name**: iot-platform
- **Description**: 基于Spring Cloud Alibaba微服务架构的智慧工厂IoT平台实践。旨在探索Spring Boot+Vue全栈技术在工业场景的应用。支持MQTT/TCP/Modbus多协议设备接入、Vert.x+InfluxDB实时数据处理及AI智能问答。集成Jenkins CI/CD、K8s部署与Prometheus+Grafana监控。适合作为物联网全栈开发的学习参考。持续迭代中，欢迎Star！
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-06-10
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智慧工厂 IoT 数据平台

SmartFactory IoT Platform - 基于微服务架构的工业互联网数据平台

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-21+-green.svg)](https://adoptium.org/)
[![Vue](https://img.shields.io/badge/Vue-3.4-brightgreen.svg)](https://vuejs.org/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.15-green.svg)](https://spring.io/projects/spring-boot)
[![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2025.0.0-orange.svg)](https://spring.io/projects/spring-cloud)

## 项目简介

本项目是一个完整的智慧工厂 IoT 数据平台，实现了设备接入、数据采集、实时监控、告警管理、数据分析、AI 智能问答等核心功能。采用微服务架构，支持海量设备接入和数据实时处理。

### 核心技术栈

| 领域 | 技术选型 |
|------|----------|
| **后端框架** | Spring Cloud Alibaba 2025.0.0.0、Spring Boot 3.5.15、Nacos、Sentinel |
| **数据库** | PostgreSQL 15 + PostGIS 3.3 + pgvector、ClickHouse 23.11、Redis 7.2、InfluxDB 2.7 |
| **消息队列** | RabbitMQ 3.12 |
| **IoT 接入** | EMQX 5.8.0 (MQTT Broker) |
| **分布式事务** | Seata 2.5.0 |
| **AI 服务** | LangChain4j、pgvector、Spring AI、Ollama |
| **前端** | Vue 3.4、TypeScript、Pinia、Element Plus、Three.js、ECharts |
| **3D 可视化** | Three.js、WebGL、Bloom 后期处理 |
| **DevOps** | Docker Compose、Kubernetes (Kustomize)、Jenkins CI/CD、Prometheus、Grafana |

---

## 系统架构

![系统架构图](./assets/architecture.png)

---

## 界面预览

> 以下为平台各子系统的实际运行界面。截图文件存放于 `assets/screenshots/` 目录。

### 📋 截图索引

| 截图 | 子系统 | 展示内容 |
|------|--------|----------|
| dashboard.png | iot-admin | 首页仪表盘（统计卡片 + 设备状态趋势 + 类型分布 + 实时告警） |
| login.png | iot-admin | 登录页 |
| device-list.png | iot-admin | 设备管理（设备列表、状态管理） |
| data-detail.png | iot-admin | 数据管理（时序数据详情、ECharts 趋势分析） |
| alert-center.png | iot-admin | 告警管理（告警列表、规则配置） |
| digital-twin.png | iot-digital | Three.js 3D 数字工厂 |
| monitor-dashboard.png | iot-monitor | 监控大屏（ECharts 全局数据可视化） |

---

### 💻 iot-admin — 管理后台

<p align="center">
  <img src="./assets/screenshots/dashboard.png" alt="首页仪表盘" width="90%" />
  <br><em>首页仪表盘 — 设备总数 / 在线状态 / 告警概览 / 数据采集速率，以及设备状态趋势与类型分布</em>
</p>

<br>

<p align="center">
  <img src="./assets/screenshots/login.png" alt="登录页" width="90%" />
  <br><em>登录页</em>
</p>

<br>

<p align="center">
  <img src="./assets/screenshots/device-list.png" alt="设备列表" width="90%" />
  <br><em>设备管理 — 设备列表、在线/离线状态管理</em>
</p>

<br>

<p align="center">
  <img src="./assets/screenshots/data-detail.png" alt="数据详情" width="90%" />
  <br><em>数据管理 — 时序数据详情、ECharts 趋势分析图表</em>
</p>

<br>

<p align="center">
  <img src="./assets/screenshots/alert-center.png" alt="告警中心" width="90%" />
  <br><em>告警管理 — 实时告警列表、告警规则配置</em>
</p>

---

### 🏭 iot-digital — 3D 数字工厂

<p align="center">
  <img src="./assets/screenshots/digital-twin.png" alt="3D数字工厂" width="90%" />
  <br><em>Three.js 3D 数字工厂 — 工厂三维可视化场景</em>
</p>

---

### 📊 iot-monitor — 监控大屏

<p align="center">
  <img src="./assets/screenshots/monitor-dashboard.png" alt="监控大屏" width="90%" />
  <br><em>监控大屏 — ECharts 全局数据可视化看板</em>
</p>

---

## 快速开始

### 环境要求

- JDK 21+
- Node.js 18+
- Docker & Docker Compose（推荐 Docker Desktop）
- Maven 3.9+
- Ollama（本地 AI 推理，详见下方说明）
- 内存建议 16GB+

---

### 1. 启动中间件

```bash
# 进入 docker 目录
cd docker

# 一键启动所有中间件（PostgreSQL / Redis / Nacos / RabbitMQ / ClickHouse / InfluxDB / EMQX / Seata / Prometheus / Grafana / Jenkins）
docker compose up -d

# 查看启动状态
docker compose ps

# 等待所有服务健康检查通过（约 1-2 分钟）
```

> ⚠️ **Windows（Docker Desktop）端口绑定失败**：若 `docker compose up -d` 报 `ports are not available ... access forbidden`（常见于 Nacos 的 gRPC 端口 9848），这是 Windows 的 Hyper-V/WinNAT 预留端口区间与 Docker 主机端口冲突，**并非端口被占用**（`netstat` 查不到进程）。两种解法：
> - **临时（推荐本地自测）**：用**管理员 PowerShell** 执行 `net stop winnat` → `docker compose up -d` → `net start winnat`，Docker 趁机绑定后重启 WinNAT 即可。重启电脑后可能再次触发。
> - **永久**：将 `docker-compose.yml` 中 Nacos 端口改为 `18848:8848` / `19848:9848`，并把各模块 `spring.cloud.nacos.server-addr` 与 `docker/nacos/*.yml` 里的 `localhost:8848` 一并改为 `18848`，重新导入 Nacos 配置。

容器启动时会自动完成：
- PostgreSQL：自动执行 `sql/init.sql` 建表
- ClickHouse：自动执行 `clickhouse/init.sql` 建表
- Redis、Nacos、RabbitMQ 等：使用 docker-compose.yml 中配置的默认密码

---

### 2. 安装 Ollama 并拉取 AI 模型

AI 知识库服务（`iot-ai`）依赖本地 Ollama 提供向量化与问答能力：

```bash
# 1. 安装 Ollama（Windows / macOS / Linux 均可）
#    官网下载：https://ollama.com/download

# 2. 拉取 Embedding 模型（向量化，必装）
ollama pull bge-m3

# 3. 拉取对话模型（智能问答，必装）
ollama pull qwen2.5:1.5b

# 4. 验证模型已就绪
ollama list
```

> 💡 **模型说明**：
> - `bge-m3`：Embedding 向量化模型，将文本转为向量用于知识库检索，维度 1024
> - `qwen2.5:1.5b`：轻量级对话模型，用于 RAG 问答推理，1.5B 参数，普通笔记本即可流畅运行
>
> ⚠️ 如需切换 Embedding provider，在 Nacos 配置中心或 `application.yml` 中设置：
> ```yaml
> iot:
>   ai:
>     embedding:
>       provider: ollama           # 本地 Ollama（默认）
>       # provider: siliconflow    # 云端 Jina AI
> ```

---

### 3. 导入 Nacos 配置

中间件启动后，将 Nacos 配置文件导入配置中心：

```bash
# 仍在 docker/ 目录下
python nacos/import_configs.py
```

> ⚠️ 等待 Nacos 容器健康检查通过后再执行，否则会连接失败。

---

### 4. 启动后端服务

#### 方式一：IDEA 中运行（推荐开发用）

在 IDEA 右侧 Maven 面板中：
1. 先执行根目录 `clean` + `compile`
2. 按以下顺序启动 Spring Boot 主类（右键 Run）：
   - `iot-gateway` → `iot-user` → `iot-device` → `iot-data` → `iot-alert` → `iot-ai` → `iot-tenant` → `iot-warehouse`

#### 方式二：命令行启动

```bash
# 回到项目根目录
cd ..

# 编译打包（跳过测试）
mvn clean package -DskipTests

# 逐一启动
java -jar iot-gateway/target/iot-gateway-1.0.0-SNAPSHOT.jar &
java -jar iot-user/target/iot-user-1.0.0-SNAPSHOT.jar &
# ... 其他服务依次启动
```

#### 方式三：启动脚本

```bash
# Windows PowerShell
powershell -File scripts/start-backend.ps1

# Linux / Mac
bash scripts/start-backend.sh
```

---

### 5. 启动前端

```bash
# 管理后台（核心）
cd iot-admin
npm install
npm run dev        # → http://localhost:5175

# 3D 数字工厂（可选）
cd ../iot-digital
npm install
npm run dev        # → http://localhost:5173

# 监控大屏（可选）
cd ../iot-monitor
npm install
npm run dev        # → http://localhost:5174
```

---

### 6. 访问地址

| 服务 | 地址 | 账号/密码                       |
|------|------|-----------------------------|
| 管理后台（系统管理员） | http://localhost:5175 | `super_admin` / `admin123`，`admin` / `admin123` |
| 3D 数字工厂 | http://localhost:5173/digital-factory | -                           |
| 监控大屏 | http://localhost:5174 | -                           |
| Nacos 控制台 | http://localhost:8081 | `nacos` / `nacos`           |
| EMQX 控制台 | http://localhost:18083 | `admin` / `public`          |
| Grafana | http://localhost:3000 | `admin` / `admin123`        |
| Prometheus | http://localhost:9090 | -                           |
| Jenkins | http://localhost:8080 | 首次启动查看初始密码                  |

### 7. 使用模拟数据（模拟设备上报）

项目内置两个 Python 脚本，可在不接真实硬件的情况下模拟一台 Modbus 温湿度传感器并自动上报数据，用于快速体验「设备接入 → 数据采集 → 实时监控」全链路。

> 💡 前置条件：请先完成上方第 1~5 步（启动中间件、导入 Nacos 配置、启动后端与前端），确保 **TCP 设备网关** 已监听（默认端口 `8889`）。

#### 7.1 安装 Python 依赖

```bash
pip install pymodbus flask
```

#### 7.2 启动 Modbus 传感器模拟器

```bash
# 项目根目录执行（自动模拟模式：温度按正弦波 + 噪声变化）
python scripts/modbus_slave_sim.py

# 可选：手动模式（仅通过 Web UI 改值）
python scripts/modbus_slave_sim.py --mode manual

# 可选：自定义端口
python scripts/modbus_slave_sim.py --port 5502 --web-port 5503
```

> 💡 **运行时切换模式（推荐）**：Web 控制台（`http://localhost:5503`）的「当前数据」卡片新增了 **自动/手动 切换按钮**，可在模拟器运行期间实时切换自动模拟与手动模式，无需重启进程。`--mode` 启动参数仍然保留，作为进程启动时的初始模式选项。

- Modbus TCP 端口：默认 `5502`
- Web 控制台：`http://localhost:5503`，可手动修改温度 / 湿度值
- 寄存器定义：40001 = 温度 × 10、40002 = 湿度 × 10、40003 = 设备状态（0 正常 / 1 告警）

#### 7.3 启动网桥，转发到 IoT 平台

```bash
# 项目根目录执行（将 Modbus 数据转发到 TCP 设备网关）
python scripts/modbus_bridge.py

# 默认参数（一般无需修改）
python scripts/modbus_bridge.py \
  --modbus-host localhost --modbus-port 5502 \
  --iot-host localhost --iot-port 8889 \
  --device-code MODBUS-TH-001 --interval 10
```

- 默认设备编码 `MODBUS-TH-001`：需确保该设备已在平台注册（或平台已开启自动注册），否则数据会被 TCP 网关拒绝。
- 数据协议格式：`设备编码|时间戳(ms)|temperature:值|humidity:值`

> 提示：模拟器与网桥为独立进程，运行时均占用前台终端；演示完毕按 `Ctrl+C` 退出即可。

#### 7.4 查看效果

进入管理后台 → 设备管理 → 实时数据，即可看到温湿度实时刷新；当温度 > 35°C 或湿度 > 85%RH 时，平台会触发告警。

---

## 项目结构

```
iot-platform/
├── iot-gateway/                 # API 网关（Spring Cloud Gateway）
├── iot-user/                    # 用户服务（用户/角色/菜单/多租户）
├── iot-device/                  # 设备服务（设备注册/定位/分组）
├── iot-data/                    # 时序数据服务（数据上报/查询/聚合）
├── iot-alert/                   # 告警服务（规则配置/评估/处理）
├── iot-ai/                      # AI 知识库服务（RAG 问答/向量检索）
├── iot-tenant/                  # 多租户服务（租户管理/套餐/计费）
├── iot-warehouse/               # OLAP 数据仓库（ClickHouse 分析报表）
├── iot-admin/                   # Vue3 管理后台（Element Plus）
├── iot-digital/                 # Three.js 3D 数字工厂（可选）
├── iot-monitor/                 # ECharts 监控大屏（可选）
├── iot-python/                  # Python AI 服务（预留，当前未集成）
├── iot-common/                  # 公共模块
│   ├── common-core/             # 统一返回/异常/工具类
│   ├── common-db/               # MyBatis-Plus 公共处理
│   ├── common-redis/            # Redisson + Redis 封装
│   ├── common-mq/               # RabbitMQ 消息封装
│   ├── common-security/         # JWT 鉴权/多租户安全
│   ├── common-ai/               # AI 通用能力封装
│   ├── common-logging/          # 日志处理
│   ├── common-trace/            # 链路追踪
│   └── common-mongodb/          # MongoDB 封装
├── docker/                      # Docker Compose 中间件部署
│   ├── docker-compose.yml       # 一键启动所有中间件
│   ├── nacos/                   # Nacos 配置 + 导入脚本
│   ├── postgres/                # PostgreSQL 自定义镜像
│   ├── seata/                   # Seata 配置
│   └── prometheus.yml           # 监控采集配置
├── k8s/                         # Kubernetes 部署（Kustomize）
├── sql/                         # PostgreSQL 建表脚本（自动执行）
├── clickhouse/                  # ClickHouse 建表脚本（自动执行）
├── scripts/                     # 后端微服务启动脚本
├── Jenkinsfile                  # CI/CD 流水线
└── pom.xml                      # 父 POM（统一依赖管理）
```

---

## 核心功能

### 设备管理 (iot-device)

- 设备注册/注销
- 设备在线/离线状态
- 设备位置管理（PostGIS 空间查询）
- 附近设备查询（ST_DWithin）
- 设备分组管理

### 时序数据 (iot-data)

- 数据上报 API（Redis 缓存 + 异步写入）
- 历史数据查询
- 聚合查询（avg/max/min/sum）
- 批量数据写入

### 告警管理 (iot-alert)

- 告警规则配置（阈值/持续/变化率）
- 定时规则评估
- 告警记录/处理/解决
- 告警统计

### AI 知识库 (iot-ai)

- RAG 检索增强生成（Ollama 本地推理）
- Embedding 向量化（默认 `bge-m3`，Ollama 本地运行）
- 对话模型（默认 `qwen2.5:1.5b`，Ollama 本地运行）
- pgvector 向量存储（PostgreSQL）
- 多知识库支持
- AI Agent（ReAct 模式）
- 支持替换为云端 LLM（阿里云百炼 / SiliconFlow / OpenAI）

### 数据分析 (iot-warehouse)

- ClickHouse OLAP 查询
- 设备统计聚合
- 告警统计分析
- 趋势分析 / 同比环比

### 3D 可视化 (iot-digital)

- Three.js 3D 场景
- 工厂建筑模型
- 设备状态展示
- WebSocket 实时更新

### 监控大屏 (iot-monitor)

- KPI 指标展示
- 产线状态图
- 能耗趋势图
- 实时告警

---

## CI/CD

项目已集成 Jenkins 流水线，代码推送后自动触发：

```bash
Checkout → Maven Build → Unit Test → Docker Build → Deploy
```

### Jenkins 配置

1. 确保 Jenkins 容器已启动：`cd docker && docker compose up -d jenkins`
2. 访问 http://localhost:8080
3. 获取初始密码：`docker exec iot-jenkins cat /var/jenkins_home/secrets/initialAdminPassword`
4. 安装推荐插件
5. 创建 Pipeline，选择 `Pipeline script from SCM`
6. 填写 Git 仓库地址，Script Path 填 `Jenkinsfile`

---

## Kubernetes 部署

```bash
# 安装 minikube（本地单节点 K8s）
minikube start --cpus=4 --memory=8192

# 部署到开发环境
kubectl apply -k k8s/overlays/dev

# 查看部署状态
kubectl get pods -n iot-platform-dev
```

---

## ⚠️ 安全提醒

**本项目为开源学习项目，请勿直接用于生产环境！**

所有密码/密钥均已硬编码在 `docker-compose.yml` 和 Nacos 配置中，均为本地开发默认值：

| 服务 | 配置项 | 默认值 |
|------|--------|--------|
| PostgreSQL | 密码 | `iot_password` |
| Redis | 密码 | `iot_redis_password` |
| Nacos | 登录密码 | `nacos` |
| EMQX | Dashboard 密码 | `public` |
| Seata | secretKey | `SeataSecretKey123456789` |
| Grafana | 管理员密码 | `admin123` |
| InfluxDB | Admin Token | `iot-admin-token` |
| JWT | 密钥 | `cadc0fa5...`（Nacos 配置中） |

生产部署前必须在 `docker-compose.yml` 和 Nacos 控制台中修改以上所有值。

---

## License

Apache License 2.0 - 详见 [LICENSE](LICENSE) 文件