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

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

## Описание

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

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

## Архитектура

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   SensusAgent   │───▶│      Kafka      │───▶│  SensusWorker   │
│   (сбор метрик) │    │     (брокер)    │    │  (обработка)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │    KafkaUI      │    │   PostgreSQL    │
                       │    (web ui)     │    │  (метаданные)   │
                       └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   ClickHouse    │
                                               │ Load Balancer   │
                                               │    (Nginx)      │
                                               │  HTTP: 8125     │
                                               │  TCP: 9002      │
                                               └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   ClickHouse    │
                                               │   (аналитика)   │
                                               │   (2 реплики)   │
                                               │  Реплика 1: 8123│
                                               │  Реплика 2: 8124│
                                               └─────────────────┘
                                                        │
                                                        ▼
                                               ┌─────────────────┐
                                               │   ZooKeeper     │
                                               │ (координатор)   │
                                               │    Port: 2181   │
                                               └─────────────────┘
```

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

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

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

# Установите Docker и Docker Compose (если не установлены)
make docker-check                    # Проверить текущие версии
make docker-install                  # Установить Docker
make docker-compose-install          # Установить Docker Compose

# Файл .env будет создан автоматически при выполнении make setup
# Или создайте вручную:
cp env.example .env

# Отредактируйте .env с вашими значениями (опционально)
nano .env
```

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

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

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

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

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

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

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

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

### Установка и обновление Docker

| Команда | Описание |
|---------|----------|
| `make docker-install` | Установить Docker через get.docker.com |
| `make docker-update` | Обновить Docker до последней версии |
| `make docker-compose-install` | Установить Docker Compose |
| `make docker-compose-update` | Обновить Docker Compose до последней версии |
| `make docker-check` | Проверить версии Docker и Docker Compose |

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

| Команда | Описание |
|---------|----------|
| `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 сертификатах |

## Установка Docker

### Автоматическая установка

Проект включает команды для автоматической установки и обновления Docker:

```bash
# Проверить текущие версии
make docker-check

# Установить Docker (если не установлен)
make docker-install

# Установить Docker Compose (если не установлен)
make docker-compose-install

# Обновить Docker до последней версии
make docker-update

# Обновить Docker Compose до последней версии
make docker-compose-update
```

### Ручная установка

Если автоматическая установка не работает, используйте официальные инструкции:

#### Docker
```bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# CentOS/RHEL
sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker
```

#### Docker Compose
```bash
# Скачать последнюю версию
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```

### Проверка установки

```bash
# Проверить версии
make docker-check

# Или вручную
docker --version
docker compose version
```

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

| Команда | Описание |
|---------|----------|
| `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)
- `POSTGRES_SSL_MODE` — режим SSL (по умолчанию require)
- `POSTGRES_SSL_CERT_FILE` — путь к сертификату сервера
- `POSTGRES_SSL_KEY_FILE` — путь к приватному ключу сервера
- `POSTGRES_SSL_CA_FILE` — путь к сертификату CA

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

#### 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` — сырые метрики (ReplicatedMergeTree)
- `metrics_processed` — обработанные метрики (ReplicatedMergeTree)
- `agents_info` — информация об агентах (ReplicatedReplacingMergeTree)

**Кластер `sensus_cluster`**:
- **Шард 1** с двумя репликами:
  - `clickhouse-1` (порт 8123/9000)
  - `clickhouse-2` (порт 8124/9001)
- **ZooKeeper** для координации репликации
- **Автоматическая репликация** данных между узлами
- **Балансировщик нагрузки** для распределения запросов

**База `system`**:
- `system_logs` — логи системы
- `system_state` — состояние системы

## Мониторинг

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

### ClickHouse Load Balancer
- **HTTP:** http://localhost:8125
- **TCP:** localhost:9002
- Балансировка нагрузки между репликами ClickHouse
- Health check endpoint: http://localhost:8125/health
- Статус endpoint: http://localhost:8125/status

### Health Check
```bash
make health-check
```

Проверяет доступность всех сервисов:
- ZooKeeper
- Kafka
- PostgreSQL
- ClickHouse (обе реплики) - с паузой 30 секунд для полной инициализации
- ClickHouse Load Balancer - с паузой 10 секунд

**Примечание:** Команда включает паузы для ClickHouse сервисов, так как они требуют времени для полной инициализации после запуска.

### Логи
```bash
# Все сервисы
make logs

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

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

### Создание резервной копии
```bash
make backup
```

Создает резервные копии:
- PostgreSQL: `./backups/postgres_YYYYMMDD_HHMMSS.sql`
- ClickHouse: `backup_YYYYMMDD_HHMMSS`

### Восстановление
```bash
make restore BACKUP_FILE=postgres_20241201_120000.sql
```

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

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

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

#### PostgreSQL SSL
- **Автоматическая генерация** SSL сертификатов при `make setup`
- **Режим SSL** — require (обязательное шифрование)
- **Самоподписанные сертификаты** для разработки
- **Поддержка SSL** на стандартном порту 5432

### Рекомендации
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
- **2181** — ZooKeeper
- **8123** — ClickHouse (реплика 1, HTTP)
- **9000** — ClickHouse (реплика 1, TCP)
- **8124** — ClickHouse (реплика 2, HTTP)
- **9001** — ClickHouse (реплика 2, TCP)
- **8125** — ClickHouse Load Balancer (HTTP)
- **9002** — ClickHouse Load Balancer (TCP)

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

### Проблемы с запуском
```bash
# Проверить статус сервисов
make status

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

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

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

### Проблемы с сетью
```bash
# Проверить Docker сеть
docker network ls
docker network inspect sensus-network
```

### Проблемы с данными
```bash
# Очистить volumes
make clean-volumes

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

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

## Разработка

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

### Тестирование
```bash
# Запуск тестовой среды
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 в репозитории