Files
ptera-py-manager/README.md
T

262 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ⚡ 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**. Распространяется свободно для личного и коммерческого использования.