goqemu

Менеджер сессий QEMU: демон, CLI и TUI. Состояние виртуалок — диски, сеть, MAC-адреса, политики перезапуска — хранится в SQLite, CLI общается с демоном через unix-сокет. По образу и подобию Docker.

Платформа: Linux. Статус: дорожная карта из DESIGN.md пройдена целиком, этапы 0–10 закрыты.

Как это выглядит

Командная строка — жизненный цикл виртуалки целиком:

Интерфейс — список с живым обновлением, форма создания, вкладки и фильтр:

Обе записи сделаны против настоящего демона и пересобираются командой make demo; как именно — в tools/demo.

Документация

• Первый запуск на реальной машине — боевая проверка по шагам: KVM, настоящий гость, агент, systemd, socket activation
• Руководство пользователя — как всем этим пользоваться
• Справочник команд — все команды и флаги
• Формат spec-файла — схема goqemu.yaml поле за полем (описана до реализации)
• HTTP API — эндпоинты для интеграций
• DESIGN.md — архитектура и принятые решения

Быстрый старт

Ниже — dev-стенд для разработки. Если задача другая — погонять goqemu на настоящей Linux-машине с аппаратной виртуализацией, — смотрите первый запуск: там порядок проверки по шагам и список того, что в контейнере не исполняется вообще.

Вся разработка идёт в контейнере, на хосте нужен только Docker.

make up                      # стенд: dev-контейнер + демон с hot-reload
make cli ARGS="ping"
make cli ARGS="info"
make logs                    # логи демона
make sh                      # шелл в dev-контейнере

Поднять первую виртуалку:

make cli ARGS="image pull https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2 --name debian-12"
make cli ARGS="create web-01 --image debian-12 --disk-size 20G --memory 2048 -p 2222:22 --restart on-failure:5"
make cli ARGS="start web-01"
make cli ARGS="ls"
make cli ARGS="stats"
docker compose exec dev go run ./cmd/goqemu console web-01   # выход — Ctrl-]

На Linux-хосте без контейнера: распакуйте релизный архив (или make build), затем отдайте демон systemd — это user-юнит, sudo не нужен:

goqemu daemon install --enable --start
goqemu daemon status

Нужны qemu-system-x86_64 и qemu-img в PATH.

Проверки:

make test        # юнит-тесты с race-детектором
make lint        # golangci-lint
make check       # fmt + vet + lint + test
make help        # все цели

Что уже работает

Вся дорожная карта из DESIGN.md.

• Демон: unix-сокет 0600 с проверкой SO_PEERCRED, flock от второго экземпляра, плавная остановка, состояние в SQLite.
• Жизненный цикл: create/start/stop/restart/kill/pause/resume/rm, адресация по имени, полному id или его префиксу.
• Виртуалки переживают рестарт демона. Процессы отвязаны через setsid, а при старте демон сверяет базу с реальностью: живые усыновляет по паре (pid, время старта), мёртвые помечает, живые но потерявшие QMP-монитор убивает — управлять ими всё равно нельзя.
• Автоперезапуск по политике: no, on-failure[:N], always, unless-stopped, с экспоненциальным backoff и сбросом счётчика. Ручная остановка сильнее любой политики.
• Правка после создания: update, disk add|rm|resize, net add|rm|set-mac, port ls|add|rm — на остановленной виртуалке.
• Пул образов: image pull с прогрессом и проверкой sha256, linked clone при создании, запрет удаления занятого образа.
• Копирование и перенос: clone рядом на той же машине; export/import для переезда — обычный tar с манифестом, потоком в оба конца (goqemu export vm - | ssh host goqemu import -).
• Стенд одним файлом: goqemu apply разворачивает набор виртуалок из goqemu.yaml и сводит машину к описанному — идемпотентно, с планом перед применением и без молчаливой потери дисков.
• Экран виртуалки: --vga std даёт гостю видеоадаптер и планшет, а goqemu display открывает VNC в местном клиенте, пробрасывая порт по ssh к удалённому демону. Без этого в графический установщик не попасть.
• Проброс USB: usb add отдаёт гостю устройство хоста, в том числе на живую; отказ по правам печатает готовое udev-правило.
• Проброс PCI: pci add для видеокарт и контроллеров. В rootless-модель он не укладывается честно — нужен root либо явно выданные права, — поэтому goqemu проверяет IOMMU, драйвер, группу и лимит памяти и в отказе печатает команду, которой это чинится.
• Общие каталоги с хостом: --mount /home/user/code отдаёт каталог гостю через virtiofs — редактируешь на хосте, собираешь в виртуалке. Монтирование прописывается в fstab гостя через cloud-init.
• UEFI: --firmware uefi подключает OVMF парой pflash, у каждой виртуалки свой NVRAM — порядок загрузки переживает перезапуск.
• Архитектуры: --arch aarch64 рядом с x86_64. Тип машины, модель CPU и прошивка подставляются по профилю архитектуры; на ARM выбор BIOS отвергается, потому что его там нет.
• Снапшоты: у работающей виртуалки — вместе с памятью (QMP snapshot-save), у остановленной — только диски (qemu-img).
• Консоль: постоянная запись в console.log с ротацией плюс интерактивное подключение goqemu console с выходом по Ctrl-].
• Метрики: goqemu stats, снимком и потоком.
• Фильтры: ls --filter state=/name=/label=/arch=/restart=, условия складываются по И.
• Интерактивный интерфейс: goqemu tui — список с живым обновлением по событиям демона, метрики выбранной виртуалки, логи, консоль и действия. Горячие клавиши в стиле k9s, справка по ?.
• События: журнал с ретенцией и живая лента goqemu events -f.
• Логи: goqemu logs -f следит за файлом и переживает его ротацию; подписаться можно до первого запуска виртуалки.
• Расписание: cron add --action restart|start|stop|snapshot.
• Удалённый доступ: демон слушает unix-сокет и TCP одновременно (--host повторяемый), по TCP — только взаимный TLS. Сертификаты выпускает goqemu daemon cert, клиент настраивается через GOQEMU_HOST и GOQEMU_CERT_PATH.
• Обвязка: systemd user-юнит через goqemu daemon install, socket activation вторым юнитом, настройки в config.yaml, релизные архивы под amd64 и arm64, проверка прав для tap/bridge с готовой командой вместо сырого «permission denied» из QEMU.
• Гость изнутри: goqemu exec и goqemu agent через qemu-guest-agent, штатное выключение его же руками, адреса и имя хоста гостя.

Подробности и примеры — в руководстве.

Что дальше

Дорожная карта из DESIGN.md пройдена целиком. Дальше:

• Роли для клиентских сертификатов (--tls-allowed-cn), управляемые сети, spec-файлы поверх нескольких хостов.

Замечание про macOS-хост

В dev-контейнере на Apple Silicon нет /dev/kvm, поэтому виртуалки идут через TCG — медленно. Для тестов жизненного цикла и супервизии используется fakeqemu — стаб, которому ускорение не нужно. На Linux-хосте есть профиль с пробросом устройства:

docker compose --profile kvm up -d dev-kvm

Отладка API вручную

make api EP=/v1/info
docker compose exec dev curl -s --unix-socket /root/.goqemu/goqemu.sock http://d/v1/ping