# node_mqtt_server

**Repository Path**: frank-xhh/node_mqtt_server

## Basic Information

- **Project Name**: node_mqtt_server
- **Description**: 基于node的iot基座
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-10
- **Last Updated**: 2025-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 物联网数据处理服务

基于 Express + TypeScript 的物联网设备数据处理服务，支持 MQTT 消息消费和 InfluxDB 数据存储。

## 功能特性

- 🚀 **Express + TypeScript**: 现代化的 Node.js 服务端架构
- 📡 **MQTT 集成**: 支持物联网设备数据接收和指令下发
- 📊 **InfluxDB 存储**: 时序数据库存储设备数据
- 🔒 **安全中间件**: 集成 Helmet、CORS 等安全防护
- 📝 **完整类型定义**: TypeScript 类型安全
- 🔄 **自动重连**: MQTT 和数据库连接自动重连机制
- 🚦 **请求限流**: API 请求频率限制
- 📋 **数据验证**: 请求参数验证中间件

## 项目结构

```
src/
├── config/          # 配置文件
├── controllers/     # 控制器:负责处理具体的业务逻辑
├── middlewares/      # 中间件：负责请求拦截、校验、日志、错误处理等
├── routes/          # 路由定义：组合控制器和中间件
├── services/        # 业务服务层：封装具体的业务逻辑和数据操作
│   ├── MqttService.ts      # MQTT 服务
│   ├── InfluxService.ts    # InfluxDB 服务
│   └── DataProcessor.ts    # 数据处理服务
├── models/           # 数据模型：定义数据库Schema、ORM
├── types/           # TypeScript 类型定义
├── utils/           # 工具函数
├── app.ts           # Express 应用配置
└── index.ts         # 应用入口
```

## 快速开始

### 方式一：使用自动化脚本（推荐）

```bash
# 1. 运行一键初始化脚本（会自动创建.env文件）
./setup.sh

# 2. 启动开发服务器
pnpm dev
```

### 方式二：手动安装

### 1. 安装依赖

```bash
pnpm install
```

### 2. 环境配置

复制环境变量模板文件：

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置你的环境变量：

```env
# 服务器配置
PORT=3000
NODE_ENV=development

# MQTT 配置
MQTT_BROKER_URL=mqtt://localhost:1883
MQTT_CLIENT_ID=iot_data_processor
MQTT_USERNAME=
MQTT_PASSWORD=

# InfluxDB 配置
INFLUX_URL=http://localhost:8086
INFLUX_TOKEN=your_influx_token_here
INFLUX_ORG=your_org
INFLUX_BUCKET=iot_data

# 日志配置
LOG_LEVEL=info
```

### 3. 启动服务

开发模式：
```bash
pnpm dev
```

生产模式：
```bash
pnpm build
pnpm start
```

## API 接口

### 健康检查
- `GET /health` - 服务健康状态检查

### 设备管理
- `GET /api/devices` - 获取设备列表
- `GET /api/devices/:deviceId/data` - 获取设备最新数据
- `GET /api/devices/:deviceId/stats` - 获取设备统计信息
- `POST /api/devices/:deviceId/commands` - 向设备发送指令

## MQTT 主题约定

### 订阅主题（设备上报）
- `devices/{deviceId}/data` - 设备数据上报
- `devices/{deviceId}/status` - 设备状态上报  
- `devices/{deviceId}/alarm` - 设备告警上报

### 发布主题（指令下发）
- `devices/{deviceId}/commands` - 向设备发送指令

## 数据格式

### 设备数据上报格式
```json
{
  "temperature": 25.6,
  "humidity": 60.2,
  "timestamp": 1634567890000
}
```

### 指令下发格式
```json
{
  "command": "set_temperature",
  "data": {
    "target": 26.0
  },
  "timestamp": 1634567890000
}
```

## 开发指南

### 添加新的数据处理逻辑

在 `src/services/DataProcessor.ts` 中扩展 `processMessage` 方法：

```typescript
async processMessage(message: MqttMessage): Promise<void> {
  // 你的自定义数据处理逻辑
}
```

### 添加新的API接口

1. 在 `src/controllers/` 中创建控制器
2. 在 `src/routes/` 中定义路由
3. 在 `src/app.ts` 中注册路由

### 扩展数据验证

在 `src/middlewares/validation.ts` 中添加新的验证中间件。

## 项目初始化脚本

### setup.sh 脚本说明

项目根目录下的 `setup.sh` 是一个自动化初始化脚本，用于快速设置和验证项目环境。

#### 脚本功能

1. **依赖检查与安装**
   - 自动检测 `node_modules` 目录是否存在
   - 如果不存在，自动运行 `pnpm install` 安装所有依赖包

2. **环境配置文件创建**
   - 检查 `.env` 文件是否存在
   - 如果不存在，自动创建包含默认配置的 `.env` 文件
   - 提供完整的环境变量模板

3. **TypeScript 编译验证**
   - 执行 `pnpm build` 编译 TypeScript 代码
   - 验证项目代码是否存在语法错误或类型错误

4. **环境配置指导**
   - 提供详细的配置说明和提示
   - 列出关键环境变量的配置要求

5. **使用说明展示**
   - 显示所有可用的 npm 脚本命令
   - 提供 API 端点的访问地址
   - 提供快速启动命令

#### 使用方法

```bash
# 给脚本添加执行权限（首次使用）
chmod +x setup.sh

# 运行初始化脚本
./setup.sh
```

#### 脚本输出示例

```
🚀 启动物联网数据处理服务...
🔧 创建环境配置文件...
✅ 已创建 .env 配置文件
🔨 编译TypeScript...
✅ 编译成功!
🌟 项目已准备就绪!

📋 可用命令:
  pnpm dev     - 开发模式启动
  pnpm start   - 生产模式启动
  pnpm build   - 编译项目

🔧 配置说明:
  请编辑 .env 文件配置你的环境变量
  - MQTT_BROKER_URL: MQTT代理地址
  - INFLUX_URL: InfluxDB地址
  - INFLUX_TOKEN: InfluxDB访问令牌

🌐 API端点:
  http://localhost:3000/health - 健康检查
  http://localhost:3000/api/devices - 设备列表

🚀 快速启动:
  ./setup.sh && pnpm dev
```

#### 适用场景

- **新环境部署**: 快速在新服务器或开发环境中初始化项目
- **CI/CD 流水线**: 作为自动化部署流程的一部分
- **团队协作**: 为新加入的开发者提供一键式环境设置
- **项目验证**: 在代码提交前验证项目完整性

## 部署建议

1. **环境变量**: 生产环境中请妥善配置所有必要的环境变量
2. **数据库**: 确保 InfluxDB 服务正常运行
3. **MQTT Broker**: 确保 MQTT 代理服务可访问
4. **监控**: 建议添加日志监控和性能监控
5. **安全**: 配置防火墙和访问控制

## 许可证

ISC