Об этом проекте

CloudPath — это self-hosted платформа управления IoT, которую можно запускать локально или развертывать в публичной сети. Ее цель — создать универсальный уровень управления для «подключения устройств, мониторинга состояния и удаленного контроля», а не быть специализированным ПО для конкретной платы разработки. Проект открыт под лицензией MIT и состоит из трех основных частей: центрального сервиса cloudpath-server (одиночный бинарный файл), шлюза cloudpath-edge, работающего на каждом компьютере или узле, и командного инструмента cloudpath для управления реестром плагинов. Технологический стек: Go на бэкенде, React на фронтенде (WebUI вшит в сервер), база данных SQLite в режиме WAL, что позволяет осуществлять кросс-компиляцию для Linux или arm64 без использования CGO. Разделение полномочий Центральный сервис является единственным авторитетом в вопросах желаемого состояния, арендаторов и аудита. Он отвечает за RBAC, токены, ограничение частоты запросов (rate limiting), сроки хранения, реестр плагинов, экземпляры их запуска, а также за отправку команд и учет подтверждений. Шлюз является единственным авторитетом в вопросах наблюдаемого состояния: он хранит последний успешно примененный снимок (snapshot), осуществляет надзор за устройствами, повторные попытки подключения с экспоненциальной задержкой и буферизацию событий офлайн. При разрыве связи шлюз продолжает работу, а при переподключении применяет только финальный снимок, не воспроизводя промежуточные побочные эффекты. Идентификация устройства определяется тройкой «арендатор, шлюз, устройство», а ключом передачи данных является комбинация edge_id и device_id. В рамках сессии аккаунта связь от шлюза к серверу и далее в браузер осуществляется через WebSocket, а REST используется для исторических запросов и операций управления. Система плагинов Проект разделяет плагины на три типа: Driver (по умолчанию работают на стороне шлюза, отвечают за обнаружение устройств, соединение, парсинг протоколов, маппинг возможностей и действия устройств); Application (работают на стороне центрального сервиса, отвечают за бизнес-объекты, привязки, правила, задачи и доменные API); Connector (планируются к запуску на шлюзе или сервере для уведомлений и вывода данных через MQTT, Webhook и т.д., на данный момент находятся в статусе целевого состояния). Ядро системы не содержит кода для конкретного оборудования — новое устройство добавляется как плагин Driver. Эталонные драйверы (например, stcb) и приложения публикуются в отдельных репозиториях, где предоставляются шаблоны Go-плагинов, примеры приложений и инфраструктура для E2E-тестирования от бинарного файла до хоста. Перед установкой плагина проверяются Manifest, диапазон совместимости, активы Release и контрольные суммы, а версия, дайджест и источник записываются в lock-файл. Быстрый старт После установки Go, Node, pnpm и (опционально) task, команда task setup загружает зависимости, а task build генерирует два бинарных файла. Сервер по умолчанию слушает 127.0.0.1:8080 и предоставляет эндпоинт /healthz для проверки состояния. При отсутствии оборудования можно использовать встроенный demo-адаптер для проверки подключения устройств, выполнения операций и переподключения. Для работы с реальными COM-портами необходимо установить соответствующий плагин Driver, включить plugin_host в локальном edge.yaml и указать порт и адаптер. После создания первой учетной записи администратора сервис переходит в режим авторизации: все интерфейсы, кроме проверки здоровья, статических ресурсов и API аутентификации, требуют учетных данных. Панель управления После входа доступны: обзор, список и детали устройств, журнал выполнения (события), приложения и плагины с деталями экземпляров, список и детали шлюзов, настройки. Для администраторов предусмотрены страницы участников, прав и токенов доступа. Панель управления на странице устройства генерирует кнопки на основе белого списка, объявленного адаптером; также можно отправлять команды через API и запрашивать поток событий и статус шлюза. Статусы операций: pending, sent, ok, failed, timeout. Операции без подтверждения в течение длительного времени помечаются фоновой задачей как тайм-аут. События и финальные статусы операций хранятся по умолчанию 30 дней. Безопасность В README уровни поверхности атаки разделены на L0 (одиночная машина), L1 (внутренняя сеть или reverse proxy) и L2 (публичная сеть), с предупреждением не выставлять конфигурацию L0 напрямую в интернет. Предусмотрено два режима учетных данных: общие токены сервиса (для совместимости) и режим аккаунтов с сессионными cookie, тремя ролями (admin, operator, viewer) и токенами арендаторов с префиксом cp_. Область действия (scope) токена может быть подмножеством read, write, admin, edge. Открытый текст токена возвращается один раз при создании, в базе хранятся только SHA-256 и короткий префикс. Секреты в конфигурациях сервера и аудите представлены в виде хендлов secret://name; расшифровка происходит локально на целевом шлюзе провайдером. Плагины должны явно заявлять о правах в manifest; сервер не хранит и не пересылает секреты в открытом виде. Также реализованы белые списки операций, ограничения длины параметров и символов, лимиты на тело запроса и чтение WebSocket, защита от path traversal в SPA, ограничение частоты операций и входа, а также набор защитных HTTP-заголовков. Развертывание и подключение нескольких шлюзов Официальное руководство по развертыванию в публичной сети без контейнеров включает: проверку архитектуры (матрица релизов включает Linux arm64), запуск сервиса через systemd от имени специального не-root пользователя, хранение секретов в файле окружения с правами 0600 и использование nginx в качестве reverse proxy для HTTPS и WSS (с отдельной настройкой заголовков Upgrade и увеличенным таймаутом чтения). Аутентификация осуществляется самим продуктом, прокси-слой остается открытым. Контейнеры и Compose также поддерживаются, но архитектура хоста должна совпадать с образом. Типовой сценарий — подключение нескольких компьютеров к одному серверу: администратор создает токены с scope edge для каждого компьютера, передает пользователю WSS-эндпоинт, токен и согласованный edge_id. Пользователь скачивает бинарный файл, проверяет его по checksums, настраивает локальный конфиг и запускает шлюз. Шлюз поддерживает переподключение с экспоненциальной задержкой, а события офлайн попадают в ограниченный буфер и воспроизводятся после восстановления связи. Устройства, события и операции разных арендаторов изолированы; сбой одного шлюза не влияет на другие. Тестирование и релизы Тестирование охватывает Unit-тесты Go, проверку на race condition, заморозку зависимостей и проверку типов фронтенда, процесс шаблонов плагинов и агрегированные команды гейт-контроля. Релизы триггерятся тегами версий, запуская сборку для шести платформ и генерацию единого файла checksums. В репозитории также есть скрипты для аудита публичных границ, проверки ссылок в Markdown и структуры workflow. Текущие ограничения В README четко разделены текущее состояние и целевое: Connector и среда выполнения уведомлений, интеграция MQTT и Modbus, удаленный OTA, агрегация временных рядов, централизованное управление ключами, распределенные квоты и поддержка нескольких серверов еще не реализованы. Сессии токенов арендаторов работают только через REST (без WebSocket в браузере). Также не завершена проверка E2E для сценариев, когда один внешний драйвер управляет несколькими реальными платами с учетом их переподключения и подтверждения операций. Принцип проекта: «не описывать нереализованные возможности как существующие».