上传
点击文件名下载附件
上传
点击文件名下载附件
上传
点击文件名下载附件
上传
点击文件名下载附件
> 适用版本：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
作者: scmonk 时间: 2026-10-12 09:50
学习啦！
| 欢迎光临 OpenEdv-开源电子网 (https://www.openedv.com/) | Powered by Discuz! X3.4 |