fix readme
ci-agent / build (push) Failing after 5m24s

This commit is contained in:
d3m0k1d
2026-04-05 10:57:14 +03:00
parent 6d6dd91241
commit a70791898c
+168 -236
View File
@@ -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 <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>"
```
### Агенты и метрики
@@ -238,66 +198,48 @@ curl http://localhost:8080/api/v1/agents/system-metrics \
-H "Authorization: Bearer <jwt>"
```
### Логи
```bash
# Поиск
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>"
```
### Скрипты
```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"}'
-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
```