20 KiB
⚡ 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 используется по умолчанию?
- Для самого менеджера (
manager.py):
Используется тот интерпретатор, через который вы запустили менеджер (системныйpython3контейнера или виртуальное окружение.venv, в котором выполнен запуск:sys.executable). - Для управляемых задач (
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 <имя> |
Перезапустить задачу |
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 с построчным описанием каждого параметра:
# ============================================================
# 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)
- Файлы в контейнере: Загрузите файлы репозитория в корневую папку вашего сервера Pterodactyl.
- Команда запуска (Startup Command):
python3 manager.py - Настройка 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.
- Сгенерируйте SSH-ключ:
🛠 Архитектура проекта
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. Распространяется свободно для личного и коммерческого использования.