Server Inventory: телеметрия и контроль доступа для golauncher

Server Inventory — продакшн-хаб для системы агентов golauncher: централизованный репозиторий для сбора телеметрии, управления релизами и трёхуровневого контроля доступа над флотом развёрнутых серверных агентов. Необычное здесь вот что: нет ни сервера телеметрии, ни базы данных, ни API. Бэкендом целиком выступает сам GitHub. GitHub Actions обрабатывает события телеметрии, Fine-Grained Personal Access Tokens задают уровни доступа, а бинарные релизы доставляются через GitHub Releases с проверкой SHA-256.

В этой статье — как это работает на практике, какие именно данные отдаёт каждый агент, как устроена трёхуровневая модель доступа и механизм авто-обновления, и — что не менее важно — где этот подход перестаёт работать и когда его применять не стоит.

Архитектура: GitHub как инфраструктура

Система построена на нестандартном, но рабочем принципе: репозиторий и есть база данных, история Git и есть журнал аудита, а доступностью и масштабированием занимается сама инфраструктура GitHub. Это сознательное разделение ответственности — репозиторий server-inventory только для продакшна: в нём лежат данные телеметрии, бинарные релизы и метаданные версий, но нет исходного кода. Исходники агента живут в отдельном репозитории, а токены доступа и конфигурации клиентов вообще не попадают в хаб — они остаются на каждой машине.

Это разделение важно для безопасности. Утечка продакшн-хаба раскрывает операционную телеметрию, но не логику, которая её собирает, и не учётные данные, которые её авторизуют. Заодно репозиторий остаётся маленьким и аудируемым: каждое изменение — это коммит, каждое обновление телеметрии атрибутируемо, а откат — операция Git, а не миграция базы.

Пайплайн телеметрии по шагам

Когда агент отчитывается, поток полностью событийный и не требует ни одного постоянно работающего сервиса:

1. Агент golauncher открывает GitHub Issue, неся телеметрию в виде json-блока, с меткой telemetry.
2. Workflow GitHub Actions срабатывает на issues: [opened], но выполняется только если у issue есть метка telemetry — дешёвый декларативный фильтр.
3. Короткий шаг на Python извлекает JSON между ограничителями ```json, парсит его и определяет имя отчитывающегося хоста.
4. Workflow пишет полезную нагрузку в telemetry/<hostname>.json, перегенерирует telemetry/dashboard.md, коммитит оба файла и закрывает issue — всё автоматически.

В результате получается самоподдерживающийся дашборд флота без единого сервера, который надо патчить. Раннер Actions эфемерный, права урезаны (contents: write, issues: write) ровно до того, что нужно задаче, а битая полезная нагрузка громко падает в логе workflow, а не тихо портит базу.

Server Inventory: что отдаёт каждый агент

Полезная нагрузка телеметрии — плоский, намеренно компактный JSON-документ. Каждый агент сообщает:

• Идентичность — server_name, hostname и стабильный host_id
• Платформа — os и architecture
• Доступность — external_ip
• Ёмкость — disk_free_gb, disk_total_gb, disk_used_percent
• Инвентарь — список applications установленных инструментов, каждый закреплён за своей Git-версией (commit)
• Происхождение — report_timestamp, тип event, номер github_issue и серверная отметка processed_at

Последнее поле — applications с Git-версиями — тихая рабочая лошадка. Оно превращает хаб в общефлотовый перечень ПО (software bill of materials): в любой момент я отвечаю на вопрос «на каких серверах старая сборка такого-то инструмента?» простым grep по каталогу telemetry/, без обращения к агентам. Флот сейчас охватывает активные хосты на Linux и Windows, а авто-генерируемый дашборд показывает, какие серверы живы, когда они в последний раз отчитывались и что на них установлено.

Трёхуровневый контроль доступа

Доступ клиентов управляется через Fine-Grained Personal Access Tokens на трёх уровнях — так один хаб обслуживает внутренних, бесплатных и платных клиентов без отдельной инфраструктуры:

• Уровень 1 (Admin) — полный доступ ко всем репозиториям, включая платные инструменты, для внутренних серверов и отладки
• Уровень 2 (Free) — доступ только к бесплатным репозиториям, например linux-network-manager
• Уровень 3 (Paid) — полный доступ, включая платные инструменты вроде rocketchat-deploy-toolkit

Два решения держат это управляемым. Первое — ссылки на токены идут через косвенность (ref:tokens/level-2-v1), поэтому ротация токена — это правка одного файла, а не перенастройка каждого клиента. Апгрейд клиента с бесплатного на платный — одна правка в YAML. Второе — контроль задвоен: сам Fine-Grained PAT ограничивает токен Уровня 2 репозиториями без топика paid, и вдобавок агент независимо проверяет список allowed_repos перед тем, как что-либо клонировать. Ошибочно выданный токен не превратится тихо в эскалацию привилегий, потому что агент откажется от репозиториев, которые его уровню видеть не положено.

Управление релизами и авто-обновление

Обновления идут через единый источник правды: releases/version.json. В нём — последняя версия, дата релиза и, для каждой пары платформа/архитектура, URL загрузки и контрольная сумма SHA-256. golauncher собирается под Linux (amd64, arm64), Windows (amd64) и macOS (amd64, arm64); каждый бинарь кросс-компилируется и хешируется.

Агенты опрашивают этот файл, сравнивают объявленную версию со своей и сами обновляются, когда появляется новая сборка — проверяя скачанный бинарь по опубликованному SHA-256 перед подменой. Контрольная сумма и есть якорь доверия: хотя бинарники отдаются из GitHub Releases по HTTPS, агент никогда не запустит загрузку, чей хеш не совпал с манифестом. Это делает путь обновления устойчивым к подмене без отдельной инфраструктуры подписи.

Почему GitHub, а не Prometheus или база данных?

Честный ответ — уместность, а не догма. Для флота примерно из 10–50 серверов, которые отчитываются на check-in, а не стримят метрики, связка Prometheus/Grafana или хостируемая time-series база — это больше механики, чем заслуживает задача: ещё один сервис, который надо держать, защищать, бэкапить и оплачивать. GitHub уже даёт API, хранилище, вычисления (Actions), контроль доступа (Fine-Grained PAT) и журнал аудита (история Git) — и для приватного репозитория всё это без дополнительной платы.

Чем я жертвую — реальным временем. Это система инвентаризации и check-in, а не конвейер метрик: она отвечает на «что у меня во флоте и здоров ли каждый хост на момент последнего отчёта?», а не «что делает CPU прямо сейчас?». Для такого вопроса задержка цикла «issue плюс Actions» не имеет значения.

Где подход перестаёт работать

Использование GitHub как бэкенда имеет реальные пределы, и делать вид, что их нет, было бы нечестно:

• Потолок масштаба. Минуты Actions и лимиты API щедры для десятков серверов и беспощадны для тысяч. После нескольких сотен часто отчитывающихся агентов выигрывает специализированный сервис приёма данных.
• Не в реальном времени. Обработка события занимает от секунд до минуты. Всё, что требует субсекундных алертов, — это уже полноценный мониторинг-стек.
• Приватность — на вас. В телеметрии есть хостнеймы и внешние IP, поэтому репозиторий обязан оставаться приватным — публичный хаб стал бы бесплатной картой разведки вашего флота. Это самое важное эксплуатационное правило всей конструкции.
• Привязка к вендору. Система завязана на доступность и продуктовые решения GitHub. Для личного флота или СМБ это приемлемый размен, для того, что должно пережить сбой провайдера, — меньше.

В этих рамках размен отличный: почти нулевая операционная стоимость, полный журнал аудита бесплатно и на один сервис меньше, который надо поднимать в 3 часа ночи.

Исходный код

Репозиторий и исходники агента доступны по запросу — свяжитесь со мной для доступа. Как Fractional CTO я строю лёгкую инфраструктуру, которая опирается на существующие платформы вместо их переизобретения; эта система — сознательный пример такого подхода. Для консалтинга по управлению серверами и DevOps за плечами 15 лет работы с инфраструктурой в 38 странах.

FAQ

Почему телеметрия через GitHub Issues, а не база данных?

Нулевая стоимость инфраструктуры и бесплатный журнал аудита. GitHub даёт API, хранилище, обработку (Actions), контроль доступа и доступность; история Git фиксирует каждое изменение. Для флота из 10–50 серверов, отчитывающихся на check-in, это проще и надёжнее, чем держать отдельный стек телеметрии — при условии, что репозиторий остаётся приватным.

Как работает ротация токенов?

Токены подключаются через косвенность (ref:tokens/level-2-v1). Для ротации создаёте новый токен, сохраняете его как новый файл версии, обновляете ссылку и помечаете старый токен истёкшим. Клиенты разрешают ссылку при старте, поэтому изменение распространяется без правки конфигураций каждого клиента.

Какие платформы поддерживает golauncher?

Linux (amd64, arm64), Windows (amd64) и macOS (amd64, arm64). Бинарники кросс-компилируются и публикуются с контрольными суммами SHA-256 в releases/version.json, которые агенты проверяют перед применением обновления.

Могут ли бесплатные клиенты получить платные репозитории?

Нет. Fine-Grained PAT ограничивают токены Уровня 2 репозиториями без топика paid, и агент независимо проверяет allowed_repos перед клонированием. Два контроля держат границу, даже если один настроен неверно.

Масштабируется ли это до сотен и тысяч серверов?

Не комфортно. Минуты GitHub Actions и лимиты API подходят для десятков серверов; после нескольких сотен часто отчитывающихся агентов лучше выделенный сервис приёма данных. Этот дизайн оптимизирован под низкие эксплуатационные накладные на малых и средних флотах, а не под безграничный масштаб.

Нужна консультация?

Если вам нужна профессиональная экспертиза — запишитесь на бесплатную 15-минутную консультацию.