# ventilator

**Repository Path**: harry1990/ventilator

## Basic Information

- **Project Name**: ventilator
- **Description**: 呼吸机物联网平台项目，前端使用Vue框架，后端使用flask框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-08
- **Last Updated**: 2025-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 物联网设备管理平台

基于Web的物联网设备管理系统，实现设备的实时监控和配置管理。系统通过MQTT协议与设备通信，实时展示设备在线状态。

## 项目特性

- ✅ 实时监控设备在线/离线状态
- ✅ 友好的设备管理界面
- ✅ 支持设备配置和参数修改
- ✅ MQTT协议通信
- ✅ 心跳机制自动检测设备状态
- ✅ 设备日志和心跳历史记录
- ✅ 统计数据和可视化展示
- ✅ Docker容器化部署

## 技术栈

### 后端
- **语言**: Python 3.11
- **框架**: Flask 3.0
- **数据库**: MongoDB 7.0
- **MQTT Broker**: EMQX 5.4
- **其他**: APScheduler (定时任务)

### 前端
- **框架**: Vue 3
- **UI库**: Element Plus
- **状态管理**: Pinia
- **图表**: ECharts
- **构建工具**: Vite

## 项目结构

```
呼吸机/
├── backend/                 # 后端代码
│   ├── api/                # API接口
│   │   ├── devices.py     # 设备管理接口
│   │   └── config.py      # 配置接口
│   ├── app.py             # Flask应用主入口
│   ├── config.py          # 配置管理
│   ├── database.py        # 数据库连接
│   ├── models.py          # 数据模型
│   ├── mqtt_client.py     # MQTT客户端
│   ├── requirements.txt   # Python依赖
│   └── Dockerfile         # Docker镜像
├── frontend/              # 前端代码
│   ├── src/
│   │   ├── api/          # API封装
│   │   ├── layout/       # 布局组件
│   │   ├── views/        # 页面组件
│   │   ├── stores/       # 状态管理
│   │   ├── router/       # 路由配置
│   │   └── utils/        # 工具函数
│   ├── package.json      # NPM依赖
│   ├── vite.config.js    # Vite配置
│   └── Dockerfile        # Docker镜像
├── scripts/              # 脚本文件
│   ├── init-mongo.js    # MongoDB初始化脚本
│   ├── test_device.py   # 设备模拟器
│   └── emqx_auth.conf   # EMQX认证配置
├── docker-compose.yml    # Docker编排
├── 需求文档.md           # 需求文档
├── 设备端MQTT协议文档.md # 协议文档
└── README.md            # 项目说明
```

## 快速开始

### 方式一：Docker Compose（推荐）

1. **克隆项目**
```bash
git clone <repository-url>
cd 呼吸机
```

2. **启动所有服务**
```bash
docker-compose up -d
```

3. **访问服务**
- 前端界面: http://localhost:3000
- 后端API: http://localhost:5000
- EMQX Dashboard: http://localhost:18083 (admin/public)
- MongoDB: localhost:27017

4. **查看日志**
```bash
# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f frontend
```

5. **停止服务**
```bash
docker-compose down
```

### 方式二：本地开发

#### 1. 准备环境

确保已安装：
- Python 3.11+
- Node.js 18+
- MongoDB 7.0+
- EMQX 5.4+

#### 2. 后端配置

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

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境 (Windows)
venv\Scripts\activate

# 激活虚拟环境 (Linux/Mac)
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 复制配置文件
copy .env.example .env

# 编辑.env文件，配置数据库和MQTT连接信息
# 注意：.env.example文件创建失败，请手动创建.env文件

# 启动后端服务
python app.py
```

**.env 文件配置示例：**
```env
FLASK_ENV=development
FLASK_DEBUG=True
SECRET_KEY=your-secret-key

MONGODB_HOST=localhost
MONGODB_PORT=27017
MONGODB_DB=iot_platform
MONGODB_USERNAME=
MONGODB_PASSWORD=

MQTT_BROKER_HOST=localhost
MQTT_BROKER_PORT=1883
MQTT_USERNAME=iot_client
MQTT_PASSWORD=iot_password_2025

HEARTBEAT_INTERVAL=60
HEARTBEAT_TIMEOUT_MULTIPLIER=2
HEARTBEAT_TIMEOUT_OFFSET=30
```

#### 3. 前端配置

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

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

访问 http://localhost:3000

#### 4. 配置EMQX

访问 EMQX Dashboard (http://localhost:18083)，配置认证：

1. 登录 Dashboard (admin/public)
2. 进入 "访问控制" -> "认证"
3. 创建认证器，选择 "Built-in Database"
4. 添加用户：
   - Username: `iot_client`
   - Password: `iot_password_2025`

## 测试设备连接

使用提供的设备模拟器测试系统：

```bash
# 安装依赖
pip install paho-mqtt

# 运行设备模拟器
python scripts/test_device.py device_001 --host localhost --port 1883 --interval 60

# 参数说明：
# device_001: 设备ID
# --host: MQTT Broker地址
# --port: MQTT端口
# --interval: 心跳间隔(秒)
```

设备模拟器会：
1. 连接到MQTT Broker
2. 立即发送第一个心跳
3. 按照设置的间隔定时发送心跳
4. 在平台上可以看到设备上线和心跳记录

## MQTT协议说明

### 连接参数
- **服务器地址**: localhost (或配置的地址)
- **端口**: 1883 (TCP) / 8883 (TLS)
- **ClientID**: `device_{deviceId}` (每个设备唯一)
- **Username**: `iot_client` (统一)
- **Password**: `iot_password_2025` (统一)
- **Keep Alive**: 60秒

### 心跳主题
- **主题格式**: `/iot/{deviceId}/heartbeat`
- **方向**: 设备 → 平台
- **QoS**: 1

### 心跳消息格式
```json
{
  "status": "online"
}
```

### 心跳机制
- 设备连接成功后立即发送第一个心跳
- 之后按照心跳间隔（默认60秒）定时发送
- 平台在超时时间（默认150秒）内未收到心跳将标记设备为离线
- 超时时间计算：`心跳间隔 × 2 + 30秒`

## API接口文档

### 设备管理

#### 获取设备列表
```
GET /api/devices
参数:
  - status: 状态筛选 (all/online/offline)
  - search: 搜索关键词
  - page: 页码
  - pageSize: 每页数量
```

#### 获取设备详情
```
GET /api/devices/{deviceId}
```

#### 添加设备
```
POST /api/devices
Body:
{
  "deviceId": "device_001",
  "deviceName": "测试设备",
  "ipAddress": "192.168.1.100"
}
```

#### 更新设备
```
PUT /api/devices/{deviceId}
Body:
{
  "deviceName": "新名称",
  "ipAddress": "192.168.1.101"
}
```

#### 删除设备
```
DELETE /api/devices/{deviceId}
```

#### 获取统计信息
```
GET /api/devices/stats
```

#### 获取设备日志
```
GET /api/devices/{deviceId}/logs
参数:
  - eventType: 事件类型 (online/offline/config)
  - page: 页码
  - pageSize: 每页数量
```

#### 获取心跳历史
```
GET /api/devices/{deviceId}/heartbeats
参数:
  - page: 页码
  - pageSize: 每页数量
```

### 系统配置

#### 获取系统配置
```
GET /api/config
```

#### 健康检查
```
GET /api/health
```

## 数据库说明

### devices 集合（设备表）
```javascript
{
  deviceId: String,           // 设备ID（唯一）
  deviceName: String,         // 设备名称
  status: String,             // 状态 (online/offline)
  lastOnlineTime: Date,       // 最后上线时间
  lastHeartbeatTime: Date,    // 最后心跳时间
  ipAddress: String,          // IP地址
  createdAt: Date,           // 创建时间
  updatedAt: Date            // 更新时间
}
```

### heartbeat_logs 集合（心跳日志表）
```javascript
{
  deviceId: String,          // 设备ID
  timestamp: Date,           // 时间戳
  payload: Object            // 心跳数据
}
```

### device_logs 集合（设备日志表）
```javascript
{
  deviceId: String,          // 设备ID
  eventType: String,         // 事件类型 (online/offline/config)
  message: String,           // 日志信息
  timestamp: Date            // 时间戳
}
```

## 常见问题

### 1. MQTT连接失败
- 检查EMQX是否正常运行
- 检查认证信息是否正确
- 检查防火墙是否开放1883端口

### 2. 设备无法上线
- 确认设备使用正确的ClientID格式：`device_{deviceId}`
- 确认心跳主题格式正确：`/iot/{deviceId}/heartbeat`
- 确认心跳消息格式正确（JSON格式）

### 3. MongoDB连接失败
- 检查MongoDB是否正常运行
- 检查连接字符串是否正确
- 检查用户权限是否正确

### 4. 前端无法访问后端API
- 检查后端是否正常运行
- 检查Vite代理配置是否正确
- 检查CORS配置是否正确

## 性能指标

- 支持至少1000个设备同时在线
- 设备状态更新延迟不超过3秒
- 页面响应时间不超过2秒
- 心跳处理能力：每秒至少500条消息

## 安全建议

1. **生产环境**：
   - 修改默认密码
   - 启用MQTT SSL/TLS加密
   - 配置防火墙规则
   - 启用MongoDB认证
   - 使用环境变量管理敏感信息

2. **MQTT认证**：
   - 为每个设备配置独立的认证信息
   - 定期更新密码
   - 使用ACL控制主题访问权限

3. **数据安全**：
   - 定期备份数据库
   - 启用日志审计
   - 限制API访问频率

## 维护和监控

### 日志管理
- 后端日志：`backend/iot_platform.log`
- Docker日志：`docker-compose logs`

### 数据清理
系统会自动清理旧数据：
- 心跳日志保留7天
- 设备日志保留30天

### 监控指标
- 设备在线率
- MQTT连接状态
- 心跳消息处理延迟
- 数据库连接状态

## 开发团队

本项目基于需求文档和MQTT协议文档开发，符合物联网设备管理的最佳实践。

## 许可证

MIT License

## 更新日志

### v1.0.0 (2025-10-08)
- ✅ 初始版本发布
- ✅ 实现设备管理基础功能
- ✅ 实现MQTT通信和心跳机制
- ✅ 实现前端展示界面
- ✅ 实现Docker容器化部署

## 技术支持

如有问题或建议，请查看：
- 需求文档：`需求文档.md`
- 协议文档：`设备端MQTT协议文档.md`