Flaree Agent
Agent — один статический бинарник (.NET NativeAOT) на хосте клиента: без рантайма, без зависимостей, с минимумом конфигурации. Он выполняет проверки, собирает логи и метрики и отправляет всё в бэкенд только исходящим HTTPS. Эта страница описывает его жизненный цикл: от регистрации до автообновления.
Регистрация
При старте агент читает конфигурацию (приоритет: env-переменные > CLI-флаги > agent.yaml > значения по умолчанию) и вызывает POST /api/agent/register. В ответ он получает свой идентификатор и требования к версии. Два сценария завершают процесс сразу:
- токен невалиден — агент завершается с кодом
77, рестарт бесполезен до замены токена; - версия ниже
minimumVersionсервера — код78, нужно обновление бинарника.
После успешной регистрации агент сохраняет state.json в рабочей директории. Токен туда не пишется — только его SHA-256 хеш.
Рабочий цикл
- Синхронизация конфига — каждые 30 секунд агент запрашивает
GET /api/agent/configи получает декларативный список заданий: что проверять, с какими интервалами и таймаутами. Никакого произвольного кода с сервера не приходит. - Планировщик — выполняет проверки по расписанию, до 50 параллельно (настраивается через
max_concurrent_checks). - Отправка результатов — результаты копятся в буфере и уходят батчами. При ошибке сети или
5xxагент повторяет с экспоненциальным backoff, ничего не теряя. - Heartbeat — раз в минуту агент отправляет версию, uptime и метрики процесса. По heartbeat дашборд определяет, что агент жив.
Буфер
Буфер защищает результаты проверок при недоступности бэкенда. Два режима:
| Режим | Как включить | Поведение |
|---|---|---|
| In-memory кольцевой | по умолчанию | Быстрый, теряется при рестарте |
| SQLite-буфер (WAL) | persistent_buffer: true | Хранится в buffer_path (/var/lib/flaree-agent), переживает рестарт |
После восстановления связи агент дошлёт накопленное. На 429 quota_exceeded он ждёт согласно заголовку Retry-After — подробности в квотах и retention.
Автообновление
Каждые 6 часов агент запрашивает манифест https://get.flaree.ru/agent/manifest.json, сравнивает версии и при необходимости обновляется: скачивает бинарник, сверяет SHA-256, делает бэкап текущего и выполняет атомарный rename, затем перезапускается через service manager.
Если версия агента ниже minimumVersion из манифеста, обновление выполняется принудительно — даже при FLAREE_AGENT_AUTO_UPDATE=false. Так парк не застревает на версиях с известными проблемами.
Канал обновлений задаётся переменной FLAREE_AGENT_UPDATE_CHANNEL (stable или beta). Если service manager недоступен и агент не может перезапустить себя сам, он завершается с кодом 79 — обновление применено, нужен ручной рестарт.
Коды выхода
| Код | Ситуация | Что делать |
|---|---|---|
0 | Штатная остановка | — |
77 | Токен невалиден (сервер вернул 401) | Заменить токен, рестарт без замены бесполезен |
78 | Версия ниже minimumVersion или ошибка валидации конфига | Обновить бинарник или исправить конфиг |
79 | Обновление применено, service manager недоступен | Перезапустить сервис вручную |
Локальные порты
Все слушающие сокеты агента привязаны только к 127.0.0.1 — валидация не даст указать внешний адрес:
| Порт | Назначение |
|---|---|
9090 | Prometheus-метрики агента (/metrics) |
9091 | Локальный heartbeat-приёмник |
4318 | OTLP receiver, если включён |