Claude
526ef3effd
Build ISO image / ISO ${{ fromJSON(github.event_name == 'workflow_dispatch' && (inputs.arch == 'both' && '["amd64","arm64"]' || format('["{0}"]', inputs.arch)) || '["amd64","arm64"]') }} (push) Canceled after 0s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019LEUXMcdZo7b87mjkUsPgg
63 строки
6.0 KiB
Markdown
63 строки
6.0 KiB
Markdown
# Virtuality — заметки для Claude Code
|
|
|
|
Virtuality — простая замена Proxmox для дома и малого офиса: KVM/QEMU/libvirt + собственная
|
|
веб-панель на FastAPI, установочный ISO на базе чистого Ubuntu Server 26.04 LTS и мастер
|
|
первичной настройки в браузере. Пользователь — обычный человек, не админ.
|
|
|
|
**Общайся с владельцем проекта по-русски.** Весь текст интерфейса — на простом русском, без жаргона
|
|
(термины вроде qcow2, libvirt, nvram — только в раскрывающихся блоках «Для специалистов»).
|
|
|
|
## Устройство репозитория
|
|
|
|
- `web/app.py` — основное приложение FastAPI (машины, ISO, образы дисков, сеть, журналы, обновления, консоль).
|
|
- `web/core.py` — общие примитивы: `run_cmd`, хранилище операций (`new_operation`, `run_operation`,
|
|
`finish_operation`, `active_operations_for`, `interrupt_orphaned_operations`), `render`, `require_auth`,
|
|
`valid_vm_name`, шаблоны Jinja. Импорт `core` выставляет `LC_ALL=C.UTF-8` (virsh иначе переводится).
|
|
- `web/features/*.py` — модули с `router = APIRouter()`, подключаются в конце `app.py`:
|
|
`setup` (мастер `/setup`), `settings` (`/settings`), `snapshots`, `backups`, `downloads` (скачивание
|
|
по ссылке и каталог), `vmops` (клон, увеличение диска, пауза/спящий режим, заметки, нагрузка).
|
|
POST-маршруты модулей — минимум 4 сегмента (`/vm/{name}/<модуль>/<действие>`), иначе их перехватит
|
|
`@app.post("/vm/{name}/{action}")`.
|
|
- `web/nodectl.py` — факты об узле и действия через `scripts/virtuality-ctl` (единая точка для
|
|
systemd-юнитов, TLS, firewall, моста br0 с автооткатом, диска под хранилище, пароля, часового пояса).
|
|
- `web/network_core.py` — NAT-сеть `virtuality-nat` (192.168.100.0/24), резервации DHCP (фиксированный
|
|
MAC по имени машины), проброс портов (nftables + ufw + iptables-fallback с меткой `virtuality-forward`).
|
|
- `web/catalog.py` — каталог облачных образов и типы ОС; `web/cloudinit.py` — seed cloud-init.
|
|
- `web/update_core.py` + `scripts/auto_update_check.sh`, `scripts/apply_github_update.sh`,
|
|
`scripts/update_target.sh` — обновления; канал `stable` = последний тег `vX.Y.Z` (пока тегов нет — main),
|
|
канал `main` = ветка main.
|
|
- `scripts/virtuality_firstboot.sh` — первая загрузка установленной системы: panel → network →
|
|
virtualization → tools → finish, прогресс в `/var/lib/virtuality/config/setup.json`.
|
|
- `scripts/install_web_panel.sh` — установка/обновление панели (web.prev для отката, офлайн-wheels).
|
|
- `install.sh` (установка одной командой), `install_virtuality_node.sh` (пакеты KVM/libvirt).
|
|
- `image/build-iso.sh`, `image/autoinstall.yaml`, `image/grub/` — сборка установочного ISO.
|
|
- `updates/versions.json` — журнал изменений для центра обновлений; `VERSION` — текущая версия.
|
|
|
|
## Команды
|
|
|
|
```bash
|
|
make check # pyflakes + shellcheck + pytest
|
|
python3 -m pytest -q # тесты (fake virsh в tests/conftest.py)
|
|
python3 tests/dev_server.py 8765 # демо-панель, вход: tester / любой пароль
|
|
VIRTUALITY_DEV_SETUP=installing python3 tests/dev_server.py # мастер на шаге установки
|
|
VIRTUALITY_DEV_SETUP=done|finished ... # мастер после установки / настроенный сервер
|
|
make iso # ISO в dist/ (нужны xorriso, git, curl, python3-pip; ~3 ГБ загрузки)
|
|
./image/build-iso.sh --help # все параметры сборки (в т.ч. --unattended)
|
|
```
|
|
|
|
Скриншоты: Playwright и Chromium доступны в облачной среде, локально — `npx playwright`.
|
|
|
|
## Правила
|
|
|
|
- Код как вокруг: плотность комментариев, имена, идиомы модуля. Не переформатировать чужой код.
|
|
- Каждое изменение поведения — с тестом. Перед коммитом: `make check`.
|
|
- Коммиты по-русски в стиле «<что> было сделано».
|
|
- Работаем прямо в `main` (так решил владелец). Перед каждым пушем — `make check`; не пушить
|
|
недоделанное: ноды на канале «Ранний доступ» (`main`) подтягивают main каждую ночь.
|
|
- Узлы на канале `stable` (по умолчанию) обновляются только до тегов `vX.Y.Z`. Релиз: поднять `VERSION`,
|
|
добавить запись в `updates/versions.json`, запушить, поставить тег `vX.Y.Z` на main — тег же запускает
|
|
сборку ISO в GitHub Actions (artifacts `virtuality-iso-amd64/arm64`).
|
|
- Секреты и пароли не логировать; пароль cloud-init хранится только как SHA-512 crypt.
|
|
- Не возвращать удалённое: Cockpit, консольный dashboard, эмуляцию ARM64 на x86, PXE, смену
|
|
архитектуры машины, скрипты bootstrap/clean_install/setup_bridge_br0/create_test_vm.
|
© 2026 StackWorks