💻

Программная Архитектура RealIoT

Детальное описание локального и глобального серверов

📋 Общее описание

RealIoT — это платформа управления IoT-устройствами с поддержкой множественных протоколов (WiFi, Zigbee, Matter, LoRaWAN). Система работает на двух уровнях:

  • Локальный сервер (Hub) — Raspberry Pi CM4 в локальной сети пользователя
  • Глобальный сервер (Cloud) — VPS хостинг (realiot.ru) для удаленного доступа
Backend: Node.js + Express + Socket.IO
Frontend: React SPA
Database: MongoDB
MQTT: Mosquitto
Automation: Node-RED, Scenario Engine
Protocols: WiFi, Zigbee, Matter, LoRaWAN

🏠 Локальный vs ☁️ Глобальный сервер

Характеристика Локальный Сервер (Hub) Глобальный Сервер (Cloud)
Расположение Raspberry Pi CM4 в локальной сети VPS хостинг (realiot.ru)
Основные модули server.js, app.js, my_mqtt.js, socketProxy.js (клиент) global-proxy.js, MqttWebSocketBridge.js
База данных Локальная MongoDB (полная история данных) Центральная MongoDB (пользователи, метаданные)
Связь Исходящее WebSocket соединение к глобальному серверу Принимает входящие WebSocket от локальных хабов
Доступ к устройствам Прямой (Zigbee стик, LoRa шлюз, MQTT) Только через MQTT Bridge или WebSocket туннель
Сценарии Выполняются локально (автономно) Опционально (через MQTT Bridge)
Режим работы Автономный (без интернета), Подключенный (с интернетом) Всегда онлайн
Масштаб: 100%

📊 Упрощенная структура системы

graph TB subgraph "IoT Устройства" WiFi[WiFi ESP32/ESP8266] Zigbee[Zigbee Sensors/Actuators] Matter[Matter over WiFi] LoRa[LoRaWAN end Devices] end subgraph "MQTT Layer" MQTTMain[Mosquitto localhost:1883] MQTTAdd[Дополнительные MQTT брокеры] Z2M[zigbee2mqtt] end subgraph "Backend - Raspberry Pi CM4" NodeJS[Node.js + Express] MyMQTT[my_mqtt.js Central Hub] SocketIO[Socket.IO WebSocket Server] Scenarios[Scenario Engine Automation] MatterCtrl[Matter Controller] NodeRED[Node-RED Visual Logic] MyMQTT --> Scenarios MyMQTT --> SocketIO NodeJS --> MyMQTT NodeJS --> NodeRED end subgraph "Database" MongoDB[(MongoDB)] DeviceData[(devicedata Time Series)] ConfigDB[(realiotdata Config)] MongoDB --> DeviceData MongoDB --> ConfigDB end subgraph "Frontend" React[React SPA Dashboard] Widgets[Device Widgets] Charts[Time Series Charts] Settings[Settings UI] React --> Widgets React --> Charts React --> Settings end subgraph "External Services" Cloud[Global Server realiot.ru] Email[Email SMTP] SMS[SMS.ru API] Telegram[Telegram Bot] end subgraph "System Services" Avahi[Avahi mDNS realiot.local] OTA[OTA Update Service] BLE[BLE Service] end WiFi --> MQTTMain Zigbee --> Z2M Z2M --> MQTTMain Matter --> MatterCtrl LoRa --> MQTTMain MQTTAdd --> MyMQTT MQTTMain --> MyMQTT MatterCtrl --> MyMQTT MyMQTT --> DeviceData Scenarios --> ConfigDB SocketIO <--> React NodeJS --> Cloud Scenarios --> Email Scenarios --> SMS Scenarios --> Telegram style NodeJS fill:#4CAF50 style MyMQTT fill:#2196F3 style MongoDB fill:#FF9800 style React fill:#00BCD4

🏗️ 1. Backend (Node.js + Express)

🏠 Локальный сервер (Hub)

server.js — основной сервер приложения

  • Инициализация HTTP сервера
  • Настройка Socket.IO для WebSocket
  • Управление подключениями к MongoDB
  • Graceful shutdown

app.js — Express приложение

  • Middleware (CORS, body-parser, статика)
  • Роутинг API endpoints
  • Обработка mDNS имен (realiot.local)
  • Режим обслуживания (при обновлениях)

my_mqtt.js — центральный MQTT модуль

  • Подключение к основному и дополнительным MQTT брокерам
  • Обработка данных от устройств всех протоколов
  • Выполнение сценариев автоматизации
  • Сохранение истории в MongoDB
  • Синхронизация между шлюзами (топик realiot/data/json)

socketProxy.js — клиент обратного прокси для облака

  • Подключение к глобальному серверу
  • Проксирование HTTP запросов через WebSocket
  • Регистрация локального сервера по уникальному ID
  • Туннелирование трафика из интернета в локальную сеть

☁️ Глобальный сервер (Cloud)

global-proxy.js — сервер WebSocket туннелирования

  • HTTPS сервер на порту 8443 с SSL/TLS сертификатами
  • Socket.IO сервер для приема соединений от локальных хабов
  • Регистрация локальных серверов по уникальным ID
  • Проксирование HTTP запросов к зарегистрированным хабам
  • Поддержка chunked transfer для больших файлов (source maps)
  • Управление маршрутизацией: /:serverId/*

MqttWebSocketBridge.js — мост MQTT ↔ WebSocket

  • Подключение к центральному MQTT брокеру (109.70.24.215:1883)
  • Подписка на топики
  • Пересылка MQTT сообщений в WebSocket клиентам (браузеры)
  • Кэширование последних значений (до 500 записей на сервер)
  • Replay кэша при подключении нового клиента
  • Поддержка namespace-based маршрутизации (/server-ID)

API Routes

Одинаковы для локального и глобального сервера (если глобальный поддерживает прямое управление устройствами):

Масштаб: 100%

🔄 Облачный прокси (Global Proxy)

sequenceDiagram participant Browser as Браузер participant Nginx as Nginx realiot.ru participant Global as Global Server Node.js participant Proxy as socketProxy.js (Local) participant Local as localhost:5000 (Local) Note over Proxy, Global: Инициализация соединения из локальной сети Proxy->>Global: WebSocket connect (SSL) Proxy->>Global: emit register SERVER_ID Global-->>Proxy: Connection confirmed Note over Browser, Nginx: Запрос пользователя из интернета Browser->>Nginx: HTTP Request GET /server-ID/api/devices Nginx->>Global: Forward request (Reverse Proxy) Global->>Global: Find socket for SERVER_ID Global->>Proxy: emit http-request data Note over Proxy, Local: Выполнение запроса внутри локальной сети Proxy->>Local: axios url localhost:5000/api/devices Local-->>Proxy: Response 200 OK (JSON) Proxy->>Global: emit http-response data Global->>Nginx: Return response Nginx->>Browser: HTTP Response

⚛️ 2. Frontend (React SPA)

Frontend идентичен для локального и глобального доступа. Автоматически определяет контекст подключения.

Структура приложения:

frontend/src/ ├── components/ # Переиспользуемые компоненты │ ├── Dashboard.js │ ├── DeviceManager.js │ ├── AnalogInstrument.js │ ├── actuators/ # Виджеты актуаторов │ └── properties/ # Модальные окна настроек ├── pages/ # Страницы приложения │ ├── DashboardPage.js │ ├── DeviceManagerPage.js │ ├── AddScenarioPage.js │ ├── MatterConnectionPage.js │ └── ... ├── contexts/ │ ├── ThemeContext.js # Темная/светлая тема │ └── WebSocketContext.js # Socket.IO клиент └── utils/ # Утилиты

Ключевые возможности:

  • Drag-and-drop размещение устройств на фоне
  • Графики истории данных (Time Series)
  • Настройка сценариев автоматизации
  • Matter/Zigbee/WiFi/LoRa commissioning
  • Real-time обновления через WebSocket
  • Адаптивный дизайн с темной/светлой темой
Масштаб: 100%

🔌 WebSocket интеграция (Frontend ↔ Backend)

graph TB subgraph "React Components" App[App.js] Dashboard[DashboardPage] DeviceManager[DeviceManagerPage] Scenarios[AddScenarioPage] end subgraph "Context Providers" WSContext[WebSocketContext] ThemeContext[ThemeContext] end subgraph "Socket.IO Events" Connect[connect] DeviceUpdate[device-update] ScenarioDebug[scenario-debug] ApprovalReq[approval-request] AlarmTrigger[alarm-trigger] MatterStatus[matter-status] end subgraph "Backend Socket.IO" Server[Socket.IO Server] Rooms[Rooms workspace-name approval-room-id] end App --> WSContext App --> ThemeContext Dashboard --> WSContext DeviceManager --> WSContext Scenarios --> WSContext WSContext --> Connect Connect --> Server Server --> Rooms Server --> DeviceUpdate Server --> ScenarioDebug Server --> ApprovalReq Server --> AlarmTrigger Server --> MatterStatus DeviceUpdate --> Dashboard ScenarioDebug --> Scenarios ApprovalReq --> App AlarmTrigger --> App MatterStatus --> DeviceManager style WSContext fill:#FF6F00 style Server fill:#1976D2

💾 3. База данных (MongoDB)

Базы данных:

devicedata — история данных устройств

  • Коллекция data — временные ряды (timestamp, deviceSN, payload)
  • Используется для хранения исторических показаний датчиков
  • Retention policy настраивается пользователем (по умолчанию 30 дней)

realiotdata — конфигурация системы

  • workspaces — рабочие области пользователей
    • items (устройства, позиции, настройки)
    • settings (тема, фон, MQTT брокеры, retention)
  • users — пользователи системы
    • email, password (bcrypt), role (user/admin/viewer)
  • scenarios — сценарии автоматизации
    • conditions (sensor, schedule, timer, weather)
    • actions (actuator, email, SMS, telegram, alarm)
  • scenarioexecutions — история выполнения сценариев
  • decoders — декодеры LoRaWAN
  • localservicetokens — токены для внешних сервисов
Масштаб: 100%

📊 Схема базы данных

erDiagram USERS ||--o{ WORKSPACES : owns USERS { ObjectId _id string email string password enum role string resetToken date tokenExpiration } WORKSPACES ||--o{ ITEMS : contains WORKSPACES ||--o{ SCENARIOS : has WORKSPACES { ObjectId _id ObjectId userId string workspaceName bool isActive object settings array sharedWith } ITEMS { string id string name string deviceSN string deviceModel object position string type string iconSrc object payloadData array historyParameters number historyRetentionDays } SCENARIOS ||--o{ CONDITIONS : has SCENARIOS ||--o{ ACTIONS : executes SCENARIOS { ObjectId _id ObjectId userId string workspaceName string scenarioName bool isActive } CONDITIONS { enum type string name string operator string value object schedule bool useTimer } ACTIONS { enum type string name string command string deviceSN bool requiresApproval bool pwmEnabled number autoOffTimeout } DEVICEDATA { ObjectId _id string deviceSN date timestamp object payload string connectionType } SCENARIO_EXECUTIONS { ObjectId _id ObjectId scenarioId string scenarioName date executedAt array actionsExecuted number successfulActions } DECODERS { ObjectId _id string name string code bool isActive }

📮 4. MQTT Брокеры (Mosquitto)

Основной брокер (localhost:1883):

WiFi устройства:

  • realiot/data — данные от ESP32/ESP8266
  • realiot/command — команды к устройствам
  • realiot/data/json — синхронизация между шлюзами

Zigbee (zigbee2mqtt):

  • zigbee2mqtt/+ — данные от Zigbee устройств
  • zigbee2mqtt/+/set — команды к Zigbee

Matter:

  • matter/+ — данные от Matter устройств
  • matter/+/set — команды к Matter

LoRaWAN (ChirpStack):

  • application/+/# — uplink/downlink данные

Дополнительные брокеры:

📡 5. Протоколы IoT

WiFi (ESP32/ESP8266):

  • Прямое подключение к MQTT брокеру
  • JSON payload
  • Поддержка множественных каналов

Zigbee:

  • Интеграция через zigbee2mqtt (отдельный процесс)
  • Автообнаружение устройств
  • IR-коды для кондиционеров

Matter (Thread/WiFi):

  • Commissioning через BLE/QR-код
  • OnOff, Level, Color Control кластеры
  • Хранение Fabric в .simple-matter-storage/

LoRaWAN:

  • ChirpStack Application Server
  • Пользовательские декодеры payload
  • Uplink/downlink через MQTT
Масштаб: 100%

⭐ Matter Commissioning (процесс подключения)

stateDiagram-v2 [*] --> Idle Idle --> BLE_Scan: Start commissioning BLE_Scan --> QR_Detected: Matter device found QR_Detected --> Pairing: Parse QR code Pairing --> Network_Config: Send WiFi credentials Network_Config --> Commissioning: Device connected Commissioning --> Fabric_Association: Add to Fabric Fabric_Association --> Storage: Save to .simple-matter-storage Storage --> MQTT_Bridge: Subscribe to matter/+ MQTT_Bridge --> Active: Device commissioned Active --> Control: Send commands Control --> MQTT_Bridge: Publish to matter nodeId set Active --> Decommission: Remove device Decommission --> Storage: Delete from storage Decommission --> [*] BLE_Scan --> Idle: Timeout 30s Pairing --> Error: Failed Network_Config --> Error: WiFi failed Commissioning --> Error: Timeout Error --> Idle: Retry

🔧 6. Дополнительные сервисы

Node-RED:

  • Визуальное программирование
  • Embedded mode (встроен в Express)
  • UI доступен по /red
  • API endpoints: /api/red
  • Аутентификация через MongoDB Users

Avahi (mDNS):

  • Автообнаружение в локальной сети
  • <servername>.local
  • Автоприменение имени

OTA Updates:

  • update_service.sh — скачивание и применение обновлений
  • rollback_service.sh — откат на предыдущую версию
  • Lock-файлы (/tmp/realiot-update.lock)
  • Graceful mode (503 страница)

🎯 7. Система автоматизации

Сценарии (Scenarios)

Условия (Conditions):

  • sensor — значение датчика (==, !=, >, <, >=, <=)
  • schedule — расписание (weekly/monthly, fromHour-untilHour)
  • timer — периодический запуск (seconds/minutes)
  • delay — задержка выполнения
  • weather — погодные условия (current/dayAhead)
  • manual — ручной запуск

Действия (Actions):

  • actuator — управление устройствами
    • PWM (ШИМ) — периодическое включение/выключение
    • Auto-off таймер
  • radio/musicPlayer — управление мультимедиа
  • email — отправка email (Nodemailer)
  • sms — отправка SMS (sms.ru API)
  • telegram — отправка в Telegram Bot
  • alarm — звуковое оповещение
  • scenario — вызов другого сценария

Дополнительные возможности:

  • Логическая связка условий (AND/OR)
  • Модальное окно для подтверждения действий
  • Debounce для датчиков (защита от дребезга)
  • Mutex для предотвращения конфликтов параллельных процессов
  • История выполнения (ScenarioExecution)
Масштаб: 100%

⚙️ Движок сценариев (Scenario Engine)

graph LR subgraph "Триггеры Conditions" Sensor[Sensor value == threshold] Schedule[Schedule weekly monthly] Timer[Timer periodic] Weather[Weather forecast data] Manual[Manual button press] end subgraph "Логика" Eval[Condition Evaluator] Logic[AND OR Logic] Mutex[Scenario Mutex] end subgraph "Действия Actions" ActuatorCmd[Actuator on off toggle] PWM[PWM periodic control] Email[Email notification] SMS[SMS notification] TG[Telegram message] Alarm[Alarm sound] SubScenario[Call Scenario] end subgraph "История" ExecLog[ScenarioExecution MongoDB] ActivityLog[Activity Log devicedata] end Sensor --> Eval Schedule --> Eval Timer --> Eval Weather --> Eval Manual --> Eval Eval --> Logic Logic --> Mutex Mutex --> ActuatorCmd Mutex --> PWM Mutex --> Email Mutex --> SMS Mutex --> TG Mutex --> Alarm Mutex --> SubScenario ActuatorCmd --> ExecLog Email --> ExecLog SMS --> ExecLog TG --> ExecLog Alarm --> ExecLog ActuatorCmd --> ActivityLog style Mutex fill:#FF5722 style ExecLog fill:#9C27B0

🛠️ 8. Утилиты (Backend)

Ключевые модули в папке /utils:

🔄 Потоки данных

1. Данные от IoT устройств → MongoDB

Устройство → MQTT Broker → my_mqtt.js → devicedataCollection → Socket.IO → Frontend → Сценарии автоматизации

2. Команды к устройствам

Frontend → Socket.IO → my_mqtt.js → MQTT publish → Устройство

3. Синхронизация между шлюзами

Шлюз A → MQTT (realiot/data/json) → Шлюз B → MongoDB

4. Облачный доступ

Браузер → realiot.ru (Nginx) → global-proxy.js → socketProxy.js → localhost:5000
Масштаб: 100%

📊 Детальный поток данных (Data Flow)

sequenceDiagram participant Device as IoT Устройство participant MQTT as MQTT Broker participant MyMQTT as my_mqtt.js participant Cache as Device Cache participant DB as MongoDB participant Scenarios as Scenario Engine participant WS as Socket.IO participant Frontend as React UI Device->>MQTT: Publish data MQTT->>MyMQTT: Message received MyMQTT->>MyMQTT: Parse payload JSON or LoRa decoder MyMQTT->>MyMQTT: Determine protocol WiFi Zigbee Matter LoRa MyMQTT->>Cache: Update cache Cache-->>MyMQTT: OK MyMQTT->>DB: Save to devicedata debounce 1.5s DB-->>MyMQTT: Saved MyMQTT->>Scenarios: Check triggers Scenarios->>Scenarios: Evaluate conditions alt Conditions met Scenarios->>Scenarios: Execute actions Scenarios->>MQTT: Send commands Scenarios->>DB: Log execution end MyMQTT->>WS: Emit device-update WS->>Frontend: Update UI Frontend->>Frontend: Render new data

🔐 Безопасность

1. Аутентификация:

  • JWT токены (httpOnly cookies)
  • Bcrypt хеширование паролей
  • Role-based access (user/admin/viewer)

2. MQTT:

  • Без аутентификации (локальная сеть)
  • Настраиваемые credentials для внешних брокеров

3. Matter:

  • WiFi credentials только из environment variables
  • Fabric encryption (Matter стандарт)

4. API:

  • CORS с whitelist
  • authMiddleware для защищенных endpoints

🚀 Deployment

Hardware (Локальный сервер):

  • Raspberry Pi CM4
  • 4 GB RAM
  • 32 GB eMMC

Software Stack:

  • Ubuntu Server 20.04 LTS
  • Node.js 18+
  • MongoDB
  • Mosquitto MQTT
  • Avahi daemon
  • PM2 process manager

OTA Updates:

# Update process /scripts/update_service.sh → Download from realiot.ru → Backup current version → npm install → npm run build → pm2 restart # Rollback /scripts/rollback_service.sh → Restore backup → pm2 restart

📈 Масштабируемость

1. MongoDB Connection Pooling:

  • maxPoolSize: 10
  • minPoolSize: 2

2. MQTT Client Management:

  • Основной + множественные дополнительные брокеры
  • Автопереподключение

3. Caching:

  • Device data cache (in-memory)
  • Workspace activity cache
  • Last values cache (MqttWebSocketBridge, до 500 записей)

4. Debouncing:

  • Device updates (1.5s)
  • Activity log (2s)

📧 info@reallab.ru | 📞 +7 (495) 26-66-700

← Назад к справке