Документация была переписана под версию 0.11: README, образ, первая машина, архитектура, требования, планы

README описывает продукт как простую замену Proxmox для дома: три способа установки (ISO из GitHub Actions или make iso, одна команда, вручную), первую загрузку и мастер настройки, возможности, страницу «Настройки», команды virtuality-ctl, обновления и откат, удаление, диагностику и разработку. Упоминания Cockpit, консольного dashboard, тестовых скриптов, эмуляции ARM64 на x86 и PXE убраны; таблица скриншотов сохранена и дополнена существующими снимками. docs/IMAGE.md — сборка ISO и все параметры image/build-iso.sh, вопросы установщика, этапы первой загрузки, тема GRUB, артефакты CI, проверка и запись на флешку. docs/FIRST_VM.md — первая машина только через панель: Ubuntu 26.04 из каталога с cloud-init, Windows 11 с ISO, экран, проброс портов, снимки, резервные копии. docs/ARCHITECTURE.md — текущее устройство: модули web/, virtuality-ctl, задачи, службы systemd, TLS, firewall, сеть NAT с резервациями, хранилище, обновления. docs/REQUIREMENTS.md — оборудование, ОС, ARM64, сеть, браузер. docs/ROADMAP.md — что сделано в 0.11 и что планируется. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LEUXMcdZo7b87mjkUsPgg
2026-09-25 15:41:03 +00:00
@@ -1,104 +1,138 @@
-# Первая тестовая виртуальная машина
+# Первая виртуальная машина

-Этот документ фиксирует проверку первого рабочего сценария Virtuality: сеть `br0`, libvirt storage pools и запуск тестовой VM.
+Всё в этом документе делается через панель в браузере — терминал не понадобится. Считаем, что Virtuality установлена и мастер настройки пройден (см. README).

-## Требования
+Сначала — самый быстрый путь: готовая Ubuntu за минуту. Потом — установка Windows 11 с ISO, экран машины, доступ снаружи, снимки и резервные копии.

-Перед созданием VM должны быть готовы:
+---

- KVM/QEMU;
- libvirt;
- Cockpit;
- storage pools `virtuality-images` и `virtuality-iso`;
- bridge `br0`;
- default route через `br0`.
+## 1. Быстрая машина из каталога: Ubuntu Server 26.04

-Проверка:
+Готовые (облачные) образы — это уже установленная система без пароля. Панель скачивает образ, делает из него диск нужного размера и через cloud-init настраивает первый вход: пользователя, пароль, SSH-ключ.
+
+### Скачать образ
+
+1. Откройте **Образы ОС** → вкладка **Готовые системы**.
+2. В карточке **Каталог готовых систем** найдите **Ubuntu Server 26.04 LTS** (помечена «Рекомендуем») и нажмите **Скачать**. Сервер скачает образ с сайта Ubuntu сам и проверит контрольную сумму; ход виден в **Задачах** и на этой же странице.
+3. Когда образ отмечен «Загружен», рядом появится кнопка **Создать машину** — она открывает мастер с уже выбранным образом.
+
+В каталоге также Ubuntu Server 24.04 LTS, Debian 13 и Alpine Linux 3.23. Свой образ (`.qcow2`, `.img`, `.raw`, `.img.xz`) можно загрузить с компьютера перетаскиванием или скачать по ссылке в карточке **Скачать по ссылке**.
+
+### Создать машину
+
+Шаг **1. Название и система**:
+
+- **Название машины** — латиница, цифры, точка, дефис, подчёркивание (например, `ubuntu-1`). Это же имя станет именем компьютера внутри системы.
+- Источник **Готовая система** уже выбран, образ подставлен.
+- Переключатель **Настроить первый вход** должен быть включён: у готовых образов нет пароля, без этого шага в машину не войти.
+  - **Пользователь** — панель подставляет стандартного пользователя образа (`ubuntu`, у Debian — `debian`, у Alpine — `alpine`); можно указать свой. Он получит права администратора (`sudo`).
+  - **Пароль** — не короче 6 символов.
+  - **SSH-ключ** — необязательно; вставьте содержимое `~/.ssh/id_ed25519.pub`. Если указать только ключ без пароля, вход по SSH будет только по ключу.
+
+Шаг **2. Мощность**: выберите профиль — **Мини** (1 ядро, 1 ГБ, 10 ГБ), **Стандарт** (2 ядра, 4 ГБ, 40 ГБ), **Мощная** (4 ядра, 8 ГБ, 80 ГБ) — или задайте ядра, память и диск сами. Диск образа увеличивается до выбранного размера, а система при первой загрузке сама расширит файловую систему.
+
+Шаг **3. Сеть**: **Автоматически** — машина получит постоянный адрес `192.168.100.x` в отдельной сети и выйдет в интернет через сервер; снаружи её не видно, пока вы не откроете доступ. **В локальной сети** (если в мастере настройки выбран мост) — машина станет устройством вашей домашней сети и получит адрес от роутера.
+
+Справа в **Итого** проверьте сводку и нажмите **Создать машину**. Панель откроет страницу задачи с живым журналом. Обычно в пределах минуты появится «Машина создана. Вход: ubuntu по паролю. Адрес в сети машин: 192.168.100.x».
+
+### Войти
+
+Откройте страницу машины (из **Обзора**) → **Открыть экран** и войдите с указанными пользователем и паролем. В машину сразу ставится гостевой агент, поэтому её адрес виден на странице машины и в **Сети и доступе** — по нему можно зайти по SSH из локальной сети (если выбран мост) или после проброса порта (см. ниже).
+
+---
+
+## 2. Windows 11 с установочного ISO
+
+### Загрузить ISO
+
+1. Скачайте ISO Windows 11 с сайта Microsoft на свой компьютер.
+2. **Образы ОС** → вкладка **Установочные образы** → перетащите файл в окно загрузки. Или вставьте прямую ссылку на `.iso` в карточку **Скачать по ссылке** — сервер скачает его сам.
+
+### Создать машину
+
+1. **Создать машину** → шаг 1: название (например, `win11`), источник **Установить с диска**, выберите ISO.
+2. **Что будете устанавливать** → **Windows 11 / Server 2025**. Панель сама включит UEFI и виртуальный TPM 2.0 (без него Windows 11 отказывается ставиться), подберёт диск SATA и сетевую карту Intel — драйверы во время установки не нужны.
+3. Шаг 2: профиль **Мощная** (4 ядра, 8 ГБ, 80 ГБ) — Windows 11 требует минимум 4 ГБ памяти и 64 ГБ диска.
+4. Шаг 3: сеть — как и для Linux.
+5. **Создать машину**. Задача завершится за несколько секунд — машина создана и запущена с установочного диска.
+
+### Установить систему
+
+1. На странице машины нажмите **Открыть экран**. Сразу после запуска Windows показывает «Press any key to boot from CD or DVD» — нажмите любую клавишу в окне экрана, иначе загрузка с диска пропустится. Если пропустили — **Перезагрузить** на странице машины и попробовать снова.
+2. Дальше установка идёт как на обычном компьютере. Диск в установщике будет пустым — выберите его целиком.
+3. После установки на странице машины откройте вкладку **Диски и загрузка** → **Привод CD/DVD** и извлеките установочный образ, чтобы машина больше не предлагала загрузку с него.
+
+Для других систем выбирайте тип **Linux** (Ubuntu, Debian, Fedora и другие), **Windows 10 / Server 2019–2022** (классическая загрузка) или **Другая система**.
+
+---
+
+## 3. Экран машины
+
+- Кнопка **Открыть экран** на странице машины открывает экран в новой вкладке браузера — это как монитор, подключённый к машине. Работает и для установки системы, и когда сеть внутри машины ещё не настроена.
+- Если курсор «застрял» внутри экрана, нажмите **Ctrl + Alt**.
+- Экран доступен только через панель: VNC-порты машин наружу не открываются, соединение идёт через сервер по вашей сессии.
+- Для повседневной работы удобнее подключаться по SSH (Linux) или по удалённому рабочему столу (Windows) — как открыть к ним доступ, ниже.
+
+---
+
+## 4. Доступ к машине снаружи (проброс портов)
+
+В сети **Автоматически (NAT)** машины не видны ни из домашней сети, ни из интернета, пока вы не откроете нужный порт на сервере.
+
+1. Откройте **Сеть и доступ** → карточка **Открыть доступ**.
+2. **Машина** — выберите машину (рядом показан её адрес).
+3. **Что открыть** — сервис из списка: **SSH — удалённый доступ к Linux**, **Сайт (HTTP)**, **Сайт (HTTPS)**, **Удалённый рабочий стол Windows (RDP)**, **Minecraft**, MySQL, PostgreSQL, OpenVPN, WireGuard и другие — или **Другой порт**.
+4. **Порт в машине** заполнится сам (для SSH — `22`), **Порт на сервере** — например, `2222`. Протокол TCP или UDP подставляется по сервису. Можно указать диапазон вида `10000-20000`.
+5. Нажмите **Открыть доступ**. Теперь `адрес-сервера:2222` ведёт в машину:
+
+   ```bash
+   ssh ubuntu@адрес-сервера -p 2222
+   ```
+
+   Для Windows выберите **RDP** и подключайтесь приложением «Подключение к удалённому рабочему столу» по адресу `адрес-сервера:3389` (или другому порту сервера, который вы указали).
+
+Кнопка **Проверить** рядом с правилом покажет, доходит ли трафик до машины и слушает ли она порт. Правила восстанавливаются после перезагрузки сервера сами. Чтобы сервис был доступен из интернета, дополнительно пробросьте тот же порт на роутере на адрес сервера.
+
+Адреса в сети NAT закреплены за машинами по имени, поэтому пробросы не ломаются после перезагрузок. Если адрес машины не определился (например, система внутри ещё не запущена), в карточке **Адреса машин** его можно указать вручную.
+
+Машинам в режиме **В локальной сети** проброс не нужен: у них свой адрес от роутера, как у ноутбука или телефона.
+
+---
+
+## 5. Снимок перед рискованными изменениями
+
+Снимок — точка восстановления машины: перед обновлением системы, экспериментом с настройками или установкой сомнительной программы.
+
+1. Страница машины → вкладка **Снимки** → карточка **Создать снимок**, при желании впишите описание («перед обновлением») → **Создать снимок**.
+2. У работающей машины в снимок попадает и память — она на несколько секунд замрёт, зато вернётся ровно в то же состояние с открытыми программами. У выключенной сохраняется только диск.
+3. Если что-то пошло не так — **Вернуться** рядом с нужным снимком. Машина откатится к тому моменту; всё, что сделано после снимка, пропадёт.
+4. Ненужные снимки удаляйте: они занимают место внутри диска машины. На одну машину — до 8 снимков.
+
+Ограничения: снимки работают только с дисками qcow2 (все машины, созданные панелью, такие). Для машин с UEFI-прошивкой (Windows 11, образы Alpine, все машины на ARM64) внутренние снимки в текущей версии libvirt недоступны — панель предупредит; для них используйте резервные копии.
+
+---
+
+## 6. Резервная копия
+
+Резервная копия — полная копия настроек машины и всех её дисков в отдельной папке на сервере. В отличие от снимка, она не зависит от диска машины и переживёт его повреждение.
+
+1. Страница машины → вкладка **Резервные копии** → **Создать копию** (заметка по желанию). Работающая машина будет корректно выключена, скопирована и запущена снова — в списке машин в это время видно, что происходит.
+2. Копии всех машин собраны в разделе **Резервные копии**; они лежат в `/var/lib/virtuality/backups/<машина>/<дата-время>/`. Ход создания виден в **Задачах**, страницу можно закрыть.
+3. **Восстановить**: выберите копию → укажите название — то же (тогда текущую машину придётся заменить, панель попросит подтверждение) или новое (получите вторую машину рядом с первой). Восстановленная машина создаётся выключенной. Файлы копии остаются на месте, восстанавливать из неё можно сколько угодно раз.
+4. Перед восстановлением панель проверяет, хватит ли места в `/var/lib/virtuality`.
+
+Копию можно делать и по расписанию из терминала сервера — например, задачей cron:

 ```bash
-sudo vhealth
-ip -br a
-ip route
-virsh pool-list --all
+sudo /opt/virtuality/venv/bin/python /opt/virtuality/web/features/backups.py web01 "ночная копия"
 ```

-Нормальная сеть:
+---

-```text
-enp2s0  UP
-br0     UP  10.0.0.200/24
-default via 10.0.0.1 dev br0
-```
+## Что дальше

-## Создание тестовой VM
-
-```bash
-cd ~/virtuality
-git pull
-sudo bash scripts/create_test_vm.sh
-```
-
-По умолчанию создаётся VM:
-
-```text
-Name:   test-alpine
-RAM:    1024 MB
-CPU:    1 vCPU
-Disk:   8 GB qcow2
-ISO:    Alpine Linux
-Network: br0
-Graphics: VNC
-```
-
-Можно задать имя:
-
-```bash
-sudo bash scripts/create_test_vm.sh test-alpine-2
-```
-
-## Проверка
-
-```bash
-virsh list --all
-sudo virsh vncdisplay test-alpine
-sudo vhealth
-```
-
-Если `vncdisplay` показывает `:0`, значит порт VNC — `5900`.
-
-Если показывает `:1`, значит порт VNC — `5901`.
-
-## Доступ через Cockpit
-
-Открыть:
-
-```text
-https://SERVER_IP:9090
-```
-
-Дальше:
-
-```text
-Virtual machines → test-alpine → Console
-```
-
-## Что считается успешным результатом
-
-Этап считается пройденным, если:
-
- VM появилась в `virsh list --all`;
- VM запущена;
- консоль открывается в Cockpit или через VNC;
- VM подключена к bridge `br0`;
- `sudo vhealth` не показывает критических ошибок по Virtuality.
-
-## Следующий этап
-
-После первой тестовой VM можно переходить к разработке собственной панели управления Virtuality:
-
- список VM;
- статусы VM;
- запуск/остановка;
- просмотр storage pools;
- создание VM через UI;
- базовый журнал событий.
+- **Клонировать** (меню на странице машины) — точная копия с новым именем и своим адресом, удобно для тестов.
+- **Спящий режим** — сохранить память на диск и выключить; после запуска машина продолжит с того же места.
+- **Автозапуск** — переключатель на странице машины: машина включится сама после перезагрузки сервера.
+- **Ресурсы** — процессор и память можно поменять, когда машина выключена; диск — увеличить в любой момент во вкладке **Диски и загрузка**.
+- Раздел **Помощь** в панели повторяет главное из этого документа.