# Управление кластером PyGuardian

## 🏢 Централизованное развертывание агентов

PyGuardian поддерживает централизованное управление кластером серверов через Telegram бот. Мастер-сервер может автоматически развертывать и управлять агентами на удаленных серверах.

## 🎯 Возможности кластера

### Основные функции:
- **Автоматическое развертывание**: Установка PyGuardian на удаленные серверы
- **Централизованное управление**: Контроль всех агентов через один Telegram бот
- **Мониторинг статуса**: Проверка состояния агентов в реальном времени
- **SSH интеграция**: Безопасное подключение через SSH ключи или пароли
- **Автоматическая очистка**: Удаление агентов с очисткой удаленных серверов

### Архитектура:
```
[Master Server] ──SSH──┐
                       ├── [Agent Server 1]
                       ├── [Agent Server 2] 
                       ├── [Agent Server 3]
                       └── [Agent Server N]
```

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

### 1. Настройка мастер-сервера

Убедитесь что в `config/config.yaml` указано:
```yaml
cluster:
  cluster_name: "MyCompany-Security"
  master_server: true
  ssh_timeout: 30
  ssh_retries: 3
```

### 2. Подготовка SSH доступа

#### Вариант A: SSH ключи (рекомендуется)
```bash
# Генерация ключей
ssh-keygen -t rsa -b 4096 -f ~/.ssh/pyguardian_cluster

# Копирование на целевой сервер
ssh-copy-id -i ~/.ssh/pyguardian_cluster.pub root@192.168.1.100
```

#### Вариант B: Пароли (менее безопасно)
Используется для первоначальной настройки или тестирования.

### 3. Добавление серверов

```
/add_server web-01 192.168.1.100
/add_server web-02 192.168.1.101 ubuntu 2222
/add_server db-01 192.168.1.200
```

### 4. Развертывание агентов

```
/deploy_agent web-01-192-168-1-100
/deploy_agent web-02-192-168-1-101
/deploy_agent db-01-192-168-1-200
```

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

```
/cluster           # Общая информация
/agents            # Список агентов
/check_agents      # Проверка статуса
```

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

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

| Команда | Описание | Пример |
|---------|----------|--------|
| `/cluster` | Информация о кластере | `/cluster` |
| `/agents` | Список всех агентов | `/agents` |
| `/add_server` | Добавить сервер | `/add_server web-01 192.168.1.100` |
| `/remove_server` | Удалить сервер | `/remove_server web-01-192-168-1-100` |
| `/deploy_agent` | Развернуть агент | `/deploy_agent web-01-192-168-1-100` |
| `/check_agents` | Проверить статусы | `/check_agents` |

### Детальные примеры

#### Добавление сервера
```
# Базовое добавление (root, порт 22)
/add_server web-server 192.168.1.100

# С кастомным пользователем
/add_server app-server 10.0.0.50 ubuntu

# С кастомным портом
/add_server db-server 192.168.1.200 postgres 2222

# Полная форма
/add_server api-server 172.16.0.100 deploy 2200
```

#### Развертывание агента
```
# Обычное развертывание
/deploy_agent web-server-192-168-1-100

# Принудительная переустановка
/deploy_agent web-server-192-168-1-100 force
```

#### Удаление сервера
```
# Простое удаление (агент остается)
/remove_server web-server-192-168-1-100

# С очисткой удаленного сервера
/remove_server web-server-192-168-1-100 cleanup
```

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

### Настройки кластера в config/config.yaml

```yaml
cluster:
  cluster_name: "Production-Cluster"    # Название кластера
  master_server: true                   # Мастер-сервер
  agents_config_path: "/var/lib/pyguardian/agents.yaml"
  deployment_path: "/opt/pyguardian"
  ssh_timeout: 30                       # Таймаут SSH (секунды)
  ssh_retries: 3                        # Попытки подключения

# SSH ключи по умолчанию (опционально)  
ssh:
  default_key_path: "/root/.ssh/pyguardian_cluster"
  default_user: "root"
  default_port: 22
```

### Файл агентов agents.yaml

```yaml
cluster:
  name: "Production-Cluster"
  master_server: true
  last_updated: "2024-11-25T15:30:00"

agents:
  web-01-192-168-1-100:
    hostname: "web-01"
    ip_address: "192.168.1.100"
    ssh_port: 22
    ssh_user: "root"
    ssh_key_path: "/root/.ssh/pyguardian_cluster"
    status: "online"
    last_check: "2024-11-25T15:25:00"
    version: "1.0.0"

  api-server-172-16-0-100:
    hostname: "api-server"
    ip_address: "172.16.0.100"
    ssh_port: 2200
    ssh_user: "deploy"
    status: "deployed"
    last_check: null
    version: null
```

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

### Рекомендации по безопасности:

1. **SSH ключи**: Всегда используйте SSH ключи вместо паролей
2. **Ограниченные права**: Создайте отдельного пользователя для развертывания
3. **Файрвол**: Ограничьте SSH доступ только с мастер-сервера
4. **Мониторинг**: Регулярно проверяйте статус агентов
5. **Обновления**: Следите за обновлениями PyGuardian

### Настройка пользователя для развертывания:

```bash
# На целевом сервере
useradd -m -s /bin/bash pyguardian-deploy
usermod -aG sudo pyguardian-deploy

# Настройка sudoers
echo 'pyguardian-deploy ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/pyguardian-deploy

# Копирование SSH ключа
mkdir /home/pyguardian-deploy/.ssh
cp /root/.ssh/authorized_keys /home/pyguardian-deploy/.ssh/
chown -R pyguardian-deploy:pyguardian-deploy /home/pyguardian-deploy/.ssh
chmod 700 /home/pyguardian-deploy/.ssh
chmod 600 /home/pyguardian-deploy/.ssh/authorized_keys
```

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

### Частые проблемы:

#### Ошибка SSH соединения
```
❌ Не удалось подключиться к серверу: Connection refused
```

**Решение:**
1. Проверьте доступность сервера: `ping 192.168.1.100`
2. Проверьте SSH сервис: `ssh root@192.168.1.100`
3. Проверьте порт SSH: `nmap -p 22 192.168.1.100`

#### Ошибка прав доступа
```
❌ Ошибка установки: Permission denied
```

**Решение:**
1. Убедитесь что пользователь имеет права sudo
2. Проверьте настройки sudoers
3. Попробуйте от root пользователя

#### Агент не запускается
```
🔴 service_status: failed
```

**Решение:**
1. Проверьте логи: `journalctl -u pyguardian-agent -f`
2. Проверьте конфигурацию агента
3. Переустановите агент: `/deploy_agent agent-id force`

### Команды диагностики:

```bash
# На мастер-сервере
tail -f /var/log/pyguardian.log

# На агенте
systemctl status pyguardian-agent
journalctl -u pyguardian-agent -f
cat /var/log/pyguardian-agent.log
```

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

### Telegram уведомления

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

### Пример вывода команд:

#### /cluster
```
🏢 Кластер Production-Cluster

📊 Статистика:
  • Всего агентов: 5
  • Онлайн: 4
  • Оффлайн: 1
  • Развернуто: 5

🖥️ Агенты:
🟢 web-01 (192.168.1.100)
🟢 web-02 (192.168.1.101)
🔴 db-01 (192.168.1.200)
🟢 api-server (172.16.0.100)
🟢 cache-01 (10.0.0.50)

🕐 Последнее обновление: 2024-11-25 15:30:45
```

#### /check_agents
```
🔍 Результаты проверки агентов

📊 Статистика:
  • Проверено: 5
  • Онлайн: 4  
  • Оффлайн: 1
  • Ошибки: 0

📋 Детали:
🟢 web-01: active
🟢 web-02: active  
🔴 db-01: inactive
🟢 api-server: active
🟢 cache-01: active

🕐 Время проверки: 15:32:10
```

## 🔄 Автоматизация

### Скрипты автоматизации

Создайте скрипты для автоматического управления кластером:

```bash
#!/bin/bash
# auto-deploy.sh - Автоматическое развертывание на список серверов

SERVERS=(
    "web-01 192.168.1.100"
    "web-02 192.168.1.101"
    "api-01 172.16.0.100"
)

for server in "${SERVERS[@]}"; do
    hostname=$(echo $server | cut -d' ' -f1)
    ip=$(echo $server | cut -d' ' -f2)
    
    echo "Добавляю $hostname ($ip)..."
    # Здесь может быть API вызов или автоматизация через expect
done
```

### Интеграция с CI/CD

PyGuardian кластер может быть интегрирован с CI/CD пайплайнами для автоматического развертывания защиты на новые серверы.

## 📈 Масштабирование

### Рекомендации по масштабированию:

- **До 10 серверов**: Один мастер-сервер
- **10-50 серверов**: Мастер + резервный мастер
- **50+ серверов**: Распределенная архитектура

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

- Время отклика SSH соединений
- Использование ресурсов мастер-сервера  
- Скорость развертывания агентов
- Частота проверки статуса

---

*Данная документация покрывает основные возможности управления кластером PyGuardian. Для дополнительной помощи обращайтесь к основной документации проекта.*