From 6d6dd9124141f626bd5f96c31ac44e28a69fcd98 Mon Sep 17 00:00:00 2001 From: d3m0k1d Date: Sun, 5 Apr 2026 09:32:12 +0300 Subject: [PATCH] docs --- .gitea/workflows/release-agent.yml | 32 +++ README.md | 427 ++++++++++++++++++++++++++++- 2 files changed, 458 insertions(+), 1 deletion(-) create mode 100644 .gitea/workflows/release-agent.yml diff --git a/.gitea/workflows/release-agent.yml b/.gitea/workflows/release-agent.yml new file mode 100644 index 0000000..25d95b7 --- /dev/null +++ b/.gitea/workflows/release-agent.yml @@ -0,0 +1,32 @@ +name: release-agent + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + packages: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v6 + with: + fetch-depth: 0 + - name: Go setup + uses: actions/setup-go@v6 + with: + go-version: "1.26.1" + - name: Run GoReleaser + uses: goreleaser/goreleaser-action@v6 + with: + distribution: goreleaser + version: latest + args: release --clean + workdir: agent + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} diff --git a/README.md b/README.md index fa77674..0663ccc 100644 --- a/README.md +++ b/README.md @@ -1 +1,426 @@ -# HellreigN \ No newline at end of file +# 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 " \ + -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 " +``` + +### Агенты и метрики + +```bash +# Список подключённых агентов +curl http://localhost:8080/api/v1/agents \ + -H "Authorization: Bearer " + +# Метрики нагрузки (CPU, RAM, disk, network) +curl http://localhost:8080/api/v1/agents/system-metrics \ + -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"}' +``` + +### 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 +```