SensusInfra/README.md

SensusInfra — Инфраструктура для проекта Sensus

Автор: Сергей Антропов
Сайт: https://devops.org.ru

Описание

SensusInfra — это полная инфраструктура для работы с системой мониторинга Sensus, включающая:

• Kafka — брокер сообщений для передачи метрик от агентов к воркерам
• KafkaUI — веб-интерфейс для мониторинга Kafka
• PostgreSQL — база данных для хранения метаданных агентов и конфигураций
• ClickHouse — аналитическая база данных для хранения и анализа метрик (2 реплики)
• Nginx Load Balancer — балансировщик нагрузки для ClickHouse

Архитектура

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   SensusAgent   │───▶│      Kafka      │───▶│  SensusWorker   │
│   (сбор метрик) │    │  (брокер)       │    │ (обработка)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   KafkaUI       │    │   PostgreSQL    │
                       │ (мониторинг)    │    │ (метаданные)    │
                       └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   ClickHouse    │
                                               │ Load Balancer   │
                                               │    (Nginx)      │
                                               └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   ClickHouse    │
                                               │ (аналитика)     │
                                               │ (2 реплики)     │
                                               └─────────────────┘

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

1. Подготовка окружения

# Клонируйте репозиторий и перейдите в директорию
cd SensusInfra

# Создайте файл .env на основе env.example
cp env.example .env

# Отредактируйте .env с вашими значениями
nano .env

2. Запуск инфраструктуры

# Первоначальная настройка (создание .env, генерация SSL, запуск сервисов)
make setup

# Или пошагово:
make ssl-generate      # Генерация SSL сертификатов
make up                # Запуск инфраструктуры
make health-check      # Проверка здоровья сервисов

3. Управление инфраструктурой

make up                # Запуск инфраструктуры
make down              # Остановка инфраструктуры
make restart           # Перезапуск инфраструктуры
make status            # Статус сервисов
make logs              # Логи всех сервисов

Управление через Makefile

Основные команды

Команда	Описание
make setup	Первоначальная настройка инфраструктуры
make up	Запустить инфраструктуру
make down	Остановить инфраструктуру
make restart	Перезапустить инфраструктуру
make status	Показать статус всех сервисов
make logs	Показать логи всех сервисов
make health-check	Проверить здоровье сервисов

Работа с базами данных

Команда	Описание
make postgres-cli	Подключиться к PostgreSQL
make clickhouse-cli	Подключиться к ClickHouse (реплика 1)
make clickhouse-cli-2	Подключиться к ClickHouse (реплика 2)
make clickhouse-cli-lb	Подключиться к ClickHouse через балансировщик
make kafka-topics	Показать список топиков Kafka
make kafka-ui	Открыть Kafka UI в браузере

SSL сертификаты

Команда	Описание
make ssl-generate	Генерация SSL сертификатов для Kafka
make ssl-clean	Очистка SSL сертификатов
make ssl-info	Информация о SSL сертификатах

Обслуживание

Команда	Описание
make clean	Очистить все контейнеры и volumes
make clean-volumes	Очистить только volumes (данные)
make backup	Создать резервную копию данных
make restore BACKUP_FILE=имя_файла	Восстановить данные из резервной копии

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

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

Все настройки хранятся в файле .env. Основные переменные:

Kafka

• KAFKA_BROKER_ID — ID брокера Kafka (по умолчанию 1)
• KAFKA_EXTERNAL_PORT — внешний порт Kafka (по умолчанию 9092)
• KAFKA_SSL_PORT — SSL порт Kafka (по умолчанию 9093)
• KAFKA_TOPIC — топик для метрик (по умолчанию sensus.metrics)
• KAFKA_UI_PORT — порт Kafka UI (по умолчанию 8080)
• KAFKA_SSL_KEYSTORE_PASSWORD — пароль keystore (по умолчанию kafka123)
• KAFKA_SSL_KEY_PASSWORD — пароль ключа (по умолчанию kafka123)
• KAFKA_SSL_TRUSTSTORE_PASSWORD — пароль truststore (по умолчанию kafka123)

Kafka UI авторизация

• KAFKA_UI_AUTH_TYPE — тип авторизации (по умолчанию LOGIN_FORM)
• KAFKA_UI_USERNAME — логин для входа (по умолчанию admin)
• KAFKA_UI_PASSWORD — пароль для входа (по умолчанию admin)
• KAFKA_UI_USER_ROLES — роли пользователя (по умолчанию ADMIN)

PostgreSQL

• POSTGRES_DB — имя базы данных (по умолчанию sensus)
• POSTGRES_USER — пользователь (по умолчанию sensus)
• POSTGRES_PASSWORD — пароль (обязательно изменить!)
• POSTGRES_PORT — порт (по умолчанию 5432)

ClickHouse

• CLICKHOUSE_DB — имя базы данных (по умолчанию sensus_metrics)
• CLICKHOUSE_USER — пользователь (по умолчанию sensus)
• CLICKHOUSE_PASSWORD — пароль (обязательно изменить!)
• CLICKHOUSE_SECURE — безопасный режим (по умолчанию true)
• CLICKHOUSE_1_PORT — порт первой реплики (по умолчанию 8123)
• CLICKHOUSE_2_PORT — порт второй реплики (по умолчанию 8124)

ClickHouse Load Balancer

• CLICKHOUSE_LB_HTTP_PORT — HTTP порт балансировщика (по умолчанию 8125)
• CLICKHOUSE_LB_TCP_PORT — TCP порт балансировщика (по умолчанию 9002)

Структура базы данных

PostgreSQL

Схема agents — метаданные агентов:

• agents — зарегистрированные агенты
• collectors — коллекторы агентов

Схема configs — конфигурации:

• agent_configs — конфигурации агентов
• config_history — история изменений

Схема metrics — метрики:

• raw_metrics — сырые метрики
• processed_metrics — обработанные метрики

Схема system — системные таблицы:

• system_state — состояние системы
• system_logs — логи системы

ClickHouse

База sensus_metrics:

• metrics_raw — сырые метрики
• metrics_processed — обработанные метрики
• metrics_aggregated_hourly — агрегация по часам
• metrics_aggregated_daily — агрегация по дням
• agents_info — информация об агентах
• collectors_info — информация о коллекторах

База system:

• system_logs — логи системы
• system_state — состояние системы

Мониторинг

Kafka UI

• URL: http://localhost:8080
• Логин: admin
• Пароль: admin
• Мониторинг топиков, консьюмеров, партиций
• Просмотр сообщений в реальном времени
• Авторизация через форму входа

Health Check

make health-check

Проверяет доступность всех сервисов:

• Zookeeper
• Kafka
• PostgreSQL
• ClickHouse (обе реплики)

Логи

# Все сервисы
make logs

# Конкретный сервис
make infra-logs
make agent-logs
make worker-logs

Резервное копирование

Создание резервной копии

make backup

Создает резервные копии:

• PostgreSQL: ./backups/postgres_YYYYMMDD_HHMMSS.sql
• ClickHouse: backup_YYYYMMDD_HHMMSS

Восстановление

make restore BACKUP_FILE=postgres_20241201_120000.sql

Безопасность

SSL/TLS

Инфраструктура поддерживает SSL/TLS для Kafka:

• Автоматическая генерация SSL сертификатов при make setup
• Поддержка SSL на порту 9093
• Клиентские сертификаты для аутентификации
• Truststore для проверки сертификатов

Рекомендации

1. Обязательно измените пароли в файле .env
2. Не коммитьте файл .env в git
3. Используйте сильные пароли для production
4. Настройте firewall для ограничения доступа к портам
5. Регулярно обновляйте образы Docker
6. Используйте SSL для production окружения
7. Регулярно обновляйте SSL сертификаты
8. Измените пароль Kafka UI для production (по умолчанию admin/admin)

Порты

• 9092 — Kafka (внешний, PLAINTEXT)
• 9093 — Kafka (SSL)
• 8080 — Kafka UI
• 5432 — PostgreSQL
• 8123 — ClickHouse (реплика 1)
• 8124 — ClickHouse (реплика 2)
• 8125 — ClickHouse Load Balancer (HTTP)
• 9002 — ClickHouse Load Balancer (TCP)

Устранение неполадок

Проблемы с запуском

# Проверить статус сервисов
make status

# Проверить логи
make logs

# Проверить здоровье
make health-check

# Перезапустить инфраструктуру
make restart

Проблемы с сетью

# Проверить Docker сеть
docker network ls
docker network inspect sensus-network

Проблемы с данными

# Очистить volumes
make clean-volumes

# Пересоздать инфраструктуру
make clean
make setup

Проблемы с производительностью

1. Увеличьте лимиты памяти в .env
2. Настройте партиционирование в ClickHouse
3. Оптимизируйте индексы в PostgreSQL

Разработка

Добавление новых сервисов

1. Добавьте сервис в docker-compose.yml
2. Добавьте переменные в env.example
3. Добавьте команды в Makefile
4. Обновите документацию

Тестирование

# Запуск тестовой среды
make setup

# Проверка работы инфраструктуры
make status
make health-check
make logs

# Проверка SSL сертификатов
make ssl-info

# Проверка баз данных
make postgres-cli
make clickhouse-cli

Лицензия

Код сопровождается подробными комментариями на русском языке. Автор — Сергей Антропов (сайт: https://devops.org.ru).

Поддержка

При возникновении проблем:

1. Проверьте логи: make logs
2. Проверьте здоровье: make health-check
3. Обратитесь к документации проектов SensusAgent и SensusWorker
4. Создайте issue в репозитории