# ThingsLink

**Repository Path**: WayneFlash/things-link

## Basic Information

- **Project Name**: ThingsLink
- **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-01-10
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IoT Platform 轻量级物联网平台

> 基于 Spring Boot + Vue 3 的轻量级物联网管理平台，支持设备接入、数据采集、告警监控、权限管理等功能。

## 项目简介

IoT Platform 是一个功能完善的物联网设备管理平台，采用前后端分离架构，支持 MQTT 协议设备接入，提供设备管理、产品管理、告警配置、用户权限等核心功能。

### 主要特性

- 🚀 **设备管理** - 设备注册、状态监控、在线/离线检测
- 📦 **产品管理** - 产品定义、属性配置、命令下发
- 🌳 **分组管理** - 树形设备分组，支持多级分组
- 👥 **权限管理** - 基于角色的访问控制 (RBAC)，支持数据权限过滤
- 📊 **数据采集** - MQTT 协议数据接收与存储
- 🔔 **告警系统** - 告警规则配置、告警日志、消息通知
- 📈 **数据查询** - 设备历史数据查询与统计
- 🎨 **现代化界面** - 基于 Element Plus + Tailwind CSS

## 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 11 | 开发语言 |
| Spring Boot | 2.7.18 | 应用框架 |
| MyBatis Plus | 3.5.3.1 | ORM 框架 |
| MySQL | 8.0 | 关系数据库 |
| Redis | 6.2 | 缓存数据库 |
| MQTT | Eclipse Paho 1.2.5 | 消息队列协议 |
| Hutool | 5.8.25 | Java 工具类库 |
| FastJSON | 2.0.43 | JSON 处理 |

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.3.4 | 前端框架 |
| Vue Router | 4.2.4 | 路由管理 |
| Element Plus | 2.3.14 | UI 组件库 |
| Axios | 1.5.0 | HTTP 客户端 |
| ECharts | 5.4.3 | 数据可视化 |
| Tailwind CSS | 4.1.18 | CSS 框架 |
| Vite | 4.4.9 | 构建工具 |

### 基础设施

| 组件 | 版本 | 说明 |
|------|------|------|
| EMQX | 5.3 | MQTT Broker |
| Nginx | - | 反向代理 |

## 项目结构

```
IOT/
├── backend/                    # 后端项目
│   ├── src/main/java/com/iot/platform/
│   │   ├── IotPlatformApplication.java    # 启动类
│   │   ├── common/            # 公共类
│   │   │   └── Result.java    # 统一响应结果
│   │   ├── config/            # 配置类
│   │   │   ├── MybatisPlusConfig.java
│   │   │   └── WebMvcConfig.java
│   │   ├── controller/        # 控制器
│   │   │   ├── DeviceController.java
│   │   │   ├── ProductController.java
│   │   │   ├── UserController.java
│   │   │   ├── NotificationController.java
│   │   │   └── ...
│   │   ├── dto/               # 数据传输对象
│   │   ├── entity/            # 实体类
│   │   │   ├── Device.java
│   │   │   ├── Product.java
│   │   │   ├── DeviceData.java
│   │   │   ├── Notification.java
│   │   │   └── ...
│   │   ├── mapper/            # MyBatis Mapper
│   │   ├── mqtt/              # MQTT 相关
│   │   │   ├── MqttConfig.java
│   │   │   ├── MqttMessageHandler.java
│   │   │   └── MqttPublisher.java
│   │   ├── service/           # 业务逻辑层
│   │   ├── task/              # 定时任务
│   │   │   └── DeviceStatusCheckTask.java
│   │   └── util/              # 工具类
│   ├── src/main/resources/
│   │   ├── application.yml    # 应用配置
│   │   └── db/migration/      # 数据库迁移脚本
│   ├── Dockerfile             # 后端 Docker 镜像
│   └── pom.xml                # Maven 配置
├── frontend/                  # 前端项目
│   ├── src/
│   │   ├── api/               # API 接口
│   │   ├── components/        # 公共组件
│   │   ├── layouts/           # 布局组件
│   │   ├── router/            # 路由配置
│   │   ├── styles/            # 样式文件
│   │   ├── utils/             # 工具函数
│   │   ├── views/             # 页面组件
│   │   │   ├── Login.vue
│   │   │   ├── Dashboard.vue
│   │   │   ├── DeviceManagement.vue
│   │   │   ├── AlarmLog.vue
│   │   │   └── ...
│   │   ├── App.vue            # 根组件
│   │   └── main.js            # 入口文件
│   ├── Dockerfile             # 前端 Docker 镜像
│   ├── package.json           # 依赖配置
│   └── vite.config.js         # Vite 配置
├── docker-compose.yml         # Docker Compose 编排
├── init.sql                   # 数据库初始化脚本
└── README.md                  # 项目说明文档
```

## 核心功能模块

### 1. 设备管理

- 设备注册与配置
- 设备状态监控（在线/离线）
- 设备分组管理
- 设备数据查询
- 设备统计数据

### 2. 产品管理

- 产品定义与模型配置
- 产品属性定义（温度、湿度等）
- 产品命令配置（开关、控制等）
- 产品启用/禁用

### 3. 告警系统

- 告警规则配置（阈值告警）
- 告警级别分类（严重/警告/提示）
- 告警日志记录
- 消息通知推送
- 告警处理与恢复

### 4. 权限管理

- 用户管理
- 角色管理
- 菜单权限控制
- 数据权限过滤（分组级别）

### 5. 数据采集

- MQTT 消息接收
- 设备数据上报处理
- 历史数据存储
- 数据分区管理

## 数据库设计

### 核心表结构

| 表名 | 说明 |
|------|------|
| `tb_user` | 用户表 |
| `tb_role` | 角色表 |
| `tb_menu` | 菜单表 |
| `tb_device_group` | 设备分组表 |
| `tb_product` | 产品表 |
| `tb_attribute` | 产品属性表 |
| `tb_command` | 产品命令表 |
| `tb_device` | 设备表 |
| `tb_device_data` | 设备数据表 |
| `tb_command_log` | 命令下发记录表 |
| `tb_notification` | 消息通知表 |
| `tb_alarm_log` | 告警日志表 |

## 快速开始

### 环境要求

- JDK 11+
- Node.js 16+
- Maven 3.6+
- Docker & Docker Compose（可选）

### 使用 Docker Compose 启动（推荐）

```bash
# 启动所有服务（MySQL、Redis、EMQX）
docker-compose up -d

# 查看服务状态
docker-compose ps
```

### 后端启动

```bash
# 进入后端目录
cd backend

# 编译打包
mvn clean package

# 运行应用
java -jar target/iot-platform.jar

# 或使用 Maven 运行
mvn spring-boot:run
```

### 前端启动

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器（运行在 5173 端口）
npm run dev

# 构建生产版本
npm run build
```

> **端口说明**：
> - **生产环境**：前端和后端都通过8080端口访问（前后端部署在一起）
> - **开发环境**：前端开发服务器运行在5173端口，后端运行在8080端口（分开运行便于开发调试）

### 默认账号

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | admin123456 | 超级管理员 |

## 配置说明

### 后端配置 (application.yml)

```yaml
server:
  port: 8080  # 服务端口

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/iot_platform
    username: root
    password: root123456
  
  redis:
    host: localhost
    port: 16379
    password: redis123456

mqtt:
  broker-url: tcp://localhost:1883
  client-id: iot-platform-backend
  username: admin
  password: admin123.
```

### MQTT 主题配置

| 主题 | 方向 | 说明 |
|------|------|------|
| `ssc/+/report` | 设备 → 平台 | 设备数据上报 |
| `ssc/{deviceCode}/command` | 平台 → 设备 | 命令下发 |

## API 文档

### 设备相关接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/devices` | POST | 创建设备 |
| `/devices/list` | POST | 分页查询设备列表 |
| `/devices/detail` | POST | 获取设备详情 |
| `/devices/update` | POST | 更新设备 |
| `/devices/delete` | POST | 删除设备 |
| `/devices/{deviceCode}` | GET | 根据设备编码获取设备 |
| `/devices/latest-data` | POST | 获取设备最新数据 |
| `/devices/statistics` | POST | 获取设备统计数据 |

### 产品相关接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/products` | POST | 创建产品 |
| `/products/list` | GET | 获取产品列表 |
| `/products/{id}` | GET | 获取产品详情 |
| `/products/update` | POST | 更新产品 |
| `/products/delete` | POST | 删除产品 |

### 用户相关接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/auth/login` | POST | 用户登录 |
| `/auth/logout` | POST | 用户登出 |
| `/users` | POST | 创建用户 |
| `/users/list` | GET | 获取用户列表 |

## 部署说明

### 前置准备（全新服务器）

如果是全新服务器，需要先安装 Docker 和 Docker Compose：

```bash
# 1. 给安装脚本添加执行权限
chmod +x install-docker.sh

# 2. 执行安装脚本
sudo ./install-docker.sh

# 3. 使权限生效（重要！）
newgrp docker
# 或者注销后重新登录
```

安装脚本会自动检测操作系统并安装：
- ✅ Docker Engine
- ✅ Docker Compose
- ✅ 配置当前用户使用 Docker（无需 sudo）

### 配置 Docker 镜像加速器（国内服务器推荐）

如果服务器在国内，建议配置 Docker 镜像加速器以加快镜像下载速度：

```bash
# 1. 给镜像加速配置脚本添加执行权限
chmod +x setup-docker-mirror.sh

# 2. 执行配置脚本（需要 sudo 权限）
sudo ./setup-docker-mirror.sh
```

配置脚本会自动：
- ✅ 备份现有 Docker 配置
- ✅ 配置多个镜像加速器（DaoCloud、1Panel、DockerHub.icu 等）
- ✅ 重启 Docker 服务
- ✅ 验证配置是否生效

> **详细配置方法**: 请查看 [DOCKER_MIRROR_GUIDE.md](./DOCKER_MIRROR_GUIDE.md)

### 🚀 一键部署（推荐）

本平台提供一键部署脚本，用户无需任何操作即可完成部署。

#### 方法一：使用 Gitee 克隆（国内推荐）

```bash
# 1. 从 Gitee 克隆项目代码（国内速度最快）
git clone https://gitee.com/WayneFlash/things-link.git

# 2. 进入项目目录
cd things-link

# 3. 给脚本添加执行权限
chmod +x deploy.sh

# 4. 执行一键部署脚本
./deploy.sh
```

#### 方法二：使用 GitHub 克隆

```bash
# 1. 克隆项目代码到服务器
git clone https://github.com/Wayneflash/ThingsLink.git

# 2. 进入项目目录
cd ThingsLink

# 3. 给脚本添加执行权限
chmod +x deploy.sh

# 4. 执行一键部署脚本
./deploy.sh
```

#### 方法三：使用 FastGit 镜像

```bash
# 1. 从 FastGit 镜像克隆
git clone https://hub.fastgit.xyz/Wayneflash/ThingsLink.git

# 2. 进入项目目录
cd ThingsLink

# 3. 给脚本添加执行权限
chmod +x deploy.sh

# 4. 执行一键部署脚本
./deploy.sh
```

#### 方法四：直接下载压缩包

如果不需要 Git，也可以直接下载压缩包：

```bash
# 1. 从 Gitee 下载项目压缩包
wget https://gitee.com/WayneFlash/things-link/archive/main.zip

# 2. 解压
unzip main.zip

# 3. 进入项目目录
cd things-link

# 4. 执行部署
chmod +x deploy.sh
./deploy.sh
```

部署脚本会自动完成以下操作：
- ✅ 检查 Docker 和 Docker Compose 是否已安装
- ✅ 检查并清理端口占用
- ✅ 停止并删除旧容器
- ✅ 创建必要的目录（mysql-data, emqx-data, emqx-log）
- ✅ 启动所有服务（MySQL + Redis + EMQX）
- ✅ 初始化数据库
- ✅ 显示服务访问地址

**详细部署指南**: 请查看 [DEPLOY.md](./DEPLOY.md)

### Docker 部署（手动）

```bash
# 构建后端镜像
cd backend
docker build -t iot-platform-backend .

# 构建前端镜像
cd frontend
docker build -t iot-platform-frontend .

# 启动所有服务
docker-compose up -d
```

### Nginx 配置

```nginx
server {
    listen 80;
    server_name localhost;

    # 前端静态资源
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /api {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # MQTT WebSocket 代理
    location /mqtt {
        proxy_pass http://emqx:8083;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## 开发指南

### 添加新的设备类型

1. 在 `tb_product` 表中创建产品定义
2. 在 `tb_attribute` 表中配置产品属性
3. 在 `tb_command` 表中配置产品命令
4. 设备按照 MQTT 协议格式上报数据

### 添加新的告警规则

1. 在设备配置中设置告警参数
2. 告警规则存储在 `tb_device.alarm_config` 字段（JSON 格式）
3. 系统自动检测并触发告警

### 自定义权限

1. 在 `tb_role` 表中定义角色
2. 在 `tb_menu` 表中配置菜单权限
3. 将角色分配给用户

## 常见问题

### 1. 设备离线检测

系统默认每 5 分钟检查一次设备在线状态，超时时间可在 `tb_device.offline_timeout` 字段配置。

### 2. 数据分区管理

设备数据表按月分区，需要定期创建新的分区，参考 `init.sql` 中的分区定义。

### 3. 告警通知

告警通知通过 `tb_notification` 表记录，前端轮询获取未读通知。

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如有问题，请提交 Issue 或联系项目维护者。