From a70791898c36d1ecdd043f4097323478efa52bb4 Mon Sep 17 00:00:00 2001 From: d3m0k1d Date: Sun, 5 Apr 2026 10:57:14 +0300 Subject: [PATCH] fix readme --- README.md | 404 +++++++++++++++++++++++------------------------------- 1 file changed, 168 insertions(+), 236 deletions(-) diff --git a/README.md b/README.md index 0663ccc..5721d24 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,148 @@ # HellreigN -Платформа централизованного мониторинга логов, управления скриптами и деплоя агентов. +Агент внутренней диагностики инфраструктуры. Централизованный сбор логов, мониторинг нагрузки, управление скриптами и контроль состояния сервисов. + +## Возможности + +- **Сбор логов** — journald, Docker, Kubernetes, файлы +- **Метрики нагрузки** — CPU, RAM, диск, сеть в реальном времени +- **Контроль сервисов** — проверка alive/dead для systemd и Docker +- **Удалённое выполнение команд** — запуск скриптов и команд на агентах +- **Граф зависимостей** — определение причин сбоев, порядок запуска +- **Офлайн-буфер** — логи не теряются при потере связи +- **mTLS** — защищённое соединение между агентом и бэкендом ## Архитектура ``` -┌─────────────┐ gRPC (mTLS) ┌────────┐ -│ Agent 1 │ ───────────────────────► │ │ -└─────────────┘ │ │ -┌─────────────┐ gRPC (mTLS) │Backend │ HTTP ┌──────────┐ -│ Agent 2 │ ───────────────────────► │ :8080 │ ◄──────────────── │ Frontend │ -└─────────────┘ │ :9001 │ │ :3000 │ -┌─────────────┐ gRPC (mTLS) │ │ └──────────┘ -│ Agent N │ ───────────────────────► │ │ -└─────────────┘ └───┬────┘ - │ - ▼ - ┌─────────────┐ - │ ClickHouse │ - │ :8123/:9000│ - └─────────────┘ +┌─────────────────────────────────────────────────────────────┐ +│ Инфраструктура │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Agent 1 │ │ Agent 2 │ │ Agent N │ │ +│ │ (хост) │ │ (docker) │ │ (k8s) │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +│ │ │ │ │ +│ └──────────────┼──────────────┘ │ +│ │ gRPC (mTLS) │ +│ ▼ │ +│ ┌───────────────┐ │ +│ │ Backend │ ◄── REST API │ +│ │ :8080 / :9001│ │ +│ └───────┬───────┘ │ +│ │ │ +│ ▼ │ +│ ┌───────────────┐ │ +│ │ ClickHouse │ ◄── Хранилище логов │ +│ └───────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ▲ + │ HTTP + ┌───────┴───────┐ + │ Frontend │ + │ :3000 │ + └───────────────┘ ``` -### Компоненты - -| Компонент | Описание | -|-----------|----------| -| **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** — агент мониторинга (пример) +- **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 -``` +# Backend +cd backend && go run ./cmd/main.go -#### Frontend +# Frontend +cd frontend && npm install && npm run dev -```bash -cd frontend -npm install -npm run dev -``` - -#### Agent - -```bash -cd agent -go mod tidy -CONFIG_FILE=./config.yml go run main.go +# Agent +cd agent && CONFIG_FILE=./config.yml go run main.go ``` ## Конфигурация -### Backend (`infra/backend/config.yml`) +### 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 + 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 # Пароль администратора (смените!) + admin_name: Admin + admin_last_name: User + admin_login: admin + admin_password: admin123 ``` -### Agent (`infra/agent/config.yml`) +### Агент + +`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 сертификатов +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 - - name: system - type: journald - - # Сбор логов Docker контейнера + # journald + проверка systemd - name: nginx + type: journald + systemd_unit: nginx.service + + # Docker контейнер + - name: redis 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`) +Поле `systemd_unit` опционально. Если указано — агент проверяет `systemctl is-active` и шлёт статус `up`/`down`. Для Docker — `docker inspect {{.State.Running}}`. -Описывает зависимости сервисов для построения графа и определения причин сбоев: +### Граф зависимостей + +`infra/services.yaml`: ```yaml nodes: - test-agent-1: + production-server-1: services: nginx: - depends_on: - - sshd + depends_on: [sshd] sshd: depends_on: [] - system: - depends_on: - - sshd ``` +Используется для определения причины сбоев и порядка запуска. + ## Переменные окружения ### Backend @@ -159,71 +151,39 @@ nodes: |------------|-------------|----------| | `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`) | +| `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 | -### 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`) | +| `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` | Веб-интерфейс (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 | +| Frontend | `3000` | Веб-интерфейс | +| Backend HTTP | `8080` | REST API + Swagger | +| Backend gRPC | `9001` | gRPC (mTLS) | +| ClickHouse HTTP | `8123` | HTTP интерфейс | +| ClickHouse Native | `9000` | Native протокол | -## API +## 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 " \ - -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 " - -# Зарегистрировать агент -curl -X POST http://localhost:8080/api/v1/agents/register \ - -H "Content-Type: application/json" \ - -d '{"registration_token":"","csr":""}' -``` - -### Логи - -```bash -# Поиск логов -curl "http://localhost:8080/api/v1/logs?service=nginx&level=error&from=2024-01-01T00:00:00Z" \ - -H "Authorization: Bearer " - -# Список сервисов -curl http://localhost:8080/api/v1/logs/services \ - -H "Authorization: Bearer " ``` ### Агенты и метрики @@ -238,66 +198,48 @@ curl http://localhost:8080/api/v1/agents/system-metrics \ -H "Authorization: Bearer " ``` +### Логи + +```bash +# Поиск +curl "http://localhost:8080/api/v1/logs?service=nginx&level=error" \ + -H "Authorization: Bearer " + +# Список сервисов +curl http://localhost:8080/api/v1/logs/services \ + -H "Authorization: Bearer " +``` + ### Скрипты ```bash -# Дерево скриптов +# Дерево curl http://localhost:8080/api/v1/scripts/tree \ -H "Authorization: Bearer " -# Создать скрипт -curl -X POST http://localhost:8080/api/v1/scripts \ - -H "Authorization: Bearer " \ - -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 " \ -H "Content-Type: application/json" \ - -d '{"token":"agent-token","stdin":""}' - -# Переименовать скрипт или папку -curl -X POST http://localhost:8080/api/v1/scripts/rename \ - -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"old_path":"deploy/old.sh","new_path":"deploy/new.sh"}' + -d '{"token":"agent-token"}' ``` ### Swagger -Swagger UI доступен по адресу: `http://localhost:8080/swagger/index.html` +`http://localhost:8080/swagger/index.html` Перегенерация: ```bash -cd backend -swag init -g ./cmd/main.go --parseDependency --parseInternal +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. Создать директорию +### 1. Директории ```bash -sudo mkdir -p /etc/hellreign-agent/certs -sudo mkdir -p /var/lib/hellreign-agent +sudo mkdir -p /etc/hellreign-agent/certs /var/lib/hellreign-agent ``` ### 2. Конфиг @@ -307,10 +249,10 @@ 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" +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 @@ -321,17 +263,16 @@ services: systemd_unit: postgresql.service ``` -### 3. Установить бинарь +### 3. Бинарь -Скачать релиз из Gitea или собрать: +Скачать из релиза Gitea или собрать: ```bash -cd agent -go build -o hellreign-agent ./main.go +cd agent && go build -o hellreign-agent ./main.go sudo mv hellreign-agent /usr/bin/ ``` -### 4. Systemd сервис +### 4. Systemd ```ini [Unit] @@ -356,71 +297,62 @@ sudo systemctl enable --now hellreign-agent ## CI/CD -### GoReleaser (агент) - -При пуше тега `v*` автоматически собирается релиз: +При пуше тега `v*` — GoReleaser собирает `.deb` и `.rpm` для `linux/amd64` и `linux/arm64`: ```bash -git tag v1.0.0 -git push origin v1.0.0 +git tag v1.0.0 && git push origin v1.0.0 ``` -Собираются `.deb` и `.rpm` пакеты для `linux/amd64` и `linux/arm64`. - Требует секрет `GITEA_TOKEN` в настройках репозитория. -## Структура проекта +## Proto + +После изменений в `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/ +``` + +## Структура ``` HellreigN/ -├── agent/ # Агент мониторинга -│ ├── main.go # Точка входа -│ ├── dockerfile -│ ├── .goreleaser.yml # Конфиг GoReleaser +├── agent/ # Агент диагностики +│ ├── main.go │ └── internal/ -│ ├── buffer/ # SQLite буфер логов +│ ├── buffer/ # SQLite буфер (офлайн-доставка) │ ├── client/ # gRPC клиент команд │ ├── commander/ # Исполнитель команд -│ ├── config/ # Загрузка YAML конфига -│ ├── logger/ # Логгер +│ ├── config/ # YAML конфиг +│ ├── metrics/ # Сбор CPU, RAM, disk, network │ ├── logsource/ # Источники логов -│ │ ├── docker/ # Docker логи -│ │ ├── file/ # File логи -│ │ ├── journald/ # Journald логи -│ │ └── kubernetes/ # Kubernetes логи -│ ├── metrics/ # Сбор метрик (CPU, RAM, disk, network) +│ │ ├── docker/ +│ │ ├── file/ +│ │ ├── journald/ +│ │ └── kubernetes/ │ ├── mtls/ # mTLS credentials -│ └── registration/ # Регистрация агента +│ └── 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 деплой +│ ├── 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/ # Инициализация ClickHouse +│ ├── backend/config.yml +│ ├── agent/config.yml +│ └── clickhouse/init/ ├── migrations/ # SQL миграции SQLite -├── proto/ # Protobuf определения -│ ├── hellreign.proto -│ └── proto/ # Сгенерированный Go код -└── .gitea/workflows/ # Gitea Actions CI/CD - ├── ci-agent.yml - ├── ci-front.yml - └── release-agent.yml +└── proto/ # Protobuf ```