Это про управление жизненным циклом виртуальных машин, а не про способ подключиться к рабочему столу.
Система сама клонирует ВМ из шаблона — ровно столько, сколько нужно прямо сейчас, — выдаёт их пользователям по требованию, замечает, что машина простаивает, и гасит или удаляет её. Гипервизор под капотом — Proxmox VE или Hyper-V, можно подключить оба сразу.
Подключение — это уже следствие, и оно намеренно сделано чужими руками: RDP в
браузере обслуживает Apache Guacamole, либо
пользователь получает обычный .rdp для mstsc. Своего протокола удалённого
доступа здесь нет и не задумывалось — изобретать замену RDP было бы странно.
Задача, из которой всё выросло: нужен большой пул виртуалок, а держать их все включёнными не на чем — одновременно работает хорошо если четверть. Обычно это начинается со скриптов «погасить по таймауту, поднять по требованию», и довольно быстро выясняется, что скриптов мало: надо ещё понимать, кому машина выдана и свободна ли она на самом деле, откуда взять новую, если свободных не осталось, и куда девать те, что больше не нужны.
Отсюда и приоритеты: сначала автоматика вокруг ВМ, потом всё остальное, и простота для двоих — для админа, который настраивает, и для пользователя, который просто хочет свою машину.
- Технический отдел, тестовые стенды. Пул машин под задачи, где нужно быстро получить чистую ВМ и не жалко её потом потерять.
- Учебный класс, лаборатория. Студенту нужна машина с набором софта под практику. Он подключается, работает, уходит — машина удаляется, следующий получает такую же чистую. Без ручной работы между занятиями.
- Небольшая инфраструктура на Proxmox или Hyper-V, где нужен именно автоматический пул, а не большое коммерческое VDI-решение.
Здесь полный исходный код, который вы собираете и запускаете у себя. Ничего не урезано и не заглушено: в коде нет ни одной проверки, которая ограничивала бы функциональность в зависимости от лицензии. Готовых образов нет — собираются на месте, это несколько минут; шаблоны ВМ вы тоже готовите сами, они всё равно специфичны для вашего гипервизора.
Условия использования — в разделе Лицензия. Если коротко: пробовать, изучать и применять некоммерчески можно свободно.
Подробные руководства — в каталоге docs/: установка с нуля
(INSTALL), повседневная работа
(OPERATOR_GUIDE) и внутреннее устройство
(ADMIN_GUIDE). README — только вводная часть, там всё
подробно и по шагам. Разбор — ниже.
Главное — то, ради чего всё затевалось:
- Пул держит себя сам. Вы говорите, сколько машин иметь наготове и сколько максимум; система клонирует шаблон до нужного числа и не создаёт лишнего.
- Выдача по требованию. Пользователь нажимает «Подключиться» и получает свободную машину. Пока она за ним, никто другой её не получит.
- Возврат по простою. Когда машина никем не занята дольше заданного времени, её гасят или удаляют — в зависимости от того, как настроен пул.
- Определение простоя, которому можно верить. Гостевой агент считает реальную занятость внутри ВМ, включая подключения по обычному RDP мимо портала. Без него простой виден только по браузерным сеансам, и машину можно погасить под работающим человеком.
- Подготовка клона после запуска. Скрипт постпровижининга (есть готовые пресеты: включить RDP или SSH, настроить обновления, ограничить интернет) и автоматический ввод в домен Active Directory при первом старте.
- Самозащита пула. Если клоны перестают оживать, пул сам останавливает автосоздание и убирает мёртвые машины, а не молотит вхолостую.
Вокруг этого:
- Два способа подключения. RDP-сеанс в браузере через Guacamole или файл
.rdpдля обычногоmstsc. Linux-гости — тем же RDP черезxrdp. - Вход через Active Directory (LDAP), опционально с двухфакторной аутентификацией (TOTP).
- Права через группы — доступ к пулу даётся группе, а не отдельному пользователю.
- Наблюдаемость. Состояние нод и пулов, метрики, журнал событий с живой лентой.
Границы, о которых честнее сказать сразу:
- Гипервизоры — только Proxmox VE и Hyper-V. В форме подключения виден пункт VMware vSphere, он помечен «скоро» и недоступен для выбора.
- Протокол подключения к рабочему столу — только RDP.
- Раздел «Обновление системы» в панели в этой сборке не работает: он
обращается к сервису обновлений, которого здесь нет. Обновление — это
git pullи пересборка, см. ниже.
| Хост под стек | Linux с Docker Engine и плагином Compose |
| CPU / RAM / диск | 4 vCPU, 8 ГБ, 40 ГБ — с запасом под нагрузку. Контрольная установка на Debian 12 занимает 5,6 ГБ диска и ~1,6 ГБ памяти в покое, сборка идёт ~8 минут |
| Гипервизор | Proxmox VE (доступ к API, обычно :8006) или хост Hyper-V (доступ по SSH) |
| Шаблон ВМ | подготовленный образ, из которого будут клонироваться машины |
Стек поднимает заметное количество контейнеров: PostgreSQL, Redis, backend и три воркера Celery, guacd и Guacamole (JVM), два SPA, nginx. Пик потребления памяти приходится на сборку образов, а не на работу — на машине с 2 ГБ она выпадает по OOM.
git clone <адрес этого репозитория> vdi
cd vdi
cp .env.example .envЗаполните .env — как минимум APP_SECRET_KEY, POSTGRES_PASSWORD,
GUACAMOLE_JSON_SECRET_KEY и APP_DOMAIN. Команды для генерации ключей есть
в комментариях рядом с каждым полем.
docker compose -f docker-compose.prod.yml build # единицы минут
docker compose -f docker-compose.prod.yml up -dПортал откроется на http://<APP_DOMAIN>/, панель администратора — на
/admin/. Первая учётная запись создаётся автоматически: admin / admin.
Смените пароль сразу же — до того, как стенд станет доступен кому-то ещё.
Дальше — docs/INSTALL.md: подготовка гипервизора, TLS,
шаблон ВМ, сборка гостевого агента.
При TLS_MODE=none после первого входа зайдите в Настройки и задайте
app_url = http://<ваш-хост>. Иначе публичный адрес выводится из
APP_DOMAIN со схемой https://, и ссылки на консоль Guacamole вместе с
адресом heartbeat агента окажутся нерабочими. По HTTPS доделывать ничего не
нужно.
Корневой docker-compose.yml собирает то же самое, но публикует порты всех
сервисов наружу и монтирует исходники внутрь контейнера. Для отладки удобно,
для стенда, доступного из сети, не годится.
Агент ставится внутрь шаблона ВМ и считает реальную занятость машины. Для Hyper-V он обязателен: без него постпровижининг не работает вовсе — у гипервизора нет своего канала выполнения команд в госте.
Готовые бинари — в ассетах релиза (вкладка Releases). Там же SHA256SUMS.
Собрать самостоятельно:
cd agent
./build.sh all # результат в agent/dist/Для Windows собираются две разные сборки, и выбор обязателен: начиная с Go 1.21 рантайм вызывает функции kernel32, которых нет в Windows 7/8/8.1 и Server 2008 R2/2012 — обычный бинарь там стартует и сразу умирает. Для этих гостей нужна сборка тулчейном Go ≤ 1.20:
go install golang.org/dl/go1.20.14@latest && ~/go/bin/go1.20.14 downloadПосле этого build.sh all подхватит его сам. Без него легаси-сборка молча
пропускается — в логе будет NOTE, а бинарей окажется два вместо четырёх.
Исходники у обеих сборок одинаковые, возможности идентичны.
Установка в шаблон — скриптами из agent/install/. Подробности и разбор
ловушек (WOW64 на 32-битных гостях, KVP в Hyper-V) — в
docs/ADMIN_GUIDE.md, раздел «Подготовка шаблона».
Три подробных руководства в каталоге docs/, все на русском. Вместе
это около 2300 строк — README только вводит в курс дела, всё остальное там.
docs/INSTALL.md — установка
От чистой машины до работающего стенда. Установка Docker, создание API-токена
Proxmox с разбором нужных привилегий, подготовка хоста Hyper-V (включая
настройку OpenSSH на Windows — там несколько неочевидных мест), заполнение
.env, сборка, TLS, первый вход. В конце — разбор типичных отказов при
установке.
Начинать отсюда, если разворачиваете впервые.
docs/OPERATOR_GUIDE.md — эксплуатация
Для того, кто будет этим пользоваться каждый день, без погружения в код. Разбор всех экранов панели, создание пула и что означает каждый его параметр, права и группы, подключение Active Directory. Половину документа занимает раздел «Что делать, если…»: пользователю не выдаётся ВМ, машина не возвращается в пул, клоны исчезают сами, пул перестал создавать машины.
Читать после установки.
docs/ADMIN_GUIDE.md — внутреннее устройство
Для инженера, которому нужно понимать, а не только запускать. Архитектура, различия драйверов Proxmox и Hyper-V, как устроены пулы и жизненный цикл клона, подготовка шаблона ВМ и установка гостевого агента, миграции. Отдельно — почему агент так важен для автоматического освобождения машин и что именно ломается без него.
Читать, если готовите шаблон ВМ или разбираетесь, почему что-то работает не так.
git pull
docker compose -f docker-compose.prod.yml build
docker compose -f docker-compose.prod.yml up -dМиграции базы применяет сам backend при старте (alembic upgrade head).
Перед обновлением сделайте дамп базы — откатывать миграции автоматика не умеет.
Business Source License 1.1 — см. LICENSE.
Коротко и без юридического языка:
- Можно свободно — изучать, менять, разворачивать для тестирования, разработки и оценки, использовать в учебных целях и лично. Учебный класс, где студенты получают ВМ под практику, под это подпадает.
- Нужна отдельная лицензия — для коммерческого продакшена: если портал раздаёт рабочие столы в коммерческой деятельности или вы предоставляете его как услугу третьим лицам.
- Через четыре года каждая версия автоматически переходит под Apache 2.0.
Дата указана в заголовке
LICENSEи считается отдельно для каждой версии.
Формулировки в файле LICENSE имеют приоритет над этим пересказом. Если
непонятно, попадает ли ваш случай под свободное использование, — спросите.
Коммерческая поставка — это готовые образы, мастер установки, обновление из
панели и, собственно, поддержка. Ставится она поверх той же базы данных:
установка, поднятая из этого репозитория, переносится без потери пулов,
пользователей и настроек. Что именно меняется — расписано в
docs/INSTALL.md, раздел «Переход на поставку с лицензией».