单文件部署的MQTT轻量级物联网数据平台

seasondear

游客，如果您要查看本帖隐藏内容请回复

> 适用版本：v2.0（基于 iot-platform.exe 单文件部署）

> 本手册面向平台使用者（管理员与普通用户），涵盖运行部署、端口修改、物模型、设备接入、数据导出、用户管理等日常操作。

---

## 1. 平台简介

本平台是一个**单文件部署**的轻量级物联网数据平台，包含：

| 组成 | 说明 | 默认端口 |

|------|------|----------|

| Web 管理端 | 浏览器 访问，管理产品、设备、数据、账号 | 8000 |

| MQTT Broker | 内置 MQTT 消息代理，设备直接接入（支持 3.1.1 / 5.0） | 1883 |

主要功能：

- 产品与物模型管理（属性定义、表达式运算、命令下发）

- 设备接入与鉴权（设备号 + 密码，MQTT 连接时认证）

- 实时数据上报 / 历史数据补传（携带时间戳）

- 数据查看、曲线展示、CSV 导出

- 多级账号体系（超级管理员 → 管理员 → 普通账号 → 子账号）

- 登录传输加密（RSA 非对称加密 + 时间戳 + 盐，浏览器端自动完成，无需配置）

---

## 2. 运行与停止

### 2.1 运行

1. 将 `iot-platform.exe` 复制到目标电脑任意目录（如 `D:\iot\`）。

2. 双击运行，会弹出一个控制台窗口（显示运行日志，**请勿关闭**，关闭即停止服务）。

3. 首次运行会自动在同目录生成：

   - `config.json` —— 配置文件

   - `iot.db` —— SQLite 数据库（**AES-256 整机加密存储**，所有数据都存这里）

   - `db.key` —— **数据库密钥文件**（256-bit 随机密钥，请与 iot.db 一并妥善保管，切勿泄露）

   - `logs\` —— 日志目录

4. 在浏览器访问：`http://本机IP:8000`（本机可用 `http://localhost:8000`）。

5. 默认管理员账号：

   | 用户名 | 密码 |

   |--------|--------|

   | admin | admin123 |

   > **首次登录后请立即修改密码**（见 2.3）。

### 2.2 防火墙放行

局域网其他电脑/设备要访问平台，需在服务器电脑放行两个端口：

- **TCP 8000**（网页访问）

- **TCP 1883**（设备 MQTT 接入）

Windows 操作：控制面板 → Windows Defender 防火墙 → 高级设置 → 入站规则 → 新建规则 → 端口 → 填入 `8000,1883` → 允许连接。

### 2.3 修改密码与退出

- 登录后点击页面**右上角用户名** → 「修改密码」→ 输入原密码和新密码 → 确定。

- 点击右上角用户名 → 「退出登录」。

- 安全策略：**超过 10 分钟无操作自动退出登录**，重新登录即可。

### 2.4 停止服务

关闭 EXE 的控制台窗口，或在任务管理器结束 `iot-platform.exe` 进程。

---

## 3. 修改端口号

1. 停止服务（关闭控制台窗口）。

2. 用记事本打开 EXE 同目录下的 `config.json`：

   ```json

   {"web_port": 8000, "mqtt_port": 1883}

   ```

   - `web_port`：网页访问端口（如改为 8080）

   - `mqtt_port`：设备 MQTT 接入端口（如改为 1884）

3. 保存文件，重新运行 EXE。

4. 用新端口访问，例如 `http://本机IP:8080`；设备端 MQTT 连接端口也要同步修改。

5. 若修改了端口，防火墙放行的端口也要相应更新。

> 若 `config.json` 被删除，下次启动会按默认端口（8000/1883）重新生成。

---

## 4. 产品与物模型

**产品是设备的模板**：定义一类设备上报哪些属性、支持哪些命令。设备必须先选择所属产品才能创建。

进入左侧「**产品与物模型**」页面操作。

### 4.1 新建产品与物模型

1. 点击「+ 新建产品」，填写产品名称（必填）、描述（可选）。

2. 在「物模型（JSON 格式）」文本框中定义属性与命令，格式如下：

   ```json

   {

     "properties": [

       {"key": "temp", "name": "温度", "type": "float", "unit": "℃", "expr": "value / 10 - 40"},

       {"key": "hum",  "name": "湿度", "type": "float", "unit": "%RH"},

       {"key": "alarm", "name": "报警", "type": "bool"}

     ],

     "commands": [

       {"key": "setTemp", "name": "设置温度", "params": [{"key": "target", "name": "目标值", "type": "int"}]}

     ]

   }

   ```

   字段说明：

   | 字段 | 说明 |

   |------|------|

   | `key` | 设备上报报文里的字段名（英文，与设备端约定一致） |

   | `name` | 页面上显示的中文名称 |

   | `type` | 数据类型：`int` / `float` / `bool` / `string` |

   | `unit` | 单位（可选，如 ℃、%RH） |

   | `expr` | 换算表达式（可选）。变量 `value` 为设备上报的原始值，支持 `+ - * / % **` 及 `abs round min max pow int float sqrt`，如 `value / 10 - 40`。运算后的值才入库显示 |

   | `commands[].key` | 下发命令的标识 |

   | `commands[].params` | 命令参数列表（可选），每项含 `key/name/type` |

3. 编辑框下方会**实时预览**属性表格；「**上报示例**」区域会按当前物模型**自动生成并自动更新**设备上报的示例 JSON（含实时上报与历史上报两种）。

4. 点击「**复制上报示例**」可把示例 JSON 复制到剪贴板，直接发给设备端开发人员对接。

5. 点击「保存」。

### 4.2 编辑 / 删除产品

- 列表中点击「编辑」修改物模型，保存后**立即对该产品下所有设备生效**。

- 删除产品前需先删除该产品下的所有设备（有设备时无法删除）。

---

## 5. 设备接入（添加设备）

进入左侧「**设备管理**」页面。

### 5.1 添加设备

1. 点击「+ 添加设备」。

2. 填写：

   - **设备名称**（必填，如"一号温湿度传感器"）

   - **所属产品**（下拉选择，决定该设备的数据解析规则）

   - **设备号**（可选）：留空自动生成；也可自定义 3–32 位字母/数字/下划线/中划线

   - **设备密码**（可选）：留空自动生成；6–32 位且不含空格

3. 点击「创建」，弹出**设备凭据**（设备号 + 设备密码），请妥善保存。

> 忘记凭据时，可在设备列表点击「凭据」按钮随时再次查看。

### 5.2 设备端 MQTT 接入说明

把以下信息提供给设备端开发人员：

| 项目 | 值 |

|------|-----|

| 服务器 | 平台电脑 IP |

| 端口 | 1883（MQTT，支持 3.1.1 / 5.0） |

| 用户名 | 设备号 |

| 密码 | 设备密码 |

**上行（设备 → 平台）**：发布到主题 `device/设备号/up`

```json

实时上报： {"data": {"temp": 365, "hum": 600}}

历史上报： {"ts": 1756368000000, "data": {"temp": 365}}

```

- 实时上报**不带 `ts`**，按平台服务器时间入库。

- 历史上报**携带 `ts`**（毫秒/秒级 Unix 时间戳，或 `"2026-08-28 12:00:00"` 格式字符串），按该时间戳入库，查询时标记为「历史」。时间戳不能晚于当前时间（容忍 5 分钟），也不能早于 30 天，否则整条报文被拒绝。

- `data` 内的字段名需与物模型 `key` 一致；带 `expr` 的属性上报**原始值**（如温度按 `value / 10 - 40` 运算，则上报 365 而不是 36.5）。

- 设备连接认证通过后，后续报文**免密**，无需再携带密码字段。

**下行（平台 → 设备）**：设备订阅主题 `device/设备号/down`，收到的报文格式：

```json

{"cmd": "setTemp", "params": {"target": 25}}

```

### 5.3 设备状态

- 设备列表实时显示在线/离线状态（自动刷新）。

- 设备断开 MQTT 连接即离线，记录离线时间。

### 5.4 下发命令

在设备列表或设备信息页点击「下发」，选择物模型中定义的命令，填写参数后发送。设备端在 `device/设备号/down` 主题收到对应 JSON。

### 5.5 远程升级（FTP）

侧边栏「远程升级」页：选择产品 → 选择设备 → 填写目标版本号与 FTP 信息（服务器地址、端口、用户名、密码、文件夹、文件名）→ 点击「下发升级」。

平台仅负责把升级参数下发到设备，**FTP 服务器与升级包由用户自行准备**。设备端收到：

```json

{"cmd": "upgrade", "params": {"version": "v1.2.0", "ftp_host": "ftp.example.com", "ftp_port": 21, "ftp_user": "user", "ftp_pass": "pass", "ftp_dir": "/firmware", "ftp_file": "fw_v1.2.0.bin"}}

```

设备从 FTP 下载升级包完成升级后，向 `device/设备号/up` 上报完成标志（**result=0 成功，非 0 失败**）：

```json

{"upgrade": {"device_no": "D1A2B3C4D", "version": "v1.2.0", "result": 0, "message": "升级成功"}}

```

- 平台自动匹配该设备最近一条「已下发/待上报」的升级任务并更新状态（成功 / 失败）。

- **设备在线时立即下发；设备离线时自动排队，设备下次上报数据时自动补发**（物模型命令下发同样适用）。

- **下发超时时间**：系统设置中可配置（默认 30 分钟）。升级任务超过该时间未收到设备上报结果自动判定失败；排队命令超时后不再补发。

- 升级记录按账号可见设备过滤，每页 20 条支持翻页，每 5 秒自动刷新。

---

## 6. 数据查看与导出

### 6.1 查看历史数据

设备列表点击「数据」进入历史数据页：

- 按时间倒序分页展示，可翻页。

- 属性值已按物模型 `expr` 运算显示，并带名称和单位。

- 时间列带橙色「**历史**」标签的行，表示该数据由设备携带时间戳补传（非实时上报）。

### 6.2 导出数据（CSV）

在历史数据页点击「**导出数据(CSV)**」按钮，浏览器下载该设备的全部历史数据（最多 30 天）：

- 第一行为列头：`时间, 来源, 属性1, 属性2, ...`（列头含属性名、标识与单位）

- 「来源」列标识该行数据是实时上报还是历史补传

- 同一时间戳的多个属性合并为一行（宽表），时间正序

- 文件带 UTF-8 BOM，**Excel 双击直接打开不乱码**

---

## 7. 报警功能

当设备上报的数据超过设定值时，平台自动记录报警；报警可消除（保留记录），消除后主页不再显示。

### 7.1 设置报警值（上限 / 下限）

1. 在设备列表点击「数据」进入设备页，点击顶部「**报警设置**」按钮。

2. 页面按物模型属性逐行列出，可为每个属性填写：

   - **上限报警值**：数据 **大于** 该值时报警（如温度超过 80）

   - **下限报警值**：数据 **小于** 该值时报警（如温度低于 -10）

   - 留空表示不启用该方向的报警

3. 点击「保存报警设置」生效。

> 说明：判断使用的是物模型 `expr` 运算后的数值（与页面显示一致）。等于阈值不报警。

### 7.2 查看报警记录

- **单设备**：设备页点击「**报警记录**」进入二级页面，查看该设备的全部报警，支持「未消除 / 已消除 / 全部」筛选，每页 20 条。

- **全局**：点击左侧导航「**报警信息**」，可直接查看当前账号可见范围内**未消除的报警**，每条显示时间、设备、产品、属性、报警类型（超上限 / 低于下限）、当前值与阈值。

### 7.3 消除报警

- 在报警列表点击某条记录的「**消除**」，或点击「**消除全部报警**」。

- 消除后**记录仍然保留**（状态列显示「已消除」及消除时间），只是不再计入报警统计。

- 同一设备的同一属性同一方向，在报警未消除期间**不会重复记录**；消除后若再次越限，会重新记录一条。

### 7.4 主页报警统计

主页统计卡片显示「**报警中设备（未消除）**」数量（有报警时红色显示）；产品概览表格的「**报警设备**」列显示每个产品有几台设备在报警中，点击红色「N 台报警中」可直接进入报警信息页。

### 7.5 报警信息可见范围

报警数据与设备权限一致：您只能看到自己及下级账号创建设备的报警，消除操作亦受同样限制。

---

## 8. 用户管理

仅超级管理员和管理员可进入「**用户管理**」页面。

### 7.1 账号角色说明

| 角色 | 说明 | 可创建的账号 |

|------|------|--------------|

| 超级管理员（admin 登录账号） | 最高权限，可见全部设备 | 管理员、普通账号 |

| 管理员 | 由超级管理员创建 | 普通账号 |

| 普通账号 | 业务账号，管理自己的设备 | 子账号 |

| 子账号 | 普通账号的附属账号 | 不能创建账号 |

- **数据可见范围**：上级账号可以看到自己及其所有下级（含下级的下级）创建的设备；同级账号之间互不可见。

- **创建者标识**：设备列表「创建者」列和设备信息页「创建账号」行会显示该设备由哪个账号创建；自己创建的显示为「本账号」。

### 7.2 创建账号

1. 点击「+ 新建账号」，填写用户名（唯一）、密码。

2. 选择角色（超级管理员可创建"管理员"或"普通账号"；管理员只能创建"普通账号"；普通账号在设备管理页可创建"子账号"）。

3. 创建"普通账号"时，超级管理员可指定其所属管理员；创建"子账号"时可勾选「**允许添加设备**」。

### 7.3 管理账号

- **重置密码**：上级账号可对下级账号重置密码。

- **子账号权限**：在账号列表中直接勾选/取消「可添加设备」，实时生效。

- **删除账号**：删除账号会**级联删除**其名下所有设备与数据，操作前请确认。

---

## 9. 数据保留策略

- 每台设备的数据保留 **30 天**，且最多保留最近 **10,000 条**，超限自动清理最旧数据。

- 如需长期留存，请定期使用 CSV 导出功能备份。

---

## 10. 常见问题（FAQ）

**Q1：浏览器打不开管理页面？**

确认 EXE 正在运行（控制台窗口未关闭）、端口未被修改、防火墙已放行 8000 端口、访问地址 `http://服务器IP:8000` 正确。

**Q2：设备连不上 MQTT（1883）？**

检查防火墙是否放行 1883；确认用户名=设备号、密码=设备密码（在设备列表「凭据」可查）；确认报文发布主题为 `device/设备号/up`。

**Q3：上报了数据但页面看不到？**

确认 `data` 里的字段名与物模型 `key` 完全一致；物模型 JSON 格式正确；带 `expr` 的属性上报的是原始值。

**Q4：带时间戳的历史数据没有入库？**

`ts` 格式必须为毫秒/秒级 Unix 时间戳或 `"YYYY-MM-DD HH:MM:SS"`；不能晚于当前时间 5 分钟以上；不能早于 30 天。可在服务控制台日志中查看拒绝原因。

**Q5：忘记 admin 密码怎么办？**

删除 `iot.db`（和 `db.key`）会重置为默认账号 admin/admin123，但**会清空所有数据，慎用**。建议平时保管好密码，或让超级管理员为下级账号重置密码。

**Q6：db.key 文件丢失或误删怎么办？**

`iot.db` 已加密，**没有 db.key 数据无法解密恢复**。请务必与 iot.db 一起备份保管。若确认数据可以丢弃，删除 `iot.db`、`iot.db-wal`、`iot.db-shm` 和 `db.key` 后重启程序，即按全新数据库初始化。

**Q7：如何备份数据？**

停止服务后，**同时复制 `iot.db` 和 `db.key`** 两个文件保存（缺一不可），恢复时放回同一目录。注意：备份文件等同于全部数据，请存放在安全位置。

**Q8：登录时浏览器提示密码错误但确认没输错？**

会话超过 10 分钟未操作会自动失效，刷新页面重新登录即可。

**Q9：设置了报警值却没有产生报警？**

确认设备已重新上报数据（报警只在数据上报时检查）；确认数值确实**严格大于上限 / 小于下限**（等于阈值不报警）；确认判断的是 `expr` 运算后的数值，而非设备上报的原始值。

---
————————————————
版权声明：本文为CSDN博主「煮煮论英雄」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/u012320127/article/details/164255499