PyGuardian/.history/QUICKSTART_20251125204704.md

PyGuardian Quick Start Guide

Быстрое руководство по развертыванию и настройке

#==========================================================================

🚀 Быстрый старт для автономного сервера

#==========================================================================

Шаг 1: Загрузка и подготовка

# Клонировать репозиторий
git clone https://github.com/your-repo/PyGuardian.git
cd PyGuardian

# Проверить систему
./scripts/test-install.sh

# Если все тесты пройдены, продолжить установку

Шаг 2: Быстрая установка

# Автоматическая установка в автономном режиме
sudo ./install.sh

# Или через Makefile
sudo make install

Шаг 3: Настройка Telegram бота

# Получить токен бота от @BotFather в Telegram
# Заменить YOUR_BOT_TOKEN_HERE в конфигурации
sudo nano /opt/pyguardian/config/config.yaml

# Получить свой Telegram ID (отправить /start боту @userinfobot)
# Добавить в admin_users: [ВАШ_ID]

Шаг 4: Запуск системы

# Запустить службу
sudo systemctl start pyguardian
sudo systemctl enable pyguardian

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

Шаг 5: Тестирование

# Отправить /start вашему боту в Telegram
# Если получили приветственное сообщение - система работает!

# Проверить статус через бота
/status

# Просмотреть логи
/logs system

#==========================================================================

🔗 Быстрый старт для кластера (контроллер + агенты)

#==========================================================================

Контроллер (центральный сервер)

Шаг 1: Установка контроллера

# На главном сервере
git clone https://github.com/your-repo/PyGuardian.git
cd PyGuardian

# Установка в режиме контроллера
sudo ./install.sh --mode controller

# Или
sudo make controller

Шаг 2: Настройка контроллера

# Настроить Telegram бота и кластерные параметры
sudo nano /opt/pyguardian/config/config.yaml

# Обязательно настроить:
# - telegram.bot_token
# - telegram.admin_users  
# - cluster.api_secret
# - cluster.deployment.ssh_key_path

Шаг 3: Генерация SSH ключей для кластера

# Создать SSH ключи для автоматического развертывания
sudo ssh-keygen -t ed25519 -f /root/.ssh/cluster_key -N ""

# Скопировать публичный ключ на целевые серверы
sudo ssh-copy-id -i /root/.ssh/cluster_key.pub root@192.168.1.50
sudo ssh-copy-id -i /root/.ssh/cluster_key.pub root@192.168.1.51

Шаг 4: Запуск контроллера

sudo systemctl start pyguardian-controller
sudo systemctl enable pyguardian-controller

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

Агенты (управляемые серверы)

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

# Отправить боту команду для добавления сервера
/cluster add

# Следовать интерактивным инструкциям бота:
# 1. Ввести IP адрес сервера
# 2. Указать SSH пользователя (обычно root)
# 3. Выбрать аутентификацию по ключу
# 4. Подтвердить развертывание

# Проверить статус кластера
/cluster status

Ручное развертывание агента

# На каждом управляемом сервере
wget https://your-server/install.sh
chmod +x install.sh

# Установить агента
sudo ./install.sh --mode agent --controller 192.168.1.10

# Или
sudo make agent CONTROLLER_IP=192.168.1.10

#==========================================================================

🐳 Быстрый старт с Docker

#==========================================================================

Автономный контейнер

# Создать образ
docker build -t pyguardian .

# Запустить контейнер
docker run -d \
  --name pyguardian \
  --privileged \
  --network host \
  -v $(pwd)/config:/opt/pyguardian/config \
  -v $(pwd)/data:/opt/pyguardian/data \
  pyguardian

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

Docker Compose для кластера

# Настроить docker-compose.yml
cp examples/configurations.md docker-compose.yml
nano docker-compose.yml

# Запустить кластер
docker-compose up -d

# Проверить статус
docker-compose ps
docker-compose logs pyguardian-controller

Использование готового Docker образа

# Скачать готовый образ
./scripts/docker-install.sh

# Или запустить автоматическую Docker установку
sudo make docker-install

#==========================================================================

⚙️ Основные команды после установки

#==========================================================================

Управление службой

# Статус службы
sudo systemctl status pyguardian

# Перезапуск службы
sudo systemctl restart pyguardian

# Просмотр логов
sudo journalctl -u pyguardian -f

# Остановка службы
sudo systemctl stop pyguardian

Управление конфигурацией

# Редактировать конфигурацию
sudo nano /opt/pyguardian/config/config.yaml

# Проверить конфигурацию
/opt/pyguardian/venv/bin/python -c "import yaml; yaml.safe_load(open('/opt/pyguardian/config/config.yaml'))"

# Перезагрузить конфигурацию
sudo systemctl reload pyguardian

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

# Основные команды бота
/start     - Начать работу с ботом
/help      - Показать справку
/status    - Статус системы
/sessions  - Активные сессии
/logs      - Просмотр логов

# Кластерные команды (только для контроллера)
/cluster status  - Статус кластера
/cluster add     - Добавить сервер
/cluster logs    - Логи агентов

#==========================================================================

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

#==========================================================================

Проблема: Telegram бот не отвечает

# Проверить токен бота
grep bot_token /opt/pyguardian/config/config.yaml

# Проверить подключение к Telegram API
curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

# Проверить логи службы
sudo journalctl -u pyguardian | grep -i telegram

Проблема: Агент не подключается к контроллеру

# На агенте проверить конфигурацию
grep controller_host /opt/pyguardian/config/config.yaml

# Проверить сетевое подключение
telnet CONTROLLER_IP 8443

# Проверить логи агента
sudo journalctl -u pyguardian-agent | grep -i connection

Проблема: Высокое использование ресурсов

# Проверить процессы PyGuardian
ps aux | grep python | grep pyguardian

# Проверить размер базы данных
du -sh /opt/pyguardian/data/

# Оптимизировать базу данных
sqlite3 /opt/pyguardian/data/pyguardian.db "VACUUM;"

Проблема: Ошибки файрвола

# Проверить правила iptables
sudo iptables -L -n

# Проверить логи файрвола
sudo tail -f /var/log/kern.log | grep -i iptables

# Временно отключить файрвол PyGuardian
sudo iptables -F PYGUARDIAN 2>/dev/null || true

#==========================================================================

📚 Дополнительные ресурсы

#==========================================================================

Документация

• README.md - Общее описание проекта
• docs/INSTALLATION.md - Подробное руководство по установке
• docs/CLUSTER_SETUP.md - Настройка кластера
• examples/configurations.md - Примеры конфигураций
• examples/telegram-commands.md - Команды Telegram бота

Полезные команды

# Проверить версию PyGuardian
/opt/pyguardian/venv/bin/python main.py --version

# Создать резервную копию
sudo tar -czf pyguardian-backup-$(date +%Y%m%d).tar.gz \
  /opt/pyguardian/config \
  /opt/pyguardian/data

# Обновить систему
cd /opt/pyguardian
sudo git pull origin main
sudo systemctl restart pyguardian

# Полная переустановка
sudo ./install.sh --reinstall

Мониторинг и метрики

# Статистика файрвола
sudo iptables -L -v -n

# Использование ресурсов
htop
df -h
free -h

# Сетевые соединения
sudo netstat -tulpn | grep python

# Логи в реальном времени
sudo tail -f /opt/pyguardian/logs/pyguardian.log

#==========================================================================

🎯 Чек-лист после установки

#==========================================================================

✅ Проверить после установки автономного режима:

• Служба PyGuardian запущена и активна
• Telegram бот отвечает на команды
• Конфигурация корректна и загружена
• База данных создана и доступна
• Файрвол настроен и работает
• Мониторинг ресурсов активен
• Логи пишутся корректно

✅ Проверить после установки кластера:

• Контроллер запущен и доступен
• API кластера отвечает на запросы
• SSH ключи настроены для развертывания
• Агенты подключены к контроллеру
• Кластерные команды работают в Telegram
• Синхронизация конфигураций работает
• Мониторинг всех узлов активен

✅ Проверить после Docker установки:

• Контейнеры запущены и работают
• Volumes примонтированы корректно
• Привилегированный режим работает
• Сеть host доступна
• Логи контейнеров доступны
• Автоперезапуск настроен

#==========================================================================

🆘 Получение поддержки

#==========================================================================

Сбор диагностической информации

# Создать диагностический отчет
sudo /opt/pyguardian/scripts/diagnostic-report.sh

# Отправить логи разработчикам
# В Telegram боте: /debug export

Контакты для поддержки

• 📧 Email: support@smartsoltech.com
• 💬 Telegram: @PyGuardianSupport
• 🐛 Issues: GitHub Issues
• 📖 Wiki: GitHub Wiki

Перед обращением в поддержку:

1. Запустить тест установки: ./scripts/test-install.sh
2. Собрать диагностическую информацию
3. Описать проблему и шаги для воспроизведения
4. Приложить релевантные логи и конфигурации

---

🎉 Поздравляем! PyGuardian готов к работе!

Ваша система безопасности настроена и готова защищать серверы. Не забудьте настроить регулярные резервные копии и мониторинг обновлений.

Happy securing! 🛡️