# iot_cloud_platform

**Repository Path**: fenghen777/iot_cloud_platform

## Basic Information

- **Project Name**: iot_cloud_platform
- **Description**: 高性能iot云平台框架。
- Web 框架：Drogon（HTTP + WebSocket）
- 关系库：PostgreSQL（用户/网关/设备属性/告警/指令日志）
- 时序库：TDengine（设备点位时序数据）
- 消息总线：Mosquitto MQTT（含 Dynamic Security）

- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IoT Cloud Platform

工业 IoT 云平台，接收边缘网关上报的设备数据，提供设备管理、时序数据查询、告警、远程控制与运维监控能力。与边缘采集网关通过 MQTT 协作，把"上报数据"转化为"可查询、可管理、可告警、可控制"的统一平台能力。

## 核心能力

- **认证与权限**：JWT 登录、token 版本作废（改密/禁用/重置后旧 token 失效）、按网关归属与角色隔离的业务授权。
- **网关与设备管理**：网关 CRUD、分配、启用/禁用、连接信息下发（`gateway_id`/`secret_key`/`mqtt_host`）；设备列表、点位查询、历史查询、在线/离线检测。
- **数据链路**：MQTT 接入（`/data`、`/status`、`/ack`），时序写入 TDengine，业务元数据写入 PostgreSQL，WebSocket（`/ws/realtime`）实时推送前端。
- **告警与远程控制**：告警规则与记录，指令模板、设备绑定、指令下发、执行日志，ACK 回执驱动指令状态更新。
- **运维监控**：管理后台（用户/网关/存储统计/审计/系统监控）、系统阈值告警引擎、SSE 事件推送、Prometheus 指标导出。

## 系统架构

```text
边缘网关 collector
  -> MQTT (/data, /status, /ack)
  -> cloud_server (MqttSubscriber)
      -> TDengine      (设备点位时序)
      -> PostgreSQL    (用户/网关/设备/告警/指令/审计)
      -> WebSocket     (/ws/realtime 前端实时推送)
```

核心组件：

| 组件 | 职责 |
|---|---|
| `MqttSubscriber` | 订阅 `/data/#`、`/status/#`、`/ack/#`，解析并分发 |
| `PostgresManager` | 用户、网关、设备属性、告警、指令、审计 |
| `TDengineManager` | 时序写入与历史查询 |
| `AuthFilter` + `AuthUtil` | JWT 校验、网关/设备范围授权 |
| `WebSocketController` | 实时消息分发与权限过滤 |
| `DeviceMonitor` | 离线检测、指标记录、指令重试 |

存储分工：PostgreSQL 维护业务属性与权限状态（强约束、审计），TDengine 承载高频时序数据（历史趋势、点位查询）。MQTT Broker 由 Mosquitto Dynamic Security 管控客户端与 Topic 权限，不替代平台业务授权。

## 目录结构

```text
iot_cloud_platform/
├── cloud_server/        云端后端服务（Drogon, C++17）
│   ├── src/             源码（controllers / managers / mqtt / websockets / ...）
│   ├── config/          server_config.json 等配置
│   ├── docs/            接口 / 部署 / MQTT 接入 / 架构设计文档
│   ├── tests/           单元 / 集成 / benchmark 测试
│   └── CMakeLists.txt
├── frontend/cloud_app/  云平台前端（React + Vite）
├── docs/                云平台设计文档（架构 / 功能 / 认证 / 告警 / 日志 / 部署等）
├── deploy_cloud.sh      一键部署脚本（详见 cloud_server/docs/部署文档.md）
├── run_cloud.sh         本地启动脚本
└── run_cloud_tests.sh   云平台测试脚本
```

## 构建与运行

### 后端 cloud_server

依赖：C++17、CMake、Ninja、Drogon、PostgreSQL、TDengine、nng、Paho MQTT、OpenSSL。

```bash
cd cloud_server
bash build.sh            # 构建
bash run.sh              # 仅启动后端（开发调试）
```

首次使用请从模板复制配置并填写真实值（数据库/MQTT 口令、服务器 IP 等；真实配置文件已在 `.gitignore` 中，不会提交）：

```bash
cp cloud_server/config/server_config.example.json cloud_server/config/server_config.json
cp cloud_server/tests/tests_config.example.env      cloud_server/tests/tests_config.env
```

默认监听 `0.0.0.0:8081`（见 `cloud_server/config/server_config.json`）。敏感配置支持环境变量覆盖：

- `CLOUD_PG_PASSWORD`
- `CLOUD_TD_PASSWORD`
- `CLOUD_MQTT_PASSWORD`
- `CLOUD_JWT_SECRET`

### 前端 cloud_app

```bash
cd frontend/cloud_app
npm install
npm run build            # 产物输出到 dist/
```

### 一键部署 / 启动

```bash
bash deploy_cloud.sh <user@host>   # 现网部署（systemd + nginx），需指定目标主机，见 cloud_server/docs/部署文档.md
bash run_cloud.sh                  # 本地启动 cloud_server
```

## 对外接口

- HTTP API：`http://<host>:8081/api/...`
- WebSocket：`ws://<host>:8081/ws/realtime?token=<jwt>`
- Prometheus 指标：`GET /metrics`
- 管理监控：`/api/admin/metrics`、`/api/admin/metrics/events`、`/api/admin/metrics/events/stream`（SSE）

接口字段与权限口径见 `cloud_server/docs/接口文档.md`。

## 技术栈

| 层 | 技术 |
|---|---|
| 后端 | C++17、Drogon（HTTP + WebSocket） |
| 关系库 | PostgreSQL |
| 时序库 | TDengine |
| 消息总线 | Mosquitto MQTT（Dynamic Security） |
| 前端 | React、Vite |
| 鉴权 | JWT + `token_version` |
| 监控 | Prometheus、SSE |

## 文档导航

- 架构与功能：`docs/云平台架构设计.md`、`docs/云平台功能设计.md`、`docs/云平台前端功能设计.md`
- 接口与部署：`cloud_server/docs/接口文档.md`、`cloud_server/docs/部署文档.md`
- MQTT 接入：`cloud_server/docs/MQTT接入指南.md`、`docs/MQTT云边协作设计.md`
- 认证鉴权：`docs/云平台认证与鉴权设计.md`、`docs/云平台用户越权优化.md`
- 告警与日志：`docs/告警引擎设计文档.md`、`docs/日志系统架构设计.md`
- 管理后台：`docs/云平台管理后台设计.md`
- 模块文档索引：`cloud_server/docs/README.md`