virtuality/README.md

# Virtuality

Платформа управления виртуализацией для одиночной Linux-ноды: KVM/QEMU/libvirt плюс собственная web-панель на FastAPI. Предназначена для администратора домашнего сервера, VPS или ARM64-платы (Raspberry Pi, Orange Pi 5), которому нужен упрощённый аналог Proxmox: создание VM из ISO, управление питанием, NAT/bridge-сеть с пробросом портов, web-консоль noVNC, журнал фоновых операций и самообновление ноды из git.

Установка выполняется одной командой; установщик сам определяет профиль хоста (x86_64 / raspberry-arm64 / orangepi5-arm64 / generic-arm64) и ставит соответствующий набор пакетов. Авторизация в панели — по существующему Linux-пользователю (PAM/shadow), отдельной базы пользователей нет.

Исходный README автора сохранён в `README.upstream.md` — там подробные разделы про порты, директории, диагностику, NAT Router и полезные команды.

## Стек

- Python 3, FastAPI, Uvicorn, Jinja2, itsdangerous (подписанные cookie-сессии)
- Bash — установщики, диагностика, сетевые скрипты, TUI-дашборд
- KVM, QEMU, libvirt (`virsh`, `virt-install`), Cockpit + Cockpit Machines
- nftables — NAT-роутер и port forwarding, netplan — настройка bridge `br0`
- noVNC + websockify — web-консоль VM
- systemd — юниты `virtuality-web`, `virtuality-auto-update.service/.timer`
- Хранение состояния — файлы JSON в `/var/lib/virtuality`, СУБД не используется
- Внешние API отсутствуют; обновления тянутся с GitHub (git pull или zip-архив ветки)

## Структура

| Путь | Назначение |
| --- | --- |
| `install.sh` | Основной установщик: проверка требований, apt-пакеты, клонирование репозитория, запуск установки ноды и панели |
| `bootstrap.sh` | Публичная точка входа one-command установки на чистый сервер |
| `install_virtuality_node.sh` | Установка компонентов ноды: KVM/QEMU/libvirt, Cockpit, storage pools, firewall |
| `setup_github_sync.sh` | Настройка git-синхронизации репозитория на ноде |
| `VERSION`, `updates/versions.json` | Текущая версия и манифест истории версий, используется центром обновлений панели |
| `web/app.py` | Базовое FastAPI-приложение панели: логин, дашборд, ISO, создание VM, карточка VM, сеть, операции, health |
| `web/network_core.py` | NAT-роутер, nftables-правила, port forwarding, диагностика сети |
| `web/host_profile.py` | Определение и чтение профиля хоста |
| `web/update_core.py` | Центр обновлений: сравнение версий и коммитов, запуск обновления, лог |
| `web/templates/` | Jinja2-шаблоны страниц панели (`dashboard`, `vm_create`, `vm_detail`, `iso`, `disk_images`, `network`, `logs`, `update`, `console`, `operations`, `login`, `_sidebar`) |
| `web/static/` | `app.css`, `themes.css` (переключаемые темы, включая MacOS Flat), `panel.js`, статическая база знаний |
| `scripts/install_web_panel.sh` | Установка панели в `/opt/virtuality/web`, venv, systemd-юнит, применение всех патчей |
| `scripts/patch_*.py` | ~28 python-патчей, дописывающих функциональность в **установленный** `app.py` (диски, boot order, автозапуск VM, noVNC, сетевые диапазоны, центр логов, центр обновлений и т. д.) |
| `scripts/setup_bridge_br0.sh` | Безопасная настройка bridge `br0` через netplan с бэкапом и откатом |
| `scripts/check_node.sh`, `virtuality_healthcheck.sh`, `virtuality_console_dashboard.sh` | Диагностика ноды, healthcheck-команда `vhealth`, консольный btop-подобный дашборд |
| `scripts/auto_update_check.sh`, `apply_github_update.sh` | Автообновление по systemd-таймеру и применение обновления |
| `scripts/create_test_vm.sh`, `clean_install.sh`, `fix_cockpit_auth.sh` | Вспомогательные операции |
| `docs/` | `ARCHITECTURE.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `FIRST_VM.md` |

Важная особенность архитектуры: репозиторный `web/app.py` — это **не** полный код панели. `install_web_panel.sh` копирует его в `/opt/virtuality/web/app.py` и затем последовательно применяет патч-скрипты из `scripts/`, которые вставляют в файл недостающие маршруты и функции (менеджер дисковых образов, web-консоль, центр логов, центр обновлений, сетевые доработки). Полная функциональность существует только после установки.

## Как запустить

Установка на чистый Ubuntu/Debian-сервер (требует root или sudo):

```bash
curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/install.sh | bash
```

Выбор Linux-пользователя для входа в панель:

```bash
curl -fsSL https://raw.githubusercontent.com/viktor138irk/virtuality/main/install.sh | VIRTUALITY_USER=<linux_user> bash
```

Установка из локального клона:

```bash
sudo bash install_virtuality_node.sh
sudo bash scripts/install_web_panel.sh
```

Обновление на ноде:

```bash
cd /opt/virtuality/source
sudo git pull
sudo bash scripts/install_web_panel.sh
sudo systemctl restart virtuality-web
```

Доступ после установки:

```text
Virtuality UI: http://SERVER_IP:8088
Cockpit:       https://SERVER_IP:9090
VNC:           5900-5999/tcp
```

Локальный запуск панели без установщика возможен (`uvicorn app:app` из `web/` после `pip install -r web/requirements.txt`), но функциональность будет урезана: не применены патч-скрипты, отсутствуют каталоги `/var/lib/virtuality`, `virsh` и права на libvirt. Полноценный dev-режим в репозитории не предусмотрен.

Минимальные требования (из `docs/REQUIREMENTS.md`): 2 ядра с VT-x/AMD-V, 4 GB RAM, 8 GB свободно на `/`, 20 GB под `/var/lib/virtuality`, Ubuntu Server 24.04 LTS или Debian-подобная система с apt.

## Конфигурация

Переменные окружения установщиков (`install.sh`, `bootstrap.sh`):

| Переменная | Назначение | Пример / по умолчанию |
| --- | --- | --- |
| `VIRTUALITY_USER` | Linux-пользователь для входа в панель | `viktor`; по умолчанию `SUDO_USER` или `root` |
| `VIRTUALITY_WEB_PORT` | Порт web-панели | `8088` |
| `VIRTUALITY_REPO_URL` | Источник исходников | `https://github.com/viktor138irk/virtuality.git` |
| `VIRTUALITY_INSTALL_URL` | URL самого установщика для self-install | raw.githubusercontent.com/... |
| `VIRTUALITY_PROJECT_BASE_DIR` / `VIRTUALITY_PROJECT_DIR` | Куда ставить проект | `/opt/virtuality`, `/opt/virtuality/source` |
| `VIRTUALITY_SETUP_BRIDGE` / `VIRTUALITY_BRIDGE_IFACE` | Настроить bridge `br0` и на каком интерфейсе | `0`, пусто |
| `VIRTUALITY_CREATE_TEST_VM` | Создать тестовую VM после установки | `0` |
| `VIRTUALITY_SKIP_REQUIREMENTS` | Пропустить проверку требований | `0` |
| `VIRTUALITY_MIN_ROOT_FREE_MB` / `MIN_VAR_FREE_MB` / `MIN_RAM_MB` / `MIN_CPU_CORES` | Пороги проверки требований | `8192` / `20480` / `4096` / `2` |
| `VIRTUALITY_CLEAN_BEFORE_INSTALL` | Очистка перед установкой | `0` |
| `VIRTUALITY_INSTALL_VERBOSE` | Подробный вывод установки | `0` |

Переменные времени выполнения панели (читаются из `/opt/virtuality/virtuality.env` и окружения):

| Переменная | Назначение | Значение по умолчанию |
| --- | --- | --- |
| `VIRTUALITY_AUTH_USER` | Linux-логин, который принимает форма входа | `viktor` |
| `VIRTUALITY_SESSION_SECRET` | Ключ подписи cookie-сессии | `dev-secret-change-me` — при установке генерируется и кладётся в `/var/lib/virtuality/config/session_secret` |
| `VIRTUALITY_SOURCE_DIR` | Каталог исходников для центра обновлений | `/opt/virtuality/source` |
| `VIRTUALITY_UPDATE_REMOTE` / `VIRTUALITY_UPDATE_BRANCH` | Git-remote и ветка обновлений | `origin` / `main` |
| `VIRTUALITY_UPDATE_ZIP_URL` | Резервный zip-источник обновления | архив ветки `main` на GitHub |

Пароль пользователя нигде не хранится — проверяется напрямую по системному shadow. Профиль хоста пишется в `/var/lib/virtuality/config/host_profile.json`.

## Состояние

Рабочий проект в активной разработке, доведённый до практического применения, но с сырой архитектурой (см. ниже). Версия по `VERSION` — `0.9.6`. 451 коммит, последний — 2026-05-07. С мая 2026 года работа в репозитории остановлена.

Разработка шла очень интенсивно двое суток (2026-05-06 — 2026-05-07): от «Initial commit» до 0.9.6. Значительная часть коммитов — механические bump-версии и правки вёрстки панели.

## Что не доделано

- Патч-архитектура вместо нормального кода. Функциональность панели разложена по ~28 скриптам `scripts/patch_*.py`, которые текстовым поиском/вставкой правят установленный `app.py`. Репозиторный `web/app.py` неполон, порядок применения патчей критичен, повторная сборка хрупкая. Это главный технический долг проекта.
- Тесты и CI отсутствуют полностью: нет ни тестов, ни `.github/workflows`, ни линтеров.
- Ролевой модели нет: один Linux-пользователь = полный доступ к панели.
- HTTPS для панели не настраивается — только HTTP на порту 8088 (у Cockpit свой TLS).
- Кластеризация, backup/snapshot, cloud-init/cloud-image шаблоны заявлены в `docs/ROADMAP.md`, но в коде отсутствуют.
- Каталог `/var/lib/virtuality/backups` создаётся, но функций резервного копирования в панели нет.
- Явных `TODO`/`FIXME` в коде нет; незавершённость выражена в расхождении между ROADMAP и реализацией.
- Версия 0.9.6 так и не доведена до 1.0.