PyGuardian/documentation/guides/CLUSTER_SETUP.md

🌐 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: Установка мастер-сервера

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

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

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

# /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: Перезапуск мастер-сервера

sudo systemctl restart pyguardian
sudo systemctl status pyguardian

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

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

# Синтаксис: /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

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

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

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

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

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

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

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

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

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

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

# 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 ключи (рекомендуется)

# На мастер-сервере сгенерировать 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

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

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

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

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

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

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

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

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

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

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

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

# Проверка 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

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

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

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

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

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

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

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

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

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

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

# Увеличить таймауты в 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. Удалить файлы агента на сервере

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

# На мастер-сервере через 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
• Telegram: @pyguardian_support