233 lines
8.7 KiB
Markdown
233 lines
8.7 KiB
Markdown
# MQTT 智能家居管理系统 - 设计文档
|
||
|
||
## 概述
|
||
|
||
一个轻量级的智能家居管理项目，通过自建 EMQX Broker 管理 MQTT 设备。提供 Web 管理页面和 CLI 命令行工具，支持 Home Assistant Discovery 协议和自定义协议。
|
||
|
||
## 技术选型
|
||
|
||
| 组件 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| 后端框架 | FastAPI | 原生异步，适合 MQTT 长连接；自带 API 文档 |
|
||
| MQTT 客户端 | aiomqtt (paho-mqtt) | 异步兼容 FastAPI |
|
||
| 前端 | Vue 3 + Vite + Tailwind CSS + Pinia | 现代单页应用，响应式 |
|
||
| 数据库 | SQLite + aiosqlite + SQLAlchemy | 零配置，单文件，适合单进程 |
|
||
| CLI | click | 与 Web API 共享业务逻辑 |
|
||
| 配置管理 | pydantic-settings | 类型安全的环境变量加载 |
|
||
|
||
## 架构方案：单体 FastAPI
|
||
|
||
采用单体架构，FastAPI 同时处理 REST API 和 MQTT 连接。单进程部署，Web 和 CLI 共享同一套业务逻辑。
|
||
|
||
```
|
||
EMQX Broker <--MQTT--> FastAPI MQTT Client <---> SQLite
|
||
| ^
|
||
REST API CLI (click)
|
||
|
|
||
Vue SPA
|
||
```
|
||
|
||
**优势：** 最简部署（一个 Python 进程 + 一个 SQLite 文件），零逻辑重复。
|
||
**局限：** MQTT 客户端和 Web 服务共享进程，不适合多实例水平扩展。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
mqtt-home/
|
||
├── pyproject.toml # 依赖管理、入口点
|
||
├── .env # EMQX 凭据（gitignore）
|
||
├── .env.example # 配置模板
|
||
├── src/
|
||
│ └── mqtt_home/
|
||
│ ├── __init__.py
|
||
│ ├── config.py # 环境变量配置（pydantic-settings）
|
||
│ ├── main.py # FastAPI 应用 + 生命周期（启停 MQTT）
|
||
│ ├── database.py # SQLite 引擎、会话、Base
|
||
│ ├── models.py # SQLAlchemy ORM 模型
|
||
│ ├── schemas.py # Pydantic 请求/响应模型
|
||
│ ├── mqtt_client.py # aiomqtt 客户端：订阅、发布、回调
|
||
│ ├── device_registry.py # 业务逻辑：添加/删除/控制设备
|
||
│ ├── discovery.py # HA Discovery 协议处理器
|
||
│ ├── emqx_api.py # EMQX REST API 封装
|
||
│ ├── cli.py # click CLI 命令
|
||
│ └── api/
|
||
│ ├── __init__.py
|
||
│ ├── devices.py # REST 路由：设备增删改查 + 控制
|
||
│ ├── broker.py # REST 路由：Broker 状态、客户端、主题
|
||
│ └── dashboard.py # REST 路由：聚合统计
|
||
└── frontend/ # Vue SPA
|
||
└── ...
|
||
```
|
||
|
||
**模块职责：**
|
||
- `device_registry.py` — 设备业务逻辑的唯一入口，API 路由和 CLI 都从此导入
|
||
- `mqtt_client.py` — MQTT 连接生命周期管理
|
||
- `discovery.py` — 在 mqtt_client 上注册 HA Discovery 主题回调
|
||
- `emqx_api.py` — EMQX REST API 的薄封装，处理认证和端点映射
|
||
- 模块间通过直接函数调用通信，无消息总线或事件队列
|
||
|
||
## 数据模型
|
||
|
||
### devices 设备表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | TEXT (UUID) | 主键 |
|
||
| name | TEXT | 设备名称 |
|
||
| type | TEXT | 设备类型：switch, light, sensor, binary_sensor, climate 等 |
|
||
| protocol | TEXT | ha_discovery 或 custom |
|
||
| mqtt_topic | TEXT | 状态主题（如 homeassistant/light/living_room/status） |
|
||
| command_topic | TEXT | 命令主题（发送控制指令） |
|
||
| discovery_topic | TEXT | 原始 HA 发现主题（可为空） |
|
||
| discovery_payload | TEXT (JSON) | 原始发现配置（可为空） |
|
||
| attributes | TEXT (JSON) | 设备属性 |
|
||
| state | TEXT | 当前状态（on, off, 温度值等） |
|
||
| is_online | BOOLEAN | 在线状态（根据 last_seen 超时判断） |
|
||
| last_seen | DATETIME | 最后收到 MQTT 消息的时间 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
### device_logs 设备日志表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INTEGER (自增) | 主键 |
|
||
| device_id | TEXT (外键) | 关联设备 |
|
||
| direction | TEXT | rx（收到）或 tx（发送命令） |
|
||
| topic | TEXT | MQTT 主题 |
|
||
| payload | TEXT | 消息内容 |
|
||
| timestamp | DATETIME | 时间戳 |
|
||
|
||
每设备保留最近 100 条日志，超出自动清理。
|
||
|
||
### 设备状态流转
|
||
|
||
1. **HA Discovery 自动注册** — 收到 `homeassistant/<type>/<node_id>/config` 消息时自动创建设备记录
|
||
2. **手动添加** — 通过 API/CLI 指定主题、类型、命令主题
|
||
3. **状态更新** — 设备状态主题收到消息 → 更新 state + last_seen
|
||
4. **设备控制** — API/CLI 向命令主题发布消息 → 同时记录日志
|
||
5. **在线判断** — last_seen 超过 60 秒标记为离线
|
||
|
||
## MQTT 集成
|
||
|
||
### HA Discovery 协议（被动，自动）
|
||
|
||
- 启动时订阅 `homeassistant/#`
|
||
- 解析 `config` 主题 → 自动创建设备记录
|
||
- 自动订阅每个设备的 `state_topic`
|
||
- 处理 `availability` 主题判断设备上下线
|
||
- 支持标准 HA Discovery 所有字段：device class, unit of measurement, state class 等
|
||
|
||
### 自定义协议（手动，用户定义）
|
||
|
||
- 用户通过 CLI 或 Web UI 添加设备，指定：
|
||
- 状态主题（监听状态更新的位置）
|
||
- 命令主题（发送控制指令的位置）
|
||
- JSON 负载格式（简单模板，如 `{"state": "{{value}}"}`）
|
||
- 系统订阅状态主题并追踪变化
|
||
|
||
### 通用 MQTT 行为
|
||
|
||
- 使用 `aiomqtt`（基于 `paho-mqtt` 的异步封装）
|
||
- 所有订阅使用 QoS 1（至少一次投递）
|
||
- 使用 Retained 消息保持状态持久化（订阅时读取保留消息）
|
||
- 连接断开时指数退避重连（初始 1 秒，最大 60 秒）
|
||
- 客户端 ID：`mqtt-home-{uuid}`
|
||
|
||
## API 设计
|
||
|
||
### REST API（FastAPI 路由）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/devices` | 获取所有设备列表 |
|
||
| POST | `/api/devices` | 手动添加设备 |
|
||
| GET | `/api/devices/{id}` | 获取设备详情 |
|
||
| PUT | `/api/devices/{id}` | 更新设备配置 |
|
||
| DELETE | `/api/devices/{id}` | 删除设备 |
|
||
| POST | `/api/devices/{id}/command` | 向设备发送控制命令 |
|
||
| GET | `/api/devices/{id}/logs` | 获取设备最近消息日志 |
|
||
| GET | `/api/broker/status` | EMQX Broker 统计信息 |
|
||
| GET | `/api/broker/clients` | 已连接 MQTT 客户端列表 |
|
||
| GET | `/api/broker/topics` | 活跃主题列表 |
|
||
| GET | `/api/dashboard` | 聚合统计（设备在线/离线数、最近活动） |
|
||
|
||
### WebSocket
|
||
|
||
- `/ws/devices` — 设备状态变化实时推送（state, is_online 变更时推送）
|
||
|
||
### CLI 命令
|
||
|
||
```bash
|
||
# 设备管理
|
||
mqtt-home device list
|
||
mqtt-home device add --name "客厅灯" --type light --state-topic home/living/light --command-topic home/living/light/set
|
||
mqtt-home device info <device_id>
|
||
mqtt-home device remove <device_id>
|
||
mqtt-home device command <device_id> --payload '{"state":"on"}'
|
||
mqtt-home device logs <device_id> [--limit 20]
|
||
|
||
# Broker 管理
|
||
mqtt-home broker status
|
||
mqtt-home broker clients
|
||
mqtt-home broker topics
|
||
|
||
# 服务启动
|
||
python -m mqtt_home serve
|
||
```
|
||
|
||
## 前端设计
|
||
|
||
### 页面
|
||
|
||
- **仪表盘** — 设备数量统计、在线/离线状态、最近活动时间线
|
||
- **设备列表** — 网格视图，每个设备卡片显示类型图标、名称、当前状态、在线指示灯、快捷切换
|
||
- **设备详情** — 状态展示、控制面板（根据类型显示开关/滑块/数值输入）、消息日志
|
||
- **Broker 管理** — 已连接客户端列表、活跃主题、Broker 健康状态
|
||
|
||
### 关键交互
|
||
|
||
- WebSocket 实时推送设备状态变化
|
||
- 设备卡片根据设备类型显示对应图标和颜色
|
||
- 控制面板根据设备类型自适应（switch → 切换按钮，light → 开关+亮度滑块，sensor → 只读数值显示）
|
||
- 响应式布局，支持移动端访问
|
||
|
||
## 配置
|
||
|
||
### 环境变量
|
||
|
||
```
|
||
MQTT_HOST=192.168.0.31
|
||
MQTT_PORT=1883
|
||
MQTT_USERNAME=
|
||
MQTT_PASSWORD=
|
||
EMQX_API_URL=http://192.168.0.31:18083/api/v5
|
||
EMQX_API_KEY=<your-api-key>
|
||
EMQX_API_SECRET=<your-secret>
|
||
DATABASE_URL=sqlite+aiosqlite:///./data/mqtt_home.db
|
||
WEB_HOST=0.0.0.0
|
||
WEB_PORT=8000
|
||
```
|
||
|
||
### EMQX 连接信息
|
||
|
||
- MQTT Broker：`192.168.0.31:1883`
|
||
- EMQX Dashboard：`http://192.168.0.31:18083`
|
||
- EMQX REST API：`http://192.168.0.31:18083/api/v5`
|
||
- 认证方式：API Key + Secret Key（HTTP Basic Auth）
|
||
|
||
## 错误处理
|
||
|
||
- MQTT 连接失败：记录日志，自动重连，Web 端显示连接状态
|
||
- EMQX API 请求失败：返回错误信息，不阻塞核心功能
|
||
- 设备命令发送失败：记录日志，返回错误给用户
|
||
- 数据库操作失败：事务回滚，返回 500 错误
|
||
|
||
## 部署
|
||
|
||
- Python 3.11+
|
||
- `pip install -e .` 安装
|
||
- `python -m mqtt_home serve` 启动（Web + MQTT）
|
||
- CLI 可独立使用，不需要启动 Web 服务
|
||
- 可选 docker-compose 部署
|