# ⚡ 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. Установка зависимостей ```bash 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. Запуск ```bash 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+ | Новейшая версия (экспериментальные фичи) | #### Пример указания в конфиге: ```yaml 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 <имя>` | Перезапустить задачу | | `start-all` | Запустить все незапущенные задачи | | `stop-all` | Остановить все задачи | | `restart-all` | Перезапустить все активные задачи | | `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` с построчным описанием каждого параметра: ```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: "" # Рабочая папка задачи (если пусто — папка скрипта) # --- Виртуальное окружение и версии 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: "" ``` --- ## 🥚 Настройка в яйце Pterodactyl (Pterodactyl Egg) 1. **Файлы в контейнере:** Загрузите файлы репозитория в корневую папку вашего сервера Pterodactyl. 2. **Команда запуска (Startup Command):** ```bash 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`. --- ## 🛠 Архитектура проекта ```text 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**. Распространяется свободно для личного и коммерческого использования.