debian-manager/README.md

Debian Manager

Десктопное приложение на Python для централизованного управления несколькими Debian-серверами: обновления, мониторинг, пакеты, Docker, файлы, systemd, firewall, cron, плейбуки, групповые операции, деплой из Gitea.

Возможности

Модуль	Что умеет
Серверы	Добавление по паролю или SSH-ключу, теги, проверка подключения, онлайн-статус
Обзор	CPU/RAM/диск/load/сеть, история метрик, apt update, upgrade, dist-upgrade, reboot с ожиданием возврата
Пакеты	Список с разбивкой на системные/пользовательские/зависимости, поиск, установка, удаление (remove/purge), autoremove, блокировка удаления системных
Docker	Контейнеры (start/stop/restart/rm, логи, stats), образы (pull/rmi), тома, сети, system df, system prune
Файлы	SFTP-браузер: навигация, upload/download с прогрессом, удаление, переименование, mkdir, встроенный редактор (sudo-режим для root-файлов)
Сервисы	Список systemd-юнитов, start/stop/restart/enable/disable, просмотр journalctl, защита критичных юнитов (sshd, docker)
Firewall	UFW: статус, правила (добавить/удалить), enable/disable с автоматическим разрешением SSH-порта, пресеты («Только SSH», «Веб-сервер», «Docker-хост»), список прослушиваемых портов
Cron	Редактор crontab: расписание из 5 полей с человекочитаемым описанием («следующий запуск»), включение/выключение строк, бэкапы с откатом
Терминал	Интерактивная PTY-сессия по SSH + библиотека из ~40 команд обслуживания (пользователи, система, процессы, сеть, логи, пакеты, безопасность) с селектором и подстановкой параметров
Группы серверов	Фильтрация дашборда по тегам («локальные», «удалённые», «prod») — чипы в верхней панели
Планировщик	Задачи по cron: update/upgrade/бэкап/плейбук/отчёт/команда, пресеты, запуск по кнопке, Telegram-уведомление о результате
Мастер настройки	Первичная настройка сервера чекбоксами: hostname, часовой пояс, NTP, пользователь, утилиты, Docker, Portainer, ufw, fail2ban, автообновления, агент
Бэкапы	tar.gz на сервере → SFTP → локальный архив, история с размерами, запуск из планировщика
Отчёты	CSV со всеми серверами (онлайн, ОС, метрики) + последние 100 задач, открытие в проводнике
Portainer	Статус контейнера portainer на каждом сервере, установка/перезапуск, открытие веб-интерфейса в браузере
Агент-режим	Установка dm-agent на сервер одной кнопкой — метрики каждые 5 сек по HTTP (порт 9102), real-time без SSH-поллинга
Webhook-автодеплой	Привязка «репозиторий@ветка → сервер», push в Gitea → автоматический pull + compose up (порт 9100)
Proxmox VE	Список нод с метриками, VM/LXC с CPU/RAM, start/reboot/shutdown/stop, добавление VM как управляемого сервера по SSH
Темы	Тёмная/светлая — иконка в нижней части навигации и кнопка в Настройках, выбор сохраняется
Групповые операции	Массовый update/upgrade/reboot/команда/установка пакета по выбранным серверам, параллельно или rolling (по одному), fail-fast, прогресс по каждому серверу
Плейбуки	YAML-плейбуки с шагами shell/apt/ufw/systemd/docker/reboot, Jinja2-переменные, when-условия, запуск на сервере или группе, встроенные шаблоны («Новый сервер», «Docker-хост», «Обновить и перезагрузить»)
Сравнение	Diff установленных пакетов между двумя серверами: только на A / только на B / различаются версии
Gitea Deploy	Деплой docker-compose проектов из Gitea-репозитория: git clone/pull → docker compose up -d, .env вне git, история в журнале задач
Telegram	Уведомления об алертах мониторинга и завершении задач (настраивается в «Настройки»)
Журнал задач	Все длинные операции с полным логом выполнения

Требования

• Windows 10/11, Linux или macOS
• Python 3.11+
• Debian-сервер(ы) с SSH-доступом (пароль или ключ)
• Для Docker-модуля: Docker на сервере (устанавливается плейбуком «Docker-хост» одной кнопкой)

Установка

git clone <repo> debian-manager
cd debian-manager

# виртуальное окружение + зависимости
uv venv --python 3.12 .venv
uv pip install --python .venv/Scripts/python.exe \
    flet asyncssh sqlmodel pydantic httpx pyyaml jinja2 croniter websockets proxmoxer requests

# запуск
.venv/Scripts/python.exe -m app.main

Без uv — классический вариант:

.venv\Scripts\pip install flet asyncssh sqlmodel pydantic httpx pyyaml jinja2 croniter websockets proxmoxer requests
.venv\Scripts\python -m app.main

Первый запуск

1. При старте автоматически создаётся тестовый сервер Test VPS (132.243.17.164:2292) — удалите или отредактируйте его.
2. Откройте Серверы → Добавить сервер: укажите хост, порт, пользователя, пароль или путь к SSH-ключу, нажмите «Проверить подключение».
3. Кликните на сервер в списке или на дашборде — откроются вкладки управления.

Использование по разделам

Дашборд

Карточки всех серверов с живыми метриками (CPU/RAM/диск), статусом онлайн/оффлайн, ОС и аптаймом. Клик по карточке → страница сервера.

Обзор (вкладка сервера)

• apt update — обновить индекс пакетов
• Upgrade / Dist-upgrade — обновить систему, вывод в реальном времени в лог-панели
• Reboot — перезагрузка с автоматическим ожиданием возврата сервера (до 5 минут)
• Графики метрик, количество доступных обновлений

Пакеты

• Чипы фильтрации: Пользовательские / Системные / Зависимости / Все
• Поиск по имени
• Установить пакет — с поиском по apt-cache
• Кнопка удаления у каждого пакета (системные заблокированы), чекбокс purge
• Autoremove — очистка неиспользуемых зависимостей

Docker

• Контейнеры: start/stop/restart/rm, логи (последние 100 строк), live-статистика CPU/MEM
• Образы: pull с прогрессом, удаление
• Тома/Сети: список, удаление
• Система: docker system df, кнопка System prune с отчётом

Файлы

• Навигация по SFTP, иконки папок/файлов, права доступа
• Upload/Download с прогресс-баром (через нативный диалог выбора файла)
• Редактировать — текстовые файлы прямо в UI, чекбокс sudo для root-owned файлов (/etc/...)
• Удаление, переименование, создание папок

Сервисы

• Таблица юнитов: состояние (цвет), enabled, описание
• start/stop/restart одной кнопкой; для критичных (ssh, docker) — двойное подтверждение
• Поиск, фильтр «только failed»
• Просмотр логов (journalctl -u <unit>) справа

Firewall

• Включить ufw — порт текущего SSH-подключения разрешается автоматически (защита от отстрела себя)
• Таблица правил с номерами, удаление по номеру
• Добавить правило: порт/диапазон, allow/deny/limit, tcp/udp, from-адрес
• Пресеты: «Только SSH», «Веб-сервер» (80,443), «Docker-хост»
• Список прослушиваемых портов (ss -tlnp) для сверки с правилами

Cron

• Карточки задач с человекочитаемым описанием расписания и следующим запуском
• Чекбокс — включить/выключить строку (комментируется)
• Добавить задачу — валидация выражения в реальном времени
• Откатить к бэкапу — каждое сохранение пишется в БД, можно вернуть любую версию

Терминал

Интерактивная SSH-сессия прямо в приложении — не нужен отдельный PuTTY/Terminal.

• Подключиться — открывает PTY (xterm-256color), работают все интерактивные команды (top, nano, htop)
• Строка ввода внизу — любая команда, Enter — отправить
• Селектор команд — библиотека обслуживания по категориям:
  • Пользователи: список, добавить/удалить, смена пароля, sudo, группы, сессии
  • Система: аптайм, часовой пояс, NTP, locale, память, диски, SMART
  • Процессы: топ по CPU, дерево, поиск, kill, lsof
  • Сеть: IP, маршруты, порты, соединения, DNS, ping, wget
  • Логи: journalctl, ошибки за час, dmesg, авторизации, неудачные логины
  • Пакеты: update/upgrade, поиск, установленные вручную, история apt
  • Безопасность: fail2ban, ufw, открытые сокеты, SUID-файлы
• Команды, требующие параметра (имя пользователя, имя сервиса и т.п.) — появляется поле ввода
• Выбранная команда подсвечивается жёлтым в выводе, затем выполняется
• Очистить вывод — сброс буфера (максимум 500 строк)

Групповые операции

• Выбор серверов чекбоксами
• Операции: update, upgrade, dist-upgrade, reboot, произвольная команда, установка пакета
• Rolling — по одному серверу, ждать возврата, только потом следующий (для кластеров)
• Fail-fast — остановиться при первой ошибке
• Прогресс и лог по каждому серверу

Группы серверов

• У каждого сервера поле Теги (через запятую): локальные, удалённые, prod, docker…
• В верхней панели — чипы «Все» + каждый тег: фильтрация карточек дашборда
• Теги также используются как цель в планировщике и групповых операциях

Планировщик

Задачи по cron-расписанию, выполняются внутри приложения (даже при свёрнутом окне).

• Действия: apt update, upgrade, dist-upgrade, команда, бэкап, плейбук, отчёт, очистка метрик
• Цель: all или тег серверов
• Пресеты: ежедневный apt update, еженедельный upgrade, ежедневный бэкап /etc, очистка метрик, ежедневный отчёт, docker prune, проверка диска
• Кнопка запустить сейчас, включение/выключение чекбоксом, последний статус
• Результат отправляется в Telegram (если настроено)

Мастер первичной настройки

Один экран для подготовки нового сервера — отметьте нужное чекбоксами:

• Изменить hostname — поле для имени
• Часовой пояс — по умолчанию Asia/Ulaanbaatar
• NTP — синхронизация времени
• Обновить систему — apt update + dist-upgrade
• Создать пользователя — имя + пароль, сразу в группу sudo
• Базовые утилиты — curl, wget, htop, git, mc, net-tools
• Docker — docker.io + docker-compose + автозапуск
• Portainer — веб-интерфейс Docker на порту 9000
• Firewall (ufw) — пресет «Только SSH» + включение
• Fail2ban — защита SSH от перебора
• Автообновления безопасности — unattended-upgrades
• Агент мониторинга — dm-agent для real-time метрик

Рекомендуемый набор (update, утилиты, ufw, fail2ban, NTP) выбран по умолчанию — кнопка «Выбрать рекомендуемое».

Бэкапы

• Укажите сервер и пути (/etc, /home/user, /var/www)
• На сервере создаётся tar.gz → скачивается по SFTP в ~/.debian-manager/backups/<сервер>/
• Временный файл на сервере удаляется после скачивания
• История: дата, размер, статус, локальный путь
• Автоматические бэкапы — через планировщик (действие «бэкап»)

Отчёты

• Сгенерировать отчёт — CSV: все серверы (онлайн, ОС, uptime, CPU/RAM/диск) + последние 100 задач
• Файлы в ~/.debian-manager/reports/, открытие в проводнике из списка
• Автоматический отчёт — через планировщик (действие «отчёт»)

Portainer

• Карточка по каждому серверу: установлен ли Portainer, статус контейнера
• Открыть в браузере — http://<сервер>:9000
• Установить / Перезапустить одной кнопкой

Агент-режим

Для real-time метрик без SSH-поллинга:

1. Запустить приёмник — приложение слушает порт 9102
2. Установить агента на сервер — Python-скрипт (только stdlib, psutil опционально) + systemd unit dm-agent
3. Агент шлёт метрики каждые 5 сек по HTTP POST с токеном
4. Статус агента и последние метрики — на карточке сервера
5. Удалить агента — остановка и полное удаление с сервера

Если сервер за NAT — агент сам инициирует соединение к приложению, проброс портов не нужен (нужен лишь доступ сервера к ПК с приложением).

Webhook-автодеплой из Gitea

1. Приложение слушает порт 9100 (запускается автоматически)
2. На странице Gitea Deploy → Добавить привязку: репозиторий, сервер, ветка, compose-файл, .env
3. В Gitea: репозиторий → Настройки → Webhooks → создать:
   • URL: http://<IP-этого-ПК>:9100/webhooks/gitea
   • Метод: POST, событие: push
4. Push в указанную ветку → автоматический git pull + docker compose up -d на сервере
5. История автодеплоев — в Журнале задач (тип webhook)

Proxmox VE

Управление виртуальными машинами и LXC-контейнерами на гипервизоре Proxmox.

Настройка:

1. В Proxmox: Datacenter → Permissions → API Tokens → создать токен (например root@pam!dm-manager)
   • Важно: у токена должна быть роль PVEAuditor (или PVEAdmin) на пути /. Если включён «Privilege Separation» — добавьте права отдельно: Permissions → Add → API Token Permission
2. В приложении → Proxmox:
   • Хост — только IP или FQDN, без http:// (например 192.168.1.100)
   • Пользователь — root@pam
   • Token ID — dm-manager
   • Token Secret — значение токена
   • Проверять SSL — выключите для локальной сети без сертификатов
3. Сохранить и проверить — покажет версию Proxmox

Ошибка 403 Forbidden: у токена нет прав. Добавьте роль PVEAuditor/PVEAdmin на путь / в настройках токена.

Возможности:

• Карточка каждой ноды: CPU/RAM ноды, uptime, список VM/LXC
• По каждой VM: VMID, имя, тип (VM/LXC), статус, CPU/RAM
• Действия: start, reboot, shutdown (graceful), stop (жёсткое) — с подтверждением
• Добавить как сервер — определяет IP через QEMU Guest Agent (или из конфига LXC) и создаёт сервер в приложении с тегом proxmox → дальше полное управление по SSH

Для определения IP в VM должен быть установлен qemu-guest-agent (apt install qemu-guest-agent).

Темы

• Иконка ☀️/🌙 в нижней части левой навигации — мгновенное переключение
• Также кнопка в Настройки → Интерфейс
• Выбор сохраняется между запусками

Плейбуки

YAML-файлы в ~/.debian-manager/playbooks/. Пример:

name: "Настройка нового сервера"
vars:
  ssh_port: "22"
steps:
  - name: Обновить систему
    apt: {update: true, upgrade: dist}
  - name: Установить утилиты
    apt: {install: [curl, htop, git, ufw]}
  - name: Firewall
    ufw: {preset: "Только SSH"}
  - name: Включить ufw
    shell: "yes | ufw enable"
  - name: Установить Docker
    apt: {install: [docker.io, docker-compose]}
  - name: Запустить docker
    systemd: {unit: docker, action: "enable --now"}

Типы шагов: shell, apt (update/upgrade/install/remove/autoremove), ufw (preset/enable), systemd (unit/action), docker (compose up/down), reboot (wait). Поддерживаются Jinja2-переменные {{var}} и when: условие.

Сравнение

Выберите два сервера → таблица расхождений: что установлено только на одном, где различаются версии.

Gitea Deploy

1. Укажите URL и API-токен Gitea (токен: Gitea → Настройки → Приложения → Создать токен)
2. Загрузить репозитории → выберите репо, сервер, ветку, путь к compose-файлу
3. Опционально заполните .env (запишется на сервер, не попадёт в git)
4. Деплой — на сервере выполнится git clone/pull в /opt/stacks/<repo> + docker compose up -d

Настройки → Telegram

1. Создайте бота через @BotFather, получите токен
2. Узнайте chat_id через @userinfobot
3. Включите нужные триггеры: алерты мониторинга, завершение задач
4. Тест — проверочное сообщение

Запуск

Windows — двойной клик по run.bat или из терминала:

.venv\Scripts\python.exe -m app.main

Сборка в .exe (PyInstaller)

# установить PyInstaller
.venv\Scripts\pip install pyinstaller

# сборка одного exe (окно без консоли)
.venv\Scripts\pyinstaller --noconfirm --onefile --windowed \
    --name "DebianManager" \
    --add-data "app;app" \
    app/main.py

# результат: dist\DebianManager.exe

Примечания:

• --windowed убирает чёрную консоль; для отладки соберите без него — увидите traceback'и
• SQLite-база (~/.debian-manager/data.db) и плейбуки (~/.debian-manager/playbooks/) создаются в домашней папке пользователя, не рядом с exe — перенос exe на другую машину не переносит данные
• Flet при первом запуске exe скачивает свой runtime (~100 МБ) — нужен интернет
• Для уменьшения размера добавьте --exclude-module pytest и подобные

Структура проекта

app/
├── main.py              # точка входа Flet
├── core/                # бизнес-логика (SSH, apt, docker, sftp, ufw, cron, плейбуки...)
├── db/                  # SQLModel: Server, TaskRecord, MetricSnapshot, CronBackup, Setting
└── ui/
    ├── pages/           # дашборд, серверы, групповые операции, плейбуки, diff, gitea, задачи, настройки
    ├── tabs/            # вкладки сервера: обзор, пакеты, docker, файлы, сервисы, firewall, cron
    └── components.py    # диалоги, лог-панель, хелперы
tests/                   # юнит-тесты парсеров (cron, packages)
scripts/                 # утилиты для ручной проверки сервера

Безопасность

• Пароли хранятся в SQLite (~/.debian-manager/data.db) — для продакшена перенесите в ОС keyring
• Все деструктивные действия (reboot, purge, prune, удаление) — с диалогом подтверждения и именем сервера
• Удаление системных пакетов (priority required/important) заблокировано
• При включении ufw текущий SSH-порт разрешается автоматически
• Stop/restart критичных systemd-юнитов (sshd, docker) — с двойным подтверждением
• Журнал задач — полный аудит всех операций с логами

Тестирование

.venv/Scripts/python.exe -m pytest tests/ -v
# 9 тестов парсеров cron и packages

Известные ограничения

• Графики метрик — текстовые (в Flet 0.86 удалён LineChart; замените на flet-charts или plotly при необходимости)
• Нет мультипользовательского режима и ролей
• Webhook-сервер слушает на 0.0.0.0:9100 без TLS — используйте в доверенной сети или за reverse-proxy