FieldDB
Обзор
FieldDB — платформа для сбора и анализа гиперлокальных данных с датчиков окружающей среды. Она принимает телеметрию погодных станций и узлов контроля качества воздуха, хранит временные ряды и показывает измерения владельцам устройств и посетителям публичной карты.
В отличие от спутниковых или усреднённых городских данных, FieldDB работает с показаниями конкретных наземных устройств. Платформа объединяет регистрацию оборудования, API приёма данных, аналитические графики и управляемую публикацию станций.
Возможности продукта
Система предоставляет:
- Регистрацию устройств и выпуск отдельных API-ключей
- Пакетную загрузку измерений погоды и качества воздуха
- Защиту от повторной записи одного измерения
- Статусы устройств: online, stale и offline
- Графики и таблицы за периоды от одного часа до 30 дней
- Метрики температуры, влажности, давления, PM2.5, PM10, ветра, осадков и точки росы
- Сводный дашборд с количеством устройств, последней синхронизацией и предупреждениями
- Публичную карту станций, для которых владелец включил публикацию
- Интерфейс на английском, испанском, немецком и русском языках
Открытая карта не возвращает точные координаты устройства. Перед публикацией местоположение преобразуется в geohash с ограниченной точностью, а внешний API отдаёт центр этой области.
Архитектура
FieldDB построен как monorepo и включает:
- Веб-приложение на Next.js
- API на Hono с документацией OpenAPI
- PostgreSQL с расширением TimescaleDB для временных рядов
- Prisma для схемы данных и миграций
- Better Auth для веб-сессий
- Keycloak как OIDC-провайдер
- BFF-маршруты в веб-приложении для обращения к API
- Google Maps для публичной карты станций
- Общий пакет со структурированным логированием и константами приложения
Измерения хранятся в hypertable TimescaleDB. API поддерживает как получение исходных точек, так и агрегацию по временным интервалам. Ключ устройства показывается пользователю один раз, а в базе сохраняется только его SHA-256-хеш.
Инфраструктура и SRE
Для проекта реализованы:
- GitLab CI с lint, type-check, сборкой, тестами и аудитом зависимостей
- Сборка контейнеров через Kaniko
- Отдельные образы веб-приложения, API, мигратора и темы Keycloak
- Health checks для API и веб-приложения
- SonarQube-проверки качества
- Renovate для обновления зависимостей
- Структурированные JSON-логи в production
- Локальное окружение с TimescaleDB и Keycloak через Testcontainers
- GitOps-деплой с отдельной задачей миграции базы данных
- Ограничение времени жизни кеша сборок и очистка старых образов registry
Миграции не запускаются вместе с API. Для них существует отдельный образ, предназначенный для Kubernetes Job перед обновлением приложения. Такой порядок уменьшает риск одновременного запуска миграции несколькими экземплярами API.
Инженерные задачи
В FieldDB пересекаются задачи потоковой телеметрии, аутентификации и защиты местоположения устройств:
- Идемпотентный приём пакетов до 500 измерений
- Хранение и агрегация временных рядов в TimescaleDB
- Безопасный выпуск и хранение ключей устройств
- Разделение приватных данных владельца и публичного представления станции
- Снижение точности координат перед публикацией на карте
- Корректная работа OAuth callback с локализованными маршрутами
- Передача Google Maps-ключей на этапе сборки и настройка разрешённых referrer
- Внутреннее получение веб-сессии без обращения к публичному TLS-маршруту из того же pod
- Выполнение миграций до развёртывания новой версии API
В результате один контур обслуживает владельцев устройств и подробные измерения, а другой публикует только явно разрешённые станции и географически обезличенные координаты.