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

```bash
cd infra
docker compose up -d --build
```

Это поднимет:
- **ClickHouse** — хранилище логов
- **Backend** — API на порту `8080`, gRPC на `9001`
- **Frontend** — веб-интерфейс на порту `3000`
- **Agent** — агент мониторинга (пример)

Откройте `http://localhost:3000`. Логин: `admin`, пароль: `admin123`.

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

#### Backend

```bash
cd backend
go mod tidy
go run ./cmd/main.go
```

#### Frontend

```bash
cd frontend
npm install
npm run dev
```

#### Agent

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

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

### Backend (`infra/backend/config.yml`)

```yaml
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`)

```yaml
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`)

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

```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

### Авторизация

```bash
# Логин
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"]}'
```

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

```bash
# Сгенерировать токен регистрации (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>"}'
```

### Логи

```bash
# Поиск логов
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>"
```

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

```bash
# Список подключённых агентов
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>"
```

### Скрипты

```bash
# Дерево скриптов
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`

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

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

## Proto

gRPC протокол определён в `proto/hellreign.proto`. После изменений:

```bash
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. Создать директорию

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

### 2. Конфиг

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

```yaml
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 или собрать:

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

### 4. Systemd сервис

```ini
[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
```

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

## CI/CD

### GoReleaser (агент)

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

```bash
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
```