Heimdallr — это высокопроизводительное, отказоустойчивое и легковесное программное решение корпоративного класса, предназначенное для мониторинга, администрирования и безопасного управления узлами удаленного доступа на базе ядер Xray-core.
Платформа сочетает в себе строгую серверную архитектуру (Clean Architecture, CQRS) и передовой интерфейс с прецизионной логикой анимаций (XState v5, Scene-Based Video Streaming), обеспечивая беспрецедентный уровень DX и UX.
Система осуществляет изоляцию трафика, защиту конечных точек в агрессивных средах передачи данных и предоставляет администраторам инструменты контроля сетевой активности в режиме реального времени.
Современная концепция мобильной и гибридной работы идет рука об руку с критическим расширением площади атаки на уровне сетевой инфраструктуры. Разработка комплекса Heimdallr обусловлена тремя фундаментальными уязвимостями традиционных каналов связи:
При инициации сетевых сессий из неконтролируемых публичных или полуоткрытых сетей (общественные Wi-Fi точки доступа в транспортных узлах, отелях и коворкингах) передаваемые данные подвергаются прямому риску перехвата.
- Направления угроз: Использование злоумышленниками уязвимостей недорогого маршрутизационного оборудования, подмена ARP-таблиц (ARP Спуффинг) и компрометация DNS-запросов (DNS серверы, подстроенные выдавать фишинговые страницы) прямо на локальном шлюзе.
- Проблема мобильных точек доступа: Использование сотового модема смартфона защищает исключительно путь до базовой станции оператора. Оно не обеспечивает сквозного шифрования (End to End шифрования) до целевого сервера, делает трафик прозрачным для DPI-систем провайдера и накладывает ограничения в виде разделяемого динамического IP-адреса, блокирующего авторизацию в закрытых корпоративных сетях.
Популярные открытые панели управления сетевыми шлюзами (например, решения типа 3X-UI) обладают рядом архитектурных недостатков, препятствующих их эксплуатации в жестко ограниченных или коммерческих инфраструктурах:
- Высокий оверхед: Использование интерпретируемых языков (Python/PHP) создает избыточную нагрузку на CPU и память, делая невозможным деплой на сверхлегкие или бюджетные VPS-серверы (≈<1GB RAM).
- Монолитная архитектура: Прямое совмещение интерфейса управления и ядра маршрутизации расширяет вектор атаки на систему. Отсутствие независимых Out-of-band способов аутентификации снижает общую отказоустойчивость контура безопасности перед тем же банальным брутфорсом.
Инфраструктура Heimdallr полностью переносит точку выхода пользовательского трафика из неконтролируемой и агрессивной среды локального провайдера в изолированную, доверенную среду выделенного сервера, размещенного в защищенном дата-центре под юрисдикцией строгих политик обработки данных уровня энтерпрайз масштаба. На магистральном уровне (дата-центр - целевой ресурс) безопасность сессий дополнительно гарантируется ведущими провайдерами и сквозными TLS-протоколами.
Комплекс Heimdallr представлен не как "доступ к прокси", а как законченная сквозная услуга — Managed Security Service (Безопасность как сервис).
Конечные пользователи (инженеры, аналитики, топ-менеджмент) получают доступ к защищенному шлюзу по принципу "по одному нажатию" непосредственно через интерфейс Telegram-бота. Вся рутинная настройка криптографических ключей, генерация конфигурационных файлов и выбор маршрутов автоматизированы на стороне бэкенда. Клиент платит за предельную автоматизацию и удобство развертывания персонального шлюза на любом устройстве за секунды.
Для ИТ-специалистов и финансистов критически важно обладание статическим выделенным IP-адресом. Доступ к промышленным базам данных, облачной инфраструктуре разработки и банковским аккаунтам в enterprise-сегменте жестко ограничен "белыми списками" по IP. Heimdallr гарантирует неизменность сетевого адреса пользователя независимо от его фактического географического местоположения.
Небольшие распределенные команды и студии (до 15-30 человек) получают полноценный эквивалент корпоративного шлюза безопасности без необходимости содержания команды системных администраторов. Через веб-интерфейс руководитель или уполномоченный сферы безопасности в реальном времени контролирует:
- Списки активных сессий сотрудников.
- Аномальные всплески или падения трафика, способные сигнализировать о скрытом сливе корпоративных данных или компрометации рабочего места.
- Оперативное управление доступом (блокировка/разблокировка учетных записей в один клик).
Стримеры, профессиональные киберспортсмены и создатели высоконагруженного контента нуждаются в сокрытии своего реального домашнего IP-адреса для предотвращения направленных DDoS-атак, способных сорвать трансляции или игровой процесс. Использование Heimdallr выносит периметр защиты наружу: весь деструктивный трафик принимает на себя удаленный шлюз, который может быть мгновенно перезапущен или пересоздан автоматикой бэкенда, в то время как основная физическая линия связи пользователя остается полностью стабильной.
Проект спроектирован с упором на максимальную автономность, экономичность ресурсов и простоту эксплуатации в продакшн-окружениях (VPS/VDS малого и среднего масштаба).
В отличие от классических веб-приложений, требующих развертывания сложной инфраструктуры (Node.js-сервер для фронтенда, отдельный веб-сервер Nginx для раздачи статики, менеджеры процессов вроде PM2 и внешняя СУБД), Heimdallr компилируется в один монолитный бинарный файл.
Как работает: Весь фронтенд на Next.js компилируется в статическое представление, оптимизируется и интегрируется в Go-приложение. Сервер на Go самостоятельно осуществляет и обработку API-запросов и высокоскоростную отдачу статических UI из указанной директории (STATIC_DIR).
В качесвте преимуществ можно выделить полноценную атомарность обновлений (для деплоя новой версии достаточно заменить один файл), отсутствие внешних рантайм-зависимостей и минимальное потребление дискового пространства.
- Асинхронный Пул Воркеров (
Pipeline+Bouncer): Процесс сбора статистики и выполнения блокирующих системных операций (например, изоляция/блокировка пользователей в конфигурации Xray) полностью изолирован от основного потока обработки API-запросов. Если API-запрос или сетевой стек Xray-core начинает задерживать ответы, внутренний буферPipelineсглаживает пики нагрузки. При переполнении буфера (>100 задач) защитный механизмBouncerкорректно дропает избыточные задачи с логгированием, исключая падение приложения по нехватке памяти (изза OOM-киллера). - Изоляция СУБД: Использование SQLite обеспечивает локальное хранение данных без накладных расходов на межпроцессное взаимодействие (IPC). Механизм работы СУБД ограничен одним соединением на запись, что гарантирует полную консистентность и защищает базу данных от дедлоков при конкурентном доступе.
- Отказоустойчивость медиа-менеджмента: Архитектура фронтенда защищена от сбоев сетевого API. В случае недоступности эндпоинта
/api/media/assetsкомпонентMediaManagerавтоматически переключается на локальные статические fallback-пути, сохраняя визуальную целостность интерфейса.
- Потребление памяти: Менее 15 МБ RAM в режиме штатной эксплуатации.
- InMemory(RAM) Кэширование: Механизм
PresenceCacheудерживает данные об онлайне пользователей в оперативной памяти с автоматической инвалидацией (30 секунд), что радикально снижает количество дисковых IO операций чтения из SQLite.
- Интеграция с Telegram Bot в качестве доверенного канала доставки одноразовых паролей (OTP).
- Защита от перебора, timing-атак и раскрытия учетных записей перебором за счет использования constant-time (утилит спец. библиотек) алгоритмов сравнения хэшей и строк при валидации токенов.
UNIQUE INDEXна уровне СУБД гарантирует наличие только одного активного OTP для администратора в единицу времени. Новый запрос мгновенно инвалидирует предыдущий.
- NotifIsland (Островок уведомлений): Компонент навигационной панели, управляемый конечным автоматом Мура и Мили на базе XState v5. Он реализует концепцию декларативного менеджмента состояний анимаций. Сложные переходы (расширение, смена контента, интерактивное схлопывание) математически просчитаны, предсказуемы и изолированы от побочных эффектов React-рендеринга.
Рис.1 - Схема переходов и состояний XState для NotifIsland
Нажмите, чтобы посмотреть все основные стадии навигационного меню
Рис.2 - Набросок стадий навигационного меню
- Scene-Based видео архитектура: Вместо ленивой загрузки медиа-ресурсов при переходе между страницами,
VisualOrchestratorвыполняет предзагрузку (pre-loading) всех видео-сцен (landing,auth,data) на этапе инициализации приложения. Переключение между экранами происходит мгновенно (0 мс задержки), без мерцания интерфейса и повторного декодирования видео процессором.
Иерархия каталогов отражает разделение зон ответственности согласно парадигме Чистой Архитектуры:
.
├── cmd/
│ └── heimdallr/ # Точка входа (Entrypoint) Go-приложения, инициализация систем
├── internal/ # Изолированная бизнес-логика (Domain & Use Cases)
│ ├── api/ # Маршрутизация, HTTP-эндпоинты и Middleware-слои сервера
│ ├── bot/ # Логика Telegram-бота (генерация OTP, нотификации)
│ ├── collector/ # Ядро сбора метрик: Pipeline, Bouncer, PresenceCache
│ ├── db/ # Слой доступа к данным (Data Access Layer), запросы к SQLite
│ ├── metrics/ # Сбор и агрегация внутренних системных метрик
│ ├── models/ # Общесистемные структуры данных и доменные модели
│ └── xray/ # Клиент взаимодействия с API управления Xray-core
├── configs/ # Конфигурационные файлы среды разработки и продакшена
├── data/ # Локальные персистентные хранилища (SQLite DB)
├── docs/ # Техническая документация, архитектурные схемы (Draw.io)
├── postman/ # Наборы интеграционных тестов (Collections/Environments)
├── web/ui/ # Исходный код фронтенд-приложения (Next.js, TypeScript)
│ ├── src/app/ # Маршрутизация Next.js (App Router)
│ ├── src/components/ # Компоненты UI (auth, dashboard, layout)
│ ├── src/lib/ # Клиентские оркестраторы и менеджеры (media-manager, etc.)
│ └── src/store/ # Менеджеры состояний (Zustand, XState-интеграция)
├── Makefile # Глобальный сценарий автоматизации сборки проекта
├── frontend-Makefile # Изолированный сценарий автоматизации фронтенда
└── package.json # Конфигурация Node.js зависимостей сборщика статики
Внутренняя структура программного комплекса спроектирована по принципам слабой связанности (Loose Coupling) и высокой внутренней связности (High Cohesion). Архитектура строго разделена на изолированные слои девайсов, бизнес-логики и персистентности, что исключает появление перекрестных или циклических зависимостей между внутренними Go-пакетами.
Рис.3 - Схема общей архитектуры проекта
Центральный HTTP-интерфейс приложения, функционирующий на базе высокопроизводительного маршрутизатора-фреймворка Echo. Модуль инкапсулирует в себе две изолированные бизнес-логики:
- Аутентификация, авторизация и верификация сессий: Обработка первичной регистрации, валидация учетных данных, координация двухфакторной аутентификации (2FA) через сквозной опрос (Polling) и сверку OTP-кодов с Telegram-платформой, а также последующая эмиссия криптографически подписанных JWT-токенов.
- Обеспечение целостности данных (Data Provisioning): Предоставление унифицированных REST-эндпоинтов (
/api/stats,/api/history) для нужд веб-интерфейса, а также обработка транзакционных административных операций над сущностями пользователей.
Архитектурные паттерны:
- Инверсия зависимостей: Сервер полностью абстрагирован от конкретных реализаций слоев хранения данных и внешних API. Проектирование опирается исключительно на интерфейсы (
StatsProvider,HistoryProvider,UserStore,SessionStore), что обеспечивает высокую тестируемость (Unit Testing через Mock-структуры) и модульную заменяемость. - Разделение уровней авторизации (Двухуровневая система аутентфиикации): В системе реализована гибридная схема контроля доступа. Веб-клиент взаимодействует с системой посредством динамических короткоживущих JWT-токенов, в то время как внешняя служебная инфраструктура и DevOps-скрипты автоматизации авторизуются через выделенные статические API-ключи (Bearer Tokens) с фиксированными привилегиями.
Специализированный узел, функционирующий по принципу Out-of-Band (внешней) узла. Он изолирован от основного сетевого интерфейса веб-приложения и обеспечивает независимый контур безопасности и двухфакторной авторизации.
Функциональные обязанности модуля:
- Криптографическая привязка (Binding) уникального идентификатора Telegram-аккаунта к учетной записи локального веб-пользователя.
- Генерация и защищенная доставка одноразовых паролей (OTP) в режиме реального времени.
- Интерактивное подтверждение активных сессий входа с использованием системных команд (включая обработку параметров команды
/start). - Асинхронная доставка критических системных нотификаций и алармов безопасности (например, оповещения о принудительной блокировке за превышение лимитов).
Архитектурное ограничение: Модуль
internal/botреализует паттерн «Чистый уведомляющий элемент» (Pure Notifier). Пакет не содержит бизнес-логики, не принимает решений о состоянии системы и не коммуницирует с базой данных напрямую. Любое входящее событие транслируется в управляющий слой API Server или Collector, что предотвращает размытие зон ответственности.
Высокопоточный движок, отвечающий за непрерывный сбор телеметрии, агрегацию сетевых метрик и оперативное реагирование на инциденты утилизации ресурсов.
Представляет собой долгоживущий демон (фоновый Worker), активируемый по сигналам внутреннего таймера. В рамках каждого итерационного тика (каждые
- Извлекает полный реестр активных пользователей из слоя персистентности (БД).
- Инициализирует gRPC-сессию с ядром маршрутизации Xray-core и запрашивает актуальные счетчики входящего/исходящего трафика.
- Осуществляет вычисление дельты сетевой активности и выполняет потокобезопасное обновление оперативного кэша
PresenceCache. - Сбрасывает агрегированные исторические срезы данных в хранилище для построения ретроспективных графиков.
- Выполняет предикативный анализ лимитов: если суммарный объем трафика пользователя превышает жестко заданный лимит, генерирует структурированную задачу на компрометацию доступа и направляет её в асинхронный
Pipeline.
Специализированная структура данных, размещенная непосредственно в оперативной памяти (RAM) процесса для обеспечения субмиллисекундного времени отклика (Low Latency).
-
Синхронизация: Архитектура базируется на примитиве
sync.RWMutex, что гарантирует бесконфликтное параллельное конкурентное чтение от множества потоков API-сервера при одновременной монопольной записи со стороны Collector. -
Логика определения статуса Online: Статус
onlineвычисляется динамически на основе математического анализа приращения объема трафика ($\Delta \text{Traffic} > 0$ ) за фиксированный скользящий интервал времени (последние 10 секунд). -
Изоляция ресурсов: Наличие
PresenceCacheполностью изолирует веб-клиентов и API-интерфейсы от прямого обращения к gRPC-интерфейсам Xray-core. Панель мониторинга мгновенно считывает готовое состояние из оперативной памяти бэкенда, снижая нагрузку на маршрутизатор до нуля.
Подсистема гарантированной обработки тяжелых инфраструктурных событий и применения карательных политик (Enforcement Policies) без деградации общей производительности приложения.
Реализует классический паттерн Worker Pool (Пул воркеров) с фиксированным числом параллельных горутин (по умолчанию: 3 активных воркера) и строго ограниченной буферизованной очередью каналов Go. Используется для полной изоляции основного потока выполнения Collector от ресурсоемких Side-Effect операций с непредсказуемым временем отклика (I/O задержки при обновлении конфигураций на диске, внешние сетевые вызовы к API мессенджеров).
Узкоспециализированный вышибала сессий, вызываемый воркерами пула Pipeline. Компонент функционирует строго атомарно и выполняет три последовательных шага:
- Модифицирует статус пользователя в базе данных (перевод в состояние
Blocked). - Инициирует мутацию конфигурации ядра Xray-core, физически удаляя идентификаторы пользователя (Inbound правила) из рантайма, тем самым мгновенно разрывая текущие сетевые сессии.
- Генерирует событие блокировки и передает его в модуль
internal/botдля отправки уведомления.
Преимущества связки Collector -> Pipeline -> Bouncer:
- Неблокирующий цикл мониторинга: Сбой или задержка при удалении пользователя из сетевого ядра или отправке уведомления в Telegram никак не влияет на таймер сбора статистики - сбор метрик продолжается без изменений.
- Идемпотентность операций: Повторные или дублирующие задачи на блокировку одного и того же пользователя безопасно поглощаются Bouncer без нарушения консистентности системы.
- Устойчивость к каскадным сбоям: Падение или зависание внешних сетевых зависимостей (например, недоступность серверов Telegram API) остается внутри пула воркеров. Буфер очереди защищает приложение от утечек памяти (OOM) и гарантирует стабильную работу Core-функционала.
Рис.4 - Схема общения компонентов приложения в процессе авторизации и
аутентификации
Для работы приложения в корневой директории необходимо создать файл .env. Ниже представлены параметры конфигурации с разделением по целевому назначению:
APP_ENV: Режим работы приложения (development/production).API_PORT: Сетевой порт для Go REST API (например,3000).APP_PORT: Сетевой порт для раздачи фронтенд-сервера в режиме разработки (3001).
DB_PATH: Путь к файлу базы данных SQLite (например,data/heimdallr.db).STATIC_DIR: Путь к директории скомпилированного статического фронтенда в production (out).LOCAL_STATIC_DIR: Локальный путь к исходникам скомпилированной статики фронтенда (web/ui/out).
JWT_SECRET: Секретный ключ криптографической подписи сессионных JWT-токенов.API_ADMIN_TOKEN: Токен для мастер-доступа к административным эндпоинтам API.ADMIN_EMAIL: Идентификатор (Email/Username) администратора системы.
TG_BOT_TOKEN: Уникальный API-токен Telegram-бота, выданный BotFather.TG_ADMIN_ID: Числовой ID аккаунта администратора в Telegram для отправки OTP.
XRAY_API_ADDR: Сетевой адрес gRPC API управляемого узла Xray (127.0.0.1:10085).COLLECT_INTERVAL: Частота опроса метрик трафика из Xray-core (например,5s).CLIENT_TUNNEL_PORT/SERVER_TUNNEL_PORT: Конфигурационные порты для SSH-туннелей мониторинга.
SSH_HOST/SSH_PORT/SSH_DEPLOY_USER: Параметры удаленного сервера для деплоя.SSH_DEPLOY_USER_KEY: Путь к приватному SSH-ключу для автоматической авторизации на сервере.API_PORT: Порт с которого будет обеспечиваться доступ к приложению
Управление жизненным циклом приложения, кодогенерацией и процедурами верификации инкапсулировано в унифицированном файле Makefile. Автоматизация спроектирована с учетом изоляции зависимостей в монорепозитории и минимизации накладных расходов при сетевом взаимодействии с удаленными узлами.
-
Контроль окружения (.env): Сценарий автоматически считывает локальные переменные среды из файла
.envв корне проекта, экспортируя их в рантайм вызываемых команд. При отсутствии явного указанияLOCAL_STATIC_DIRсистема прозрачно переключается на безопасный fallback-путь (./web/ui/out). -
Статическая компиляция Go бинарника: Флаг
CGO_ENABLED=0полностью отключает динамическое связывание с системными библиотеками C (glibc), гарантируя стопроцентную переносимость бинарного файла между различными дистрибутивами Linux. Использование флагов компилятора-trimpathудаляет из результирующего файла абсолютные пути файловой системы разработчика (для безопасности), а-ldflags="-s -w"полностью вырезает таблицы символов и отладочную информацию (DWARF), снижая вес исполняемого файла более чем на 40%. -
Изоляция NPM-скриптов в Монорепозитории: При вызове
make ui-installиспользуется строгий набор флагов--ignore-scripts --include=dev. Это критически важно для предотвращения конфликтов хуков (как, например, Husky) и зацикливания жизненных циклов сборки, так как в корне репозитория и в подкаталогеweb/uiнаходятся независимые конфигурацииpackage.json. Флаг--include=devгарантирует установку зависимостей сборщика (devDependencies) Next.js.
Сложная интеграция с механизмами ядра Xray-core (в частности, подсистемами proxyman и command) требует актуального состояния gRPC-заглушек на стороне Go-бэкенда.
- Таргет
make proto: осуществляет проверку присутствия компилятораprotocи плагинов генерации Go-кода (protoc-gen-go,protoc-gen-go-grpc). При успешной валидации компилирует файлыcommand.protoиconfig.protoиз директории./api/protoв целевой пакет./internal/xray/proto. - Механизм контроля состояния (.stamp): Для оптимизации повторных сборок используется сигнальный файл
.stamp. Компиляция запускается повторно только в случае физического изменения исходных.protoфайлов. - Строгая верификация (
make proto-verify): Используется на этапе CI. Команда проверяет, что сгенерированный код не имеет локальных диффов (git diff --quiet) и полностью синхронизирован с репозиторием, исключая рассинхронизацию интерфейсов на продакшене.
Для проверки корректности сборки в режиме Single Binary (когда фронтенд должен полностью раздаваться Go-сервером автономно) реализован таргет локальной изоляции:
- Полностью очищаются старые артефакты.
- Собирается чистый статический экспорт фронтенда и Go-бинарник.
- В директории
./bin/test_isolation/создается изолированный контекст, куда копируется бинарный файл, локальный.envи ассеты фронтенда. - Выполняется запуск приложения из этой папки. Данный шаг гарантирует, что бэкенд не завязывается на пути разработки (
web/ui/out) и корректно инициализирует встроенный или локальный файловый сервер в абсолютной изоляции.
Сценарий позволяет безопасно верифицировать изменения на реальном продакшн-сервере, не затрагивая стабильную работающую версию платформы.
[Локальная машина] [Удаленный Сервер]
│ │
├─ 1. Сборка проекта │
├─ 2. tar -czf ui_bundle.tar.gz (Упаковка ассетов 110MB) │
├─ 3. scp бинарника -> /tmp/heimdallr-test │
├─ 4. scp ui_bundle.tar.gz -> /tmp/ │
│ ├─ 5. Распаковка в /tmp/out
│ ├─ 6. Экспорт рабочего .env
│ ├─ 7. nohup на Порту 4000
│ │ (Процесс изолирован)
- Быстрая передача артефактов: Передача скомпилированного фронтенда Next.js (объемом ~110 МБ с учетом статических медиа-ресурсов) напрямую через
scpв виде отдельных файлов неэффективна из-за сетевых накладных расходов на каждый кусок. Система упаковывает ассеты в единый сжатый архивui_bundle.tar.gz, передает его за один сетевой стрим, атомарно распаковывает на удаленной стороне в/tmp/outи производит очистку за собой. - Изоляция процессов: Тестовый бинарник копируется под именем
heimdallr-test. Он запускается в фоновом режиме через утилитуnohup(чтобы процесс не терминировался при закрытии SSH-сессии) на альтернативном выделенном порту — 4000 (API_PORT=4000), переопределяя переменные из продакшн-файла окружения/var/www/heimdallr/.env. - Безопасный доступ (
make tunnel-test): Тестовое окружение на порту 4000 не открывается во внешний мир через брандмауэр сервера. Доступ к нему осуществляется через безопасный локальный SSH-туннель: порт4000удаленного сервера маппится наlocalhost:4000разработчика. - Атомарная очистка (
make stop-test): Команда находит по имени процесса и терминирует тестовый экземпляр (heimdallr-test), а также полностью вычищает директорию/tmp/от временных файлов конфигураций и логов, исключая засорение дискового пространства сервера.
| Команда | Зона ответственности | Описание и побочные эффекты |
|---|---|---|
make setup |
Инициализация | Первичная настройка окружения: скачивание зависимостей Go, установка Node-модулей и активация git-хуков. |
make build |
Сборка (Full) | Полный цикл: компиляция статического фронтенда Next.js и сборка монолитного Go-бинарника. |
make go-build |
Сборка (Backend) | Компиляция исключительно Go-кода бэкенда с применением оптимизаций -trimpath и -ldflags. |
make ui-build |
Сборка (Frontend) | Сборка статического продакшн-экспорта веб-интерфейса через npm workspaces. |
make dev |
Разработка | Запуск локального Go-сервера бэкенда с одновременной инициализацией SSH-туннеля к Xray-core. |
make tunnel |
Сеть | Открытие фонового SSH-туннеля для проброса gRPC API статистики Xray (CLIENT_TUNNEL_PORT -> SERVER_TUNNEL_PORT). |
make proto |
Кодогенерация | Компиляция gRPC/Protobuf контрактов Xray-core в структуры языка Go с проверкой тулчейна. |
make proto-verify |
Валидация (CI) | Строгая проверка актуальности закоммиченного gRPC-кода. Завершается ошибкой, если код не обновлен. |
make test-backend |
Тестирование | Запуск стандартного пакета unit-тестов бэкенда. |
make test-race |
Тестирование | Запуск unit-тестов бэкенда с включенным детектором состояний гонки (go test -race). |
make prod-check |
Валидация | Запуск собранного бинарника в полностью изолированной локальной папке для тестирования стабильности Single Binary. |
make deploy-test |
Тестирование (Host) | Сборка, архивация, отправка и запуск изолированной тестовой версии на удаленном сервере (Порт 4000, режим nohup). |
make tunnel-test |
Сеть | Проброс порта 4000 удаленного тестового окружения на локальную машину разработчика. |
make stop-test |
Очистка (Host) | Остановка тестового процесса heimdallr-test на сервере и удаление всех временных файлов из /tmp. |
make stop |
Очистка (Local) | Остановка всех локальных фоновых процессов бэкенда и активных SSH-туннелей мониторинга. |
make clean |
Очистка (Local) | Полное удаление директорий сборки (/bin), кэша Next.js (/.next) и статических экспортов (/out). |
make db-reset |
Инфраструктура | Физическое удаление локального файла базы данных SQLite (data/heimdallr.db) для чистого перезапуска системы. |
Автоматизация деплоя стабильных версий платформы в продакшн-окружение реализована с помощью GitHub Actions через конфигурационный файл воркфлоу Deploy: Heimdallr Service.
- Триггеры запуска: Воркфлоу активируется автоматически при создании и публикации Git-тега, соответствующего семантическому версионированию
v*.*.*(например,v1.0.0). Также предусмотрен ручной запуск конвейера через интерфейс GitHub (workflow_dispatch) для внепланового обновления конфигураций. - Защита от гонок (Concurrency Control): Настроен блок
concurrencyс флагомcancel-in-progress: trueдля группыdeploy-heimdallr. Это гарантирует, что если разработчик ошибочно опубликует два тега подряд или запустит ручной деплой во время выполнения предыдущего, старая цепочка задач будет немедленно и безопасно закончена на стороне GitHub. Это исключает состояние гонки (race conditions) при обновлении бинарного файла на конечном сервере.
Конвейер деплоя состоит из изолированных этапов, гарантирующих стабильность целевой системы на каждом шаге доставки.
Выполняется в изолированном контейнере ubuntu-latest (так как для GH actions это быстрее, чем искать четкую версию):
- Инициализация рантайма: Разворачивается актуальная среда Go 1.25.x с включенным автоматическим кэшированием модулей для ускорения последующих запусков.
- Этап автоматического контроля качества (Юнит-тестирование): Перед началом компиляции принудительно выполняются все тесты бэкенда (
go test ./cmd/... ./internal/...). Любое падение теста мгновенно останавливает конвейер и предотвращает деплой сломанного кода. - Компиляция артефакта продакшн-уровня: Выполняется кросс-компиляция статического бинарного файла под целевую архитектуру целевого сервера (
GOOS=linux GOARCH=amd64 CGO_ENABLED=0) с флагами оптимизации размера и безопасности (-trimpath -ldflags="-s -w"). Скомпилированный файл временно сохраняется в артефакты сборки GitHub (heimdallr-binary).
(Примечание: На следующем шаге конвейера происходит интеграция собранного статического экспорта UI во встроенные структуры бэкенда либо доставка в директорию STATIC_DIR удаленного хоста).
После завершения процессов сборки и физической доставки артефактов на целевой сервер (путь установки: /var/www/heimdallr/heimdallr), GitHub Actions инициализирует удаленный сеанс через SSH-экшен (appleboy/ssh-action) для финального ввода в эксплуатацию:
-
Установка прав доступа: Выполняется принудительное обновление прав на исполнение для обновленного файла:
sudo chmod +x /var/www/heimdallr/heimdallr
-
Перезапуск демона (Graceful Restart): Менеджер системных служб systemd инициализирует перезапуск сервиса:
sudo systemctl restart heimdallr.service Благодаря встроенному в Go-код механизму Graceful Shutdown, старый процесс корректно завершает обслуживание текущих активных сетевых сессий, закрывает дескрипторы базы данных SQLite, инвалидирует временные структуры и передает управление новому бинарному файлу без прерывания мониторинга.
-
Верификация работоспособности (Healthcheck и Smoke Tests): Конвейер CI/CD не считает задачу завершенной на факте отправки команды перезапуска. Сценарий выполняет автоматические проверки состояния на удаленном сервере:
- Проверка активности процесса: Инструмент запрашивает статус юнита у systemd, контролируя, что приложение не упало на этапе инициализации из-за ошибок парсинга переменных окружения или повреждения БД:
sudo systemctl is-active --quiet heimdallr.service || exit 1
- Smoke-тестирование веб-интерфейса: Происходит HTTP-запрос к эндпоинту веб-сервера. Проверяется, что корень / стабильно возвращает HTTP-статус 200 OK, подтверждая работоспособность подсистемы раздачи статики Next.js и доступность роутинга API.
В случае сбоя любого из подэтапов тестирования или проверки работоспособности, шаг CI/CD завершается со статусом Failure, сигнализируя дежурному инженеру о необходимости инспекции системных логов (journalctl -u heimdallr.service).