Skip to content

Облако (cloud-service)

Облачный сервис, развёрнутый на https://cloud.kavlev.ru/. Делает три вещи:

  1. Удалённый доступ к платам без VPN — плата сама pull'ит команды heartbeat'ами.
  2. Расшаривание — несколько человек видят одну плату с разными ролями.
  3. OTA + интеграции с голосовыми ассистентами — то, что плата сама в одиночку не умеет.

Если ничего этого не нужно — облако можно вообще не подключать. Плата работает автономно.

Что внутри

Раздел Что в нём
Проекты Создание, API-key, инвайты
Устройства Все платы проекта, состояние, команды
Группы устройств Логическая группировка для фильтра
Участники Роли и приглашения
Интеграции OAuth-привязка к Алисе / Марусе / Салюту
Аккаунт Профиль, дефолтный проект, смена пароля

Регистрация и логин

https://cloud.kavlev.ru/login.html — вход по email + одноразовому коду:

  1. Ввести email.
  2. На почту прилетает 6-значный код, валидный 10 минут.
  3. Ввести код → выдаётся JWT.

Зарегистрироваться можно или через register.html, или через invite-токен на проект — тогда регистрация + добавление в проект одной операцией.

Архитектура

Internet ──:443──→ Caddy ──→ FastAPI :8000 ──→ Postgres :5432
                     ↑
                     :8081 ──── board-канал (plain HTTP с HMAC)
  • Caddy — reverse-proxy с auto-Let's Encrypt. Терминирует TLS, балансит между service-ами.
  • FastAPI — основной HTTP-сервер. Web UI, REST API, OAuth для голосовых ассистентов.
  • Postgres 16 — пользователи, проекты, устройства, команды, прошивки.
  • EMQX (Phase Broker) — MQTT-брокер для cloud→board команд (опционально, см. MQTT интеграцию).

Плата ходит по HTTPS на основной порт (443 снаружи, проксируется в 8000). На отдельный 8081 ходит только heartbeat-канал; разделение нужно чтобы board-трафик не мешал user-трафику и не упирался в общие rate-limits.

Production-данные

Volume Что в нём
cloud_db_data Postgres-данные. Бэкапятся отдельно (см. deploy.md в репе cloud-service).
firmware_data Бинарники прошивок (.bin + .littlefs.bin), метаданные в Postgres.
emqx_data Состояние MQTT-брокера (если используется).

Доступы и роли

Роль в проекте Что может
owner Всё + удаление проекта + смена owner'а.
admin Управление платами, командами, OTA, инвайтами, группами.
viewer Только просмотр состояния. Не может ничего нажать.

Роль выдаётся при создании инвайта; menять можно в Участниках (admin+).

Технологии

  • FastAPI 0.115 + uvicorn (async HTTP)
  • SQLAlchemy 2.0 + asyncpg (async Postgres)
  • Alembic для миграций
  • Pydantic v2 для валидации
  • JWT (HS256) для пользователей, HMAC-SHA256 для плат
  • aiomqtt для MQTT (Phase Broker)
  • aiosmtplib для email-нотификаций
  • Web UI — vanilla HTML + Bootstrap 5.3.3 + plain JS, без bundler'ов

Дальше