HellreigN/README.md

HellreigN

Агент внутренней диагностики инфраструктуры. Централизованный сбор логов, мониторинг нагрузки, управление скриптами и контроль состояния сервисов.

Возможности

• Сбор логов — journald, Docker, Kubernetes, файлы
• Метрики нагрузки — CPU, RAM, диск, сеть в реальном времени
• Контроль сервисов — проверка alive/dead для systemd и Docker
• Удалённое выполнение команд — запуск скриптов и команд на агентах
• Граф зависимостей — определение причин сбоев, порядок запуска
• Офлайн-буфер — логи не теряются при потере связи
• mTLS — защищённое соединение между агентом и бэкендом

Архитектура

┌─────────────────────────────────────────────────────────────┐
│                     Инфраструктура                          │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │ Agent 1  │  │ Agent 2  │  │ Agent N  │                  │
│  │ (хост)   │  │ (docker) │  │ (k8s)    │                  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘                  │
│       │              │              │                       │
│       └──────────────┼──────────────┘                       │
│                      │ gRPC (mTLS)                          │
│                      ▼                                      │
│              ┌───────────────┐                              │
│              │    Backend    │ ◄── REST API                 │
│              │  :8080 / :9001│                              │
│              └───────┬───────┘                              │
│                      │                                      │
│                      ▼                                      │
│              ┌───────────────┐                              │
│              │  ClickHouse   │ ◄── Хранилище логов          │
│              └───────────────┘                              │
└─────────────────────────────────────────────────────────────┘
                      ▲
                      │ HTTP
              ┌───────┴───────┐
              │   Frontend    │
              │     :3000     │
              └───────────────┘

Быстрый старт

Требования

• Docker + Docker Compose
• Go 1.26.1+ (для локальной разработки)

Деплой

cd infra
docker compose up -d --build

Поднимутся:

• ClickHouse — хранилище логов
• Backend — API (8080) + gRPC (9001)
• Frontend — веб-интерфейс (3000)
• Agent — пример агента

Откройте http://localhost:3000. Логин: admin, пароль: admin123. Что бы агент заработал нужно в веб интрфейсе найти кнопку создать токен получить его и вписать в конфигурацию агента

Локальная разработка

# Backend
cd backend && go run ./cmd/main.go

# Frontend
cd frontend && npm install && npm run dev

# Agent
cd agent && CONFIG_FILE=./config.yml go run main.go

Конфигурация

Backend

infra/backend/config.yml:

database:
  token_db: /var/lib/hellreign/tokens.db
  clickhouse_host: clickhouse:9000
  clickhouse_user: default
  clickhouse_password: testpassword
  clickhouse_database: hellreign
admin:
  admin_name: Admin
  admin_last_name: User
  admin_login: admin
  admin_password: admin123

Агент

infra/agent/config.yml:

backend_url: http://backend:8080
grpc_url: backend:9001
label: production-server-1
registration_token: "token-из-ui"
cert_dir: /etc/hellreign-agent/certs
services:
  # journald + проверка systemd
  - name: nginx
    type: journald
    systemd_unit: nginx.service

  # Docker контейнер
  - name: redis
    type: docker

  # Файл
  - name: myapp
    type: file
    path: /var/log/myapp/app.log

Поле systemd_unit опционально. Если указано — агент проверяет systemctl is-active и шлёт статус up/down. Для Docker — docker inspect {{.State.Running}}.

Граф зависимостей

infra/services.yaml:

nodes:
  production-server-1:
    services:
      nginx:
        depends_on: [sshd]
      sshd:
        depends_on: []

Используется для определения причины сбоев и порядка запуска.

Переменные окружения

Backend

Переменная	По умолчанию	Описание
CONFIG_FILE	/etc/hellreign/config.yml	Путь к YAML конфигу
GRAPH_YAML_PATH	/etc/hellreign/services.yaml	Путь к графу сервисов
SSL_CERT_DIR	/var/lib/hellreign/ssl	Директория mTLS сертификатов
SERVER_SAN_DNS	localhost,backend	SAN DNS сертификата
SERVER_SAN_IP	127.0.0.1	SAN IP сертификата
GRPC_PORT	9001	Порт gRPC
GIN_MODE	release	Режим Gin

Агент

Переменная	По умолчанию	Описание
CONFIG_FILE	/etc/hellreign-agent/config.yml	Путь к YAML конфигу
JOURNALD_LOGDIR	/var/log/journal	Директория journald (ro)
BUFFER_DB	/var/lib/hellreign-agent/agent_buffer.db	SQLite буфер
IS_DEBUG	0	Debug логи (1/0)

Порты

Сервис	Порт	Назначение
Frontend	3000	Веб-интерфейс
Backend HTTP	8080	REST API + Swagger
Backend gRPC	9001	gRPC (mTLS)
ClickHouse HTTP	8123	HTTP интерфейс
ClickHouse Native	9000	Native протокол

API примеры

Авторизация

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"admin123"}'

Агенты и метрики

# Список подключённых агентов
curl http://localhost:8080/api/v1/agents \
  -H "Authorization: Bearer <jwt>"

# Метрики нагрузки (CPU, RAM, disk, network)
curl http://localhost:8080/api/v1/agents/system-metrics \
  -H "Authorization: Bearer <jwt>"

Логи

# Поиск
curl "http://localhost:8080/api/v1/logs?service=nginx&level=error" \
  -H "Authorization: Bearer <jwt>"

# Список сервисов
curl http://localhost:8080/api/v1/logs/services \
  -H "Authorization: Bearer <jwt>"

Скрипты

# Дерево
curl http://localhost:8080/api/v1/scripts/tree \
  -H "Authorization: Bearer <jwt>"

# Запуск на агенте
curl -X POST http://localhost:8080/api/v1/scripts/1/run \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"token":"agent-token"}'

Swagger

http://localhost:8080/swagger/index.html

Перегенерация:

cd backend && swag init -g ./cmd/main.go --parseDependency --parseInternal

Деплой агента на хост

1. Директории

sudo mkdir -p /etc/hellreign-agent/certs /var/lib/hellreign-agent

2. Конфиг

sudo nano /etc/hellreign-agent/config.yml

backend_url: https://monitoring.example.com
grpc_url: monitoring.example.com:9001
label: prod-web-1
registration_token: "token-из-ui"
cert_dir: /etc/hellreign-agent/certs
services:
  - name: nginx
    type: journald
    systemd_unit: nginx.service
  - name: postgres
    type: journald
    systemd_unit: postgresql.service

3. Бинарь

Скачать из релиза Gitea или собрать:

cd agent && go build -o hellreign-agent ./main.go
sudo mv hellreign-agent /usr/bin/

4. Systemd

[Unit]
Description=HellreigN Agent
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/hellreign-agent
Environment=CONFIG_FILE=/etc/hellreign-agent/config.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now hellreign-agent

CI/CD

При пуше тега v* — GoReleaser собирает .deb и .rpm для linux/amd64 и linux/arm64:

git tag v1.0.0 && git push origin v1.0.0

Требует секрет GITEA_TOKEN в настройках репозитория.

Proto

После изменений в proto/hellreign.proto:

cd proto
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       hellreign.proto
mv hellreign*.go proto/

Структура

HellreigN/
├── agent/                          # Агент диагностики
│   ├── main.go
│   └── internal/
│       ├── buffer/                 # SQLite буфер (офлайн-доставка)
│       ├── client/                 # gRPC клиент команд
│       ├── commander/              # Исполнитель команд
│       ├── config/                 # YAML конфиг
│       ├── metrics/                # Сбор CPU, RAM, disk, network
│       ├── logsource/              # Источники логов
│       │   ├── docker/
│       │   ├── file/
│       │   ├── journald/
│       │   └── kubernetes/
│       ├── mtls/                   # mTLS credentials
│       └── registration/           # Регистрация
├── backend/                        # Бэкенд API
│   ├── cmd/main.go
│   └── internal/
│       ├── handlers/               # HTTP хендлеры
│       ├── repository/             # SQLite репозитории
│       ├── grpcsrv/
│       │   ├── commander/          # Выполнение команд
│       │   └── collector/          # Сбор логов и метрик
│       ├── auth/                   # JWT
│       └── storage/                # ClickHouse
├── frontend/                       # React + TypeScript
├── infra/                          # Docker Compose
│   ├── docker-compose.yml
│   ├── services.yaml               # Граф зависимостей
│   ├── backend/config.yml
│   ├── agent/config.yml
│   └── clickhouse/init/
├── migrations/                     # SQL миграции SQLite
└── proto/                          # Protobuf