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):

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

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

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

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

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

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

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

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

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.