# 🌐 PyGuardian Cluster Setup Guide

## Обзор

PyGuardian поддерживает кластерный режим для централизованного управления безопасностью множественных Linux серверов из единого Telegram интерфейса.

## 🏗️ Архитектура кластера

```
┌─────────────────┐    ┌─────────────────┐
│   Telegram Bot  │◄──►│  Master Server  │
│                 │    │  (PyGuardian)   │
└─────────────────┘    └─────────┬───────┘
                                 │
                   ┌─────────────┼─────────────┐
                   ▼             ▼             ▼
            ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
            │  Agent 1    │ │  Agent 2    │ │  Agent 3    │
            │ Web Server  │ │ DB Server   │ │ App Server  │
            └─────────────┘ └─────────────┘ └─────────────┘
```

### Компоненты
- **Master Server**: Основной сервер с полной установкой PyGuardian
- **Agent Servers**: Серверы с установленными агентами PyGuardian
- **Telegram Bot**: Единый интерфейс управления всем кластером

## 🚀 Быстрая настройка кластера

### Шаг 1: Установка мастер-сервера

```bash
# Установить PyGuardian на мастер-сервер
curl -sSL https://raw.githubusercontent.com/your-org/pyguardian/main/install.sh | bash

# Настроить конфигурацию
sudo nano /etc/pyguardian/config.yaml
```

### Шаг 2: Включение кластерного режима

```yaml
# /etc/pyguardian/config.yaml
cluster:
  enabled: true
  ssh_timeout: 30
  deployment_timeout: 300
  retry_attempts: 3
  agent_port: 8081
  master_host: "192.168.1.100"  # IP вашего мастер-сервера
  master_port: 8080
```

### Шаг 3: Перезапуск мастер-сервера

```bash
sudo systemctl restart pyguardian
sudo systemctl status pyguardian
```

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

### Добавление серверов в кластер

```bash
# Синтаксис: /add_server <имя> <IP> <пользователь>
/add_server web01 192.168.1.10 ubuntu
/add_server db01 192.168.1.20 admin
/add_server app01 192.168.1.30 deploy
```

### Автоматическое развертывание агентов

```bash
# Развернуть агента на сервере (требует SSH доступ)
/deploy_agent web01

# Проверить статус развертывания
/agents
```

### Мониторинг кластера

```bash
# Общая статистика кластера
/cluster

# Список всех агентов и их статус
/agents

# Проверить доступность всех агентов
/check_agents
```

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

Если автоматическое развертывание невозможно, установите агента вручную:

### На целевом сервере:

```bash
# 1. Загрузить агента
wget https://raw.githubusercontent.com/your-org/pyguardian/main/agent/install_agent.sh

# 2. Сделать исполняемым
chmod +x install_agent.sh

# 3. Запустить установку
sudo ./install_agent.sh --master 192.168.1.100 --port 8080

# 4. Проверить статус
sudo systemctl status pyguardian-agent
```

## 🛡️ Безопасность кластера

### SSH ключи (рекомендуется)

```bash
# На мастер-сервере сгенерировать SSH ключ
ssh-keygen -t rsa -b 4096 -f /etc/pyguardian/cluster_key

# Скопировать публичный ключ на целевые серверы
ssh-copy-id -i /etc/pyguardian/cluster_key.pub user@target-server

# Обновить конфигурацию
ssh_key_path: "/etc/pyguardian/cluster_key"
```

### Настройка firewall

```bash
# На агентах открыть порт для агента
sudo ufw allow 8081/tcp

# На мастере открыть порт для управления
sudo ufw allow 8080/tcp
```

## 🔍 Мониторинг и диагностика

### Проверка статуса кластера

```bash
# Статус мастер-сервера
sudo systemctl status pyguardian

# Лог мастер-сервера
sudo journalctl -u pyguardian -f

# Проверка соединений
sudo netstat -tlnp | grep 8080
```

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

```bash
# На агенте
sudo systemctl status pyguardian-agent
sudo journalctl -u pyguardian-agent -f

# Проверка порта агента
sudo netstat -tlnp | grep 8081
```

### Диагностика соединений

```bash
# Проверка SSH доступа с мастера
ssh -i /etc/pyguardian/cluster_key user@agent-server

# Проверка сетевого соединения
telnet agent-server 8081
```

## 📊 Команды кластерного управления

| Команда | Описание | Пример |
|---------|----------|--------|
| `/cluster` | Статистика кластера | `/cluster` |
| `/add_server` | Добавить сервер | `/add_server web01 10.0.0.5 ubuntu` |
| `/remove_server` | Удалить сервер | `/remove_server old_web` |
| `/deploy_agent` | Развернуть агента | `/deploy_agent web01` |
| `/agents` | Список агентов | `/agents` |
| `/check_agents` | Проверить агентов | `/check_agents` |

## 🚨 Решение проблем

### Агент не подключается

```bash
# Проверить firewall на агенте
sudo ufw status
sudo ufw allow 8081/tcp

# Проверить статус сервиса агента
sudo systemctl status pyguardian-agent

# Перезапустить агента
sudo systemctl restart pyguardian-agent
```

### SSH ошибки развертывания

```bash
# Проверить SSH ключи
ssh -i /etc/pyguardian/cluster_key user@target-server

# Проверить права на ключ
chmod 600 /etc/pyguardian/cluster_key

# Проверить конфигурацию SSH
sudo nano /etc/ssh/sshd_config
```

### Тайм-ауты соединений

```yaml
# Увеличить таймауты в config.yaml
cluster:
  ssh_timeout: 60        # Увеличить с 30
  deployment_timeout: 600 # Увеличить с 300
  retry_attempts: 5      # Увеличить с 3
```

## 🔄 Масштабирование кластера

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

1. Подготовить сервер согласно требованиям
2. Настроить SSH доступ
3. Добавить через `/add_server`
4. Развернуть агента через `/deploy_agent`

### Удаление серверов

1. Остановить агента: `sudo systemctl stop pyguardian-agent`
2. Удалить из кластера: `/remove_server <name>`
3. Удалить файлы агента на сервере

### Обновление агентов

```bash
# На мастер-сервере через Telegram
/update_agents  # Планируется в будущих версиях

# Или вручную на каждом агенте
sudo systemctl stop pyguardian-agent
sudo pip3 install --upgrade pyguardian
sudo systemctl start pyguardian-agent
```

## 📈 Мониторинг производительности

### Метрики кластера

- Количество активных агентов
- Время отклика агентов
- Статус безопасности каждого сервера
- Общая статистика атак по кластеру

### Алерты

PyGuardian автоматически уведомит в Telegram о:
- Недоступности агентов
- Обнаруженных атаках на любом сервере
- Ошибках развертывания
- Проблемах с соединением

## 🎯 Лучшие практики

1. **Безопасность**: Используйте SSH ключи вместо паролей
2. **Мониторинг**: Регулярно проверяйте статус агентов
3. **Резервное копирование**: Сохраняйте конфигурацию и ключи
4. **Обновления**: Поддерживайте все компоненты в актуальном состоянии
5. **Логирование**: Мониторьте логи мастера и агентов

---

Для получения поддержки обращайтесь:
- GitHub Issues: [pyguardian/issues](https://github.com/your-org/pyguardian/issues)
- Telegram: [@pyguardian_support](https://t.me/pyguardian_support)