262 lines
20 KiB
Markdown
262 lines
20 KiB
Markdown
# ⚡ 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**. Распространяется свободно для личного и коммерческого использования.
|