HellreigN/README.md

HellreigN

Платформа централизованного мониторинга логов, управления скриптами и деплоя агентов.

Архитектура

┌─────────────┐       gRPC (mTLS)        ┌────────┐
│   Agent 1   │ ───────────────────────► │        │
└─────────────┘                          │        │
┌─────────────┐       gRPC (mTLS)        │Backend │       HTTP        ┌──────────┐
│   Agent 2   │ ───────────────────────► │  :8080 │ ◄──────────────── │ Frontend │
└─────────────┘                          │  :9001 │                   │   :3000   │
┌─────────────┐       gRPC (mTLS)        │        │                   └──────────┘
│   Agent N   │ ───────────────────────► │        │
└─────────────┘                          └───┬────┘
                                            │
                                            ▼
                                     ┌─────────────┐
                                     │ ClickHouse  │
                                     │  :8123/:9000│
                                     └─────────────┘

Компоненты

Компонент	Описание
Backend	Go (Gin + gRPC). REST API, gRPC сервер с mTLS, хранение токенов в SQLite
Agent	Go. Сбор логов (journald, docker, kubernetes, file), отправка метрик, выполнение команд
Frontend	React 19 + TypeScript + TailwindCSS + PrimeReact
ClickHouse	Хранилище логов

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

Требования

• Docker + Docker Compose
• Go 1.26.1+ (для локальной разработки)
• protoc + protoc-gen-go (для генерации proto)

Деплой через Docker Compose

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 mod tidy
go run ./cmd/main.go

Frontend

cd frontend
npm install
npm run dev

Agent

cd agent
go mod tidy
CONFIG_FILE=./config.yml go run main.go

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

Backend (infra/backend/config.yml)

database:
  token_db: /var/lib/hellreign/tokens.db      # SQLite база токенов и пользователей
  clickhouse_host: clickhouse:9000             # ClickHouse native порт
  clickhouse_user: default                     # Пользователь ClickHouse
  clickhouse_password: testpassword            # Пароль ClickHouse
  clickhouse_database: hellreign               # База данных ClickHouse
admin:
  admin_name: Admin                            # Имя администратора
  admin_last_name: User                        # Фамилия администратора
  admin_login: admin                           # Логин администратора
  admin_password: admin123                     # Пароль администратора (смените!)

Agent (infra/agent/config.yml)

backend_url: http://backend:8080               # HTTP URL бэкенда
grpc_url: backend:9001                         # gRPC URL бэкенда
label: test-agent-1                            # Уникальная метка агента
registration_token: "your-token-here"          # Токен регистрации (сгенерировать в UI)
cert_dir: /etc/hellreign-agent/certs           # Директория для mTLS сертификатов
services:
  # Сбор логов из journald
  - name: system
    type: journald

  # Сбор логов Docker контейнера
  - name: nginx
    type: docker

  # Сбор логов из journald + проверка systemd сервиса
  - name: sshd
    type: journald
    systemd_unit: sshd                         # Опционально: проверка alive/dead

  # Сбор логов из файла
  - name: myapp
    type: file
    path: /var/log/myapp/app.log

  # Сбор логов из Kubernetes
  - name: mypod
    type: kubernetes
    namespace: default
    pod: my-pod
    container: my-container

Graph зависимостей (infra/services.yaml)

Описывает зависимости сервисов для построения графа и определения причин сбоев:

nodes:
  test-agent-1:
    services:
      nginx:
        depends_on:
          - sshd
      sshd:
        depends_on: []
      system:
        depends_on:
          - sshd

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

Backend

Переменная	По умолчанию	Описание
CONFIG_FILE	/etc/hellreign/config.yml	Путь к YAML конфигу
GRAPH_YAML_PATH	/etc/hellreign/services.yaml	Путь к графу сервисов
SSL_CERT_DIR	/var/lib/hellreign/ssl	Директория 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 (debug / release)

Agent

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

Порты

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

API

Авторизация

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

# Создать токен
curl -X POST http://localhost:8080/api/v1/auth/token \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-token","permissions":["admin"]}'

Регистрация агента

# Сгенерировать токен регистрации (admin)
curl -X POST http://localhost:8080/api/v1/agents/register-token \
  -H "Authorization: Bearer <jwt>"

# Зарегистрировать агент
curl -X POST http://localhost:8080/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"registration_token":"<token>","csr":"<pem>"}'

Логи

# Поиск логов
curl "http://localhost:8080/api/v1/logs?service=nginx&level=error&from=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer <jwt>"

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

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

# Список подключённых агентов
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/scripts/tree \
  -H "Authorization: Bearer <jwt>"

# Создать скрипт
curl -X POST http://localhost:8080/api/v1/scripts \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"path":"deploy/restart.sh","content":"#!/bin/bash\nsystemctl restart nginx","interpreter_id":1}'

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

# Переименовать скрипт или папку
curl -X POST http://localhost:8080/api/v1/scripts/rename \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"old_path":"deploy/old.sh","new_path":"deploy/new.sh"}'

Swagger

Swagger UI доступен по адресу: http://localhost:8080/swagger/index.html

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

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

Proto

gRPC протокол определён в 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/

Миграции

SQL миграции для SQLite хранятся в migrations/. Применяются автоматически при старте бэкенда.

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

1. Создать директорию

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

2. Конфиг

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

backend_url: https://your-backend.example.com
grpc_url: your-backend.example.com:9001
label: production-server-1
registration_token: "token-from-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

GoReleaser (агент)

При пуше тега v* автоматически собирается релиз:

git tag v1.0.0
git push origin v1.0.0

Собираются .deb и .rpm пакеты для linux/amd64 и linux/arm64.

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

Структура проекта

HellreigN/
├── agent/                          # Агент мониторинга
│   ├── main.go                     # Точка входа
│   ├── dockerfile
│   ├── .goreleaser.yml             # Конфиг GoReleaser
│   └── internal/
│       ├── buffer/                 # SQLite буфер логов
│       ├── client/                 # gRPC клиент команд
│       ├── commander/              # Исполнитель команд
│       ├── config/                 # Загрузка YAML конфига
│       ├── logger/                 # Логгер
│       ├── logsource/              # Источники логов
│       │   ├── docker/             # Docker логи
│       │   ├── file/               # File логи
│       │   ├── journald/           # Journald логи
│       │   └── kubernetes/         # Kubernetes логи
│       ├── metrics/                # Сбор метрик (CPU, RAM, disk, network)
│       ├── mtls/                   # mTLS credentials
│       └── registration/           # Регистрация агента
├── backend/                        # Бэкенд API
│   ├── cmd/main.go                 # Точка входа
│   ├── dockerfile
│   ├── internal/
│   │   ├── handlers/               # HTTP хендлеры
│   │   ├── repository/             # Репозитории (SQLite)
│   │   ├── service/                # Бизнес-логика
│   │   ├── storage/                # ClickHouse storage
│   │   ├── grpcsrv/                # gRPC серверы
│   │   │   ├── commander/          # Выполнение команд на агентах
│   │   │   └── collector/          # Сбор логов и метрик
│   │   ├── auth/                   # JWT авторизация
│   │   └── config/                 # Загрузка конфига
│   └── docs/                       # Swagger документация
├── frontend/                       # Веб-интерфейс
│   ├── dockerfile
│   ├── nginx.conf
│   └── src/
├── infra/                          # Docker Compose деплой
│   ├── docker-compose.yml
│   ├── services.yaml               # Граф зависимостей
│   ├── backend/config.yml          # Конфиг бэкенда
│   ├── agent/config.yml            # Конфиг агента
│   └── clickhouse/init/            # Инициализация ClickHouse
├── migrations/                     # SQL миграции SQLite
├── proto/                          # Protobuf определения
│   ├── hellreign.proto
│   └── proto/                      # Сгенерированный Go код
└── .gitea/workflows/               # Gitea Actions CI/CD
    ├── ci-agent.yml
    ├── ci-front.yml
    └── release-agent.yml