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-хост» одной кнопкой)

## Установка

```bash
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` — классический вариант:
```bash
.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/`. Пример:

```yaml
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`** или из терминала:
```bash
.venv\Scripts\python.exe -m app.main
```

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

```bash
# установить 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) — с двойным подтверждением
- Журнал задач — полный аудит всех операций с логами

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

```bash
.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