Files
ptera-py-manager/README.md
T

23 KiB
Raw Blame History

⚡ DevCoded PteraPyManager (v2.5)

PteraPyManager — продвинутый интерактивный супервизор процессов и менеджер Python-ботов. Разработан специально для мультизапуска и контроля нескольких ботов/скриптов в одном контейнере (яйце) Pterodactyl Panel, а также на любых Linux/Windows серверах.


🚀 Основные возможности

  • Мультипроцессорный супервизор: Запуск и независимый контроль любого количества Python-скриптов и фоновых воркеров.
  • Интеллектуальный авторестарт: Автоматический перезапуск упавших ботов с защитой от краш-штормов (restart_delay, экспоненциальный бэкофф и сброс счетчика при стабильной работе).
  • Корректное завершение (Tree Kill): Завершение не только родительского процесса, но и всего дерева дочерних подпроцессов (aiohttp-серверы, воркеры, ffmpeg и др.).
  • Управление версиями Python и автоматический Venv:
    • Вариант А: Автопоиск нужной версии Python (3.9, 3.10, 3.11, 3.12, 3.13) среди установленных в системе / контейнере.
    • Резерв Б: Автоматическая докачка автономного Portable CPython (python-build-standalone) без прав root / sudo.
    • Автосоздание venv: Автоматическое создание изолированного окружения .venv, обновление pip и установка зависимостей из requirements.txt при первом старте.
  • Квоты ресурсов (Resource Quotas): Мониторинг RAM каждого скрипта в реальном времени. Автоматический перезапуск (restart) или остановка (kill) при утечках памяти.
  • Автоматическая ротация логов: Ограничение размера лог-файлов на диске и автоматическая ротация архивов, предотвращающая переполнение дисковой квоты в контейнере.
  • Планировщик задач (Interval Schedule): Поддержка периодических задач (парсеров, генераторов бэкапов) с интервальным перезапуском.
  • Двусторонние уведомления (Telegram + Discord): Асинхронная очередь оповещений о падениях, рестартах, превышении памяти и обновлениях Git с красивыми цветными Embeds.
  • Git Auto-Updater c поддержкой SSH: Периодическая проверка репозитория, автоматический git pull, доустановка новых зависимостей и безопасный рестарт ботов. Полная поддержка Deploy Keys через SSH.
  • Интерактивная CLI-консоль: Управление через терминал с автодополнением по клавише Tab, подсказками при опечатках на базе RapidFuzz и живым просмотром логов (tail).

📦 Быстрый старт

1. Требования

  • Python 3.9+ (рекомендуется Python 3.10–3.12)
  • Git (для работы автообновления)

2. Установка зависимостей

git clone ssh://git@git.dev-core.me:2222/dev-core/ptera-py-manager.git
cd ptera-py-manager

# Рекомендуется создать базовый venv менеджера:
python3 -m venv .venv
source .venv/bin/activate  # На Windows: .venv\Scripts\activate

# Установка зависимостей менеджера:
pip install -r reqs.txt

3. Запуск

python manager.py

🐍 Интерпретатор по умолчанию и выбор версий Python

Какой Python используется по умолчанию?

  1. Для самого менеджера (manager.py):
    Используется тот интерпретатор, через который вы запустили менеджер (системный python3 контейнера или виртуальное окружение .venv, в котором выполнен запуск: sys.executable).
  2. Для управляемых задач (tasks):
    • Если в задаче не указаны ни python_version, ни venv, ни python_path: задача выполняется через тот же интерпретатор по умолчанию, на котором работает сам менеджер.
    • Если указан venv, но не указан python_version: виртуальное окружение задачи создается на базе текущего родительского Python.
    • Если указан python_version: менеджер автоматически ищет указанную версию в системе (Вариант А) или скачивает автономный переносимый бинарник нужной версии (Резерв Б).

Список поддерживаемых версий для поля python_version

В поле python_version в config.yaml указывается мажорная версия в формате "3.X". Поддерживаются следующие значения:

Значение в конфиге Ветка CPython Версия автодокачки (Резерв Б) Рекомендации по использованию
"3.12" Python 3.12 3.12.7+ ⚡ Рекомендуется — высокая производительность, современный синтаксис
"3.11" Python 3.11 3.11.10+ Отличная стабильность, ускоренное ядро CPython (Faster CPython)
"3.10" Python 3.10 3.10.15+ Максимальная совместимость со старыми библиотеками и ботами
"3.9" Python 3.9 3.9.20+ Для легаси-проектов
"3.13" Python 3.13 3.13.0+ Новейшая версия (экспериментальные фичи)

Пример указания в конфиге:

tasks:
  - name: my-bot
    script: "bots/bot.py"
    venv: "bots/bot/.venv"
    python_version: "3.10"       # Достаточно указать "3.10"
    auto_create_venv: true        # Менеджер сам создаст venv с Python 3.10
    allow_download_python: true   # Если в Pterodactyl нет Python 3.10, он скачается автоматически

🎮 Команды интерактивной консоли

В консоли менеджера (ptera-manager>) доступны следующие команды:

Команда Описание
status (или ps) Сводная цветная таблица: PID, статус, CPU %, RAM (с учетом квот), Uptime и число рестартов
list Список всех настроенных задач, их скрипты, флаги автостарта и расписания
start <имя> Запустить выбранную задачу
stop <имя> Остановить задачу с graceful-завершением дочерних процессов
restart <имя> Перезапустить задачу (с автоматическим обновлением файлов из Git)
start-all Запустить все незапущенные задачи
stop-all Остановить все задачи
restart-all Перезапустить все активные задачи (с автообновлением файлов из Git)
update [имя] (или git-pull [имя]) Проверить и подтянуть обновления из Git (для конкретной задачи или всех сразу)
logs <имя> [строк] Показать последние строки логов stdout и stderr (по умолчанию 25)
tail <имя> Трансляция логов задачи в реальном времени (выход: Ctrl+C)
info <имя> Подробная диагностика задачи (пути, интерпретатор, окружение, лимиты, ошибки)
install <имя> Принудительно установить/обновить requirements.txt для выбранной задачи
clean-logs <имя> Очистить файлы логов выбранной задачи
reload Перечитать конфигурационный файл config.yaml на лету
clear (или cls) Очистить экран консоли
exit (или quit, q) Корректно остановить все задачи и выйти из программы

💡 Автокомплит и поиск опечаток: Для всех команд и имен задач работает автодополнение по клавише Tab. Если вы опечатались (например, ввели ststus), система автоматически подскажет правильную команду.


⚙️ Подробный конфигурационный файл (config.yaml)

Ниже приведена детальная структура config.yaml с построчным описанием каждого параметра:

# ============================================================
#             PyTaskManager Configuration
# ============================================================

# ===================== TELEGRAM =====================
# Настройки оповещений в Telegram о событиях, крашах и рестартах
telegram:
  enabled: false                               # Включить/выключить Telegram-уведомления (true/false)
  token: "123456789:ABCdefGhIJKlmNoPQRsTUVw"   # Токен Telegram-бота от @BotFather
  chat_id: "123456789"                         # ID чата или пользователя для получения уведомлений

# ===================== DISCORD =====================
# Настройки оповещений в Discord через Webhook (с цветными Embeds)
discord:
  enabled: false                               # Включить/выключить Discord-уведомления (true/false)
  webhook_url: "https://discord.com/api/webhooks/..." # URL созданного вебхука канала
  username: "PyTaskManager"                    # Отображаемое имя бота в канале
  avatar_url: ""                               # Ссылка на аватарку бота (опционально)

# ===================== GIT AUTO-UPDATE =====================
# Автоматическая синхронизация с Git-репозиторием и поддержка SSH-ключей.
# Позволяет обновлять всех ботов на сервере по push в репозиторий.
git:
  enabled: false                               # Включить фоновую автосинхронизацию с Git
  repo_url: "ssh://git@git.dev-core.me:2222/dev-core/ptera-py-manager.git" # URL (SSH или HTTPS)
  branch: "main"                               # Отслеживаемая ветка (main / master)
  check_interval: 300                          # Интервал проверки обновлений в секундах (например, каждые 5 минут)
  ssh_key_path: "id_ed25519"                   # Путь к приватному SSH-ключу (для доступа к закрытым репо)
  auto_restart: true                           # Автоматически перезапустить активных ботов после git pull
  auto_install_reqs: true                      # Автоматически проверить и установить новые requirements.txt

# ===================== MONITORING =====================
# Настройки фонового мониторинга процессов и сбора метрик
monitoring:
  enabled: true                                # Включить супервизор и сбор метрик CPU/RAM
  interval: 5                                  # Интервал проверки состояния процессов (в секундах)
  log_metrics: false                           # Спамить ли замерами CPU/RAM в терминал каждые N секунд

# ===================== LOGGING =====================
# Хранение логов и автоматическая ротация для экономии дискового пространства
logging:
  dir: "logs"                                  # Папка для сохранения логов stdout и stderr
  manager_log: "logs/manager.log"              # Лог-файл самого менеджера процессов
  max_size_mb: 20.0                            # Максимальный размер файла лога перед ротацией (в MB)
  backup_count: 3                              # Сколько ротированных архивов хранить (.log.1, .log.2...)

# ===================== TASKS =====================
# Список контролируемых ботов и процессов
tasks:
  # Пример постоянного бота (24/7):
  - name: my-telegram-bot                      # Уникальное имя задачи
    script: "bots/tg_bot/main.py"              # Путь к исполняемому Python-скрипту
    args: ["--mode", "production"]             # Аргументы командной строки передаваемые скрипту
    autostart: true                            # Запускать ли бота при старте менеджера
    autorestart: true                          # Автоматически перезапускать при падении (exit code != 0)
    max_restarts: 5                            # Лимит попыток рестарта (0 - без ограничений)
    restart_delay: 3.0                         # Пауза перед рестартом в секундах (защита от краш-штормов)
    stable_uptime: 60.0                        # Время стабильной работы (сек) для сброса счетчика рестартов
    cwd: ""                                    # Рабочая папка задачи (если пусто — папка скрипта)

    # --- Персональный Git задачи (Gitea, GitHub, GitLab, кастомные SSH порты) ---
    # Репозиторий автоматически клонируется с сервера при первом старте, если его еще нет!
    git:
      enabled: true                            # Включить Git-синхронизацию для этой задачи
      repo_url: "ssh://git@git.dev-core.me:2222/dev-core/my-gitea-bot.git" # URL (поддерживает Gitea, кастомные порты и др.)
      branch: "main"                           # Ветка репозитория
      path: "bots/tg_bot"                      # Локальная папка для клонирования кода бота
      ssh_key_path: "keys/id_ed25519"          # Путь к SSH-ключу (Deploy Key) для доступа к репозиторию
      check_interval: 300                      # Интервал проверки обновлений в секундах
      auto_restart: true                       # Перезапускать ТОЛЬКО этого бота при появлении новых коммитов
      auto_install_reqs: true                  # Автоматически обновлять зависимости pip при изменениях

    # --- Виртуальное окружение и версии Python ---
    venv: "bots/tg_bot/.venv"                  # Папка для venv (создастся сама, если отсутствует)
    python_version: "3.10"                     # Нужная версия Python ("3.10", "3.11", "3.12"...)
    auto_create_venv: true                     # Автоматически создать venv при первом запуске
    allow_download_python: true                # Скачать portable Python (Резерв Б), если версии нет в системе
    python_path: ""                            # Прямой путь к интерпретатору (если нужно переопределить)

    # --- Квоты ресурсов (Resource Quotas) ---
    max_memory_mb: 500.0                       # Лимит оперативной памяти в MB
    memory_limit_action: "restart"             # Действие при превышении: "restart", "kill" или "alert"

    # --- Тип расписания (Schedule) ---
    schedule_type: "continuous"                # "continuous" (работа 24/7) или "interval" (периодический запуск)
    schedule_interval: 0                       # Интервал для типа "interval" (в секундах)

    # --- Переменные окружения и зависимости ---
    env:
      PYTHONIOENCODING: "utf-8"
      MY_CUSTOM_VAR: "example_value"
    requirements:
      enabled: true                            # Проверять и устанавливать зависимости
      path: "bots/tg_bot/requirements.txt"     # Путь к файлу зависимостей

  # Пример периодической задачи (запуск раз в 2 часа):
  - name: database-backup
    script: "scripts/backup.py"
    args: []
    autostart: true
    autorestart: false
    schedule_type: "interval"
    schedule_interval: 7200                    # Запуск каждые 7200 секунд (2 часа)
    requirements:
      enabled: false
      path: ""

🐙 Мульти-репозитории и поддержка Gitea / GitHub / GitLab

Каждая задача может иметь свой собственный независимый репозиторий:

  • Разные источники: Один бот может обновляться из вашей собственной Gitea (с кастомным SSH-портом 2222), второй — из приватного GitHub, третий — из GitLab.
  • Разные SSH-ключи (Deploy Keys): Для каждого бота в ssh_key_path можно указать свой приватный ключ (например, keys/bot1_key, keys/bot2_key), или использовать общий.
  • Поддержка нестандартных SSH-портов Gitea: Поддерживаются URL любого формата:
    • ssh://git@git.dev-core.me:2222/username/bot-repo.git
    • git@github.com:username/bot-repo.git
    • https://git.dev-core.me/username/bot-repo.git
  • Автоматический клон (Zero-Touch): Если вы добавили задачу в config.yaml, но папка бота еще пуста — менеджер при первом запуске сам сделает git clone, создаст виртуальное окружение, установит requirements.txt и запустит бота.
  • Изолированный перезапуск: При появлении нового коммита в репозитории бота my-bot, менеджер подтянет код и перезапустит только my-bot, не прерывая работу остальных скриптов.

🥚 Настройка в яйце Pterodactyl (Pterodactyl Egg)

  1. Файлы в контейнере: Загрузите файлы репозитория в корневую папку вашего сервера Pterodactyl.
  2. Команда запуска (Startup Command):
    python3 manager.py
    
  3. Настройка SSH для приватных репозиториев:
    • Сгенерируйте SSH-ключ: ssh-keygen -t ed25519 -C "ptera-manager" -f id_ed25519 -N ""
    • Добавьте открытый ключ id_ed25519.pub в Deploy Keys вашего Git-репозитория (GitHub / GitLab / Gitea).
    • Приватный ключ id_ed25519 оставьте в корне контейнера рядом с config.yaml.
    • В config.yaml укажите ssh_key_path: "id_ed25519".
    • Менеджер автоматически установит на ключ права 0600 и настроит StrictHostKeyChecking=no.

🛠 Архитектура проекта

ptera-py-manager/
├── core/
│   ├── __init__.py         # Метаданные пакета
│   ├── models.py           # Dataclass-модели настроек, квот, метрик и статусов задач
│   ├── logger.py           # Потокобезопасный цветной логгер с поддержкой UTF-8
│   ├── config.py           # Безопасный парсер YAML с защитой от сбоев при опечатках
│   ├── notifier.py         # Асинхронный диспетчер Telegram и Discord (Embeds)
│   ├── python_env.py       # Поиск версий Python (А), автодокачка Portable CPython (Б) и venv
│   ├── process.py          # ManagedTask: управление процессами, ротация логов, квоты RAM
│   ├── git_updater.py      # Git-синхронизатор с авто-pull и поддержкой SSH Deploy Keys
│   ├── manager.py          # ProcessManager: монитор процессов, синхронизация потоков, hot-reload
│   └── console.py          # Интерактивная консоль с RapidFuzz и автодополнением Tab
├── config.yaml             # Конфигурационный файл
├── manager.py              # Точка входа в программу
├── reqs.txt                # Зависимости Python
├── .gitignore              # Исключения Git (логи, ключи, кэш, .venv)
└── README.md               # Документация проекта

📄 Лицензия

Разработано Dev-Cored. Распространяется свободно для личного и коммерческого использования.