Развертывание на сервере: Docker noVNC vs Headless Xvfb (выбор и эксплуатация)

Вы хотите выполнить серверное развертывание Antigravity Tools, запустив его на NAS/сервере, обычно не для того, чтобы «удалённо открыть GUI и посмотреть», а чтобы использовать его как постоянно работающий локальный API-шлюз: всегда онлайн, можно проверить работоспособность, можно обновлять, можно выполнять резервное копирование, при возникновении проблем можно их устранить.

В этом уроке рассматриваются только два реально реализуемых пути, указанных в проекте: Docker (с noVNC) и Headless Xvfb (управление systemd). Все команды и значения по умолчанию основаны на файлах развертывания в репозитории.

Если вы только хотите «запуститься один раз»

В главе об установке уже описаны входные команды Docker и Headless Xvfb, вы можете сначала посмотреть Установка и обновление, затем вернуться к этому уроку, чтобы дополнить «эксплуатационный замкнутый цикл».

Что вы сможете сделать после изучения

• Правильно выбрать форму развертывания: знать, какие проблемы решают Docker noVNC и Headless Xvfb
• Запустить полный замкнутый цикл: развертывание → синхронизация данных учётных записей → проверка /healthz → просмотр журналов → резервное копирование
• Сделать обновление контролируемым действием: понимать разницу между «автоматическим обновлением при запуске» Docker и upgrade.sh Xvfb

Ваша текущая проблема

• На сервере нет десктопа, но вы не можете обойтись без операций, которые «требуют браузера», таких как OAuth/авторизация
• Вы запустились один раз, но этого недостаточно, вам больше нужно: автоматическое восстановление после перезагрузки питания, проверка работоспособности, обновление, резервное копирование
• Вы беспокоитесь, что открытие порта 8045 создаст риск безопасности, но не знаете, с какой стороны следует начать ограничения

Когда использовать этот подход

• NAS/домашний сервер: хотите использовать браузер, чтобы открыть GUI для выполнения авторизации (Docker/noVNC очень удобен)
• Длительная работа сервера: вы больше предпочитаете использовать systemd для управления процессами, журналирование на диск, обновление с помощью скриптов (Headless Xvfb больше похож на «проект эксплуатации»)

Что такое режим «развертывание на сервере»?

Развертывание на сервере означает, что вы не запускаете Antigravity Tools на локальном десктопе, а размещаете его на постоянно работающей машине и используете порт обратного прокси (по умолчанию 8045) в качестве входа для внешнего обслуживания. Его суть — не «удалённо посмотреть интерфейс», а создать стабильный эксплуатационный замкнутый цикл: сохранение данных, проверка работоспособности, журналирование, обновление и резервное копирование.

Основная идея

1. Сначала выберите «то, чего вам больше всего не хватает»: если не хватает браузерской авторизации — выбирайте Docker/noVNC; если не хватает управляемости эксплуатации — выбирайте Headless Xvfb.
2. Затем зафиксируйте «данные»: учётные записи/конфигурация находятся в .antigravity_tools/, либо используйте Docker volume, либо закрепляйте в /opt/antigravity/.antigravity_tools/.
3. Наконец, создайте «эксплуатационный замкнутый цикл»: используйте /healthz для проверки работоспособности, при сбоях сначала смотрите журналы, затем решайте, перезапустить или обновить.

Предварительное напоминание: сначала определите базовые требования безопасности

Если вы собираетесь открыть 8045 в локальную сеть/общественную сеть, сначала посмотрите Безопасность и приватность: auth_mode, allow_lan_access, и проект «не раскрывать информацию об учётных записях».

Быстрая справка по выбору: Docker vs Headless Xvfb

То, что вам важнее всего	Рекомендуется	Почему
Нужен браузер для OAuth/авторизации	Docker (noVNC)	В контейнере есть встроенный Firefox ESR, можно напрямую работать в браузере (см. deploy/docker/README.md)
Хотите управление systemd/журналы на диск	Headless Xvfb	Скрипт установки установит systemd service, журналы будут дописываться в logs/app.log (см. deploy/headless-xvfb/install.sh)
Хотите изоляцию и ограничения ресурсов	Docker	Способ compose обеспечивает естественную изоляцию, также проще настроить ограничения ресурсов (см. deploy/docker/README.md)

Следуйте за мной

Шаг 1: Сначала подтвердите, где находится «каталог данных»

Почему Успешное развертывание, но «нет учётных записей/конфигурации», по сути означает, что каталог данных не был перенесён или не сохранён.

• Вариант Docker: данные монтируются в /home/antigravity/.antigravity_tools внутри контейнера (compose volume)
• Вариант Headless Xvfb: данные размещаются в /opt/antigravity/.antigravity_tools (и фиксируются для записи с помощью HOME=$(pwd))

Вы должны увидеть

• Docker: docker volume ls показывает antigravity_data
• Xvfb: /opt/antigravity/.antigravity_tools/ существует, и включает accounts/, gui_config.json

Шаг 2: Запуск Docker/noVNC (подходит для тех, кто нуждается в браузерской авторизации)

Почему Вариант Docker упаковывает «виртуальный дисплей + менеджер окон + noVNC + приложение + браузер» в один контейнер, что экономит вам установку множества графических зависимостей на сервере.

На сервере выполните:

cd deploy/docker
docker compose up -d

Откройте noVNC:

http://<server-ip>:6080/vnc_lite.html

Вы должны увидеть

• docker compose ps показывает, что контейнер работает
• Браузер может открыть страницу noVNC

О порте noVNC (рекомендуется сохранить по умолчанию)

deploy/docker/README.md упоминает, что можно использовать NOVNC_PORT для настройки порта, но в текущей реализации start.sh при запуске websockify слушает жёстко заданный порт 6080. Чтобы изменить порт, нужно одновременно настроить отображение портов docker-compose и порт прослушивания start.sh.

Чтобы избежать несоответствия конфигурации, рекомендуется напрямую использовать порт по умолчанию 6080.

Шаг 3: Сохранение, проверка работоспособности и резервное копирование Docker

Почему Доступность контейнера зависит от двух вещей: работоспособности процесса (запущен ли) и сохранения данных (после перезапуска учётные записи остаются).

1. Подтвердите, что том для сохранения смонтирован:

cd deploy/docker
docker compose ps

2. Резервное копирование тома (README проекта даёт способ резервного копирования tar):

docker run --rm -v antigravity_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/antigravity-backup.tar.gz /data

3. Проверка работоспособности контейнера (в Dockerfile есть HEALTHCHECK):

docker inspect --format '{{json .State.Health}}' antigravity-manager | jq

Вы должны увидеть

• .State.Health.Status имеет значение healthy
• В текущем каталоге создаётся antigravity-backup.tar.gz

Шаг 4: Установка Headless Xvfb в один клик (подходит для тех, кто хочет управление systemd)

Почему Headless Xvfb — это не «чисто бэкендовый режим», а запуск графического приложения на сервере с помощью виртуального дисплея; но это даёт более знакомый способ эксплуатации: systemd, фиксированные каталоги, журналирование на диск.

На сервере выполните (скрипт в один клик, предоставленный проектом):

curl -fsSL https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/deploy/headless-xvfb/install.sh | sudo bash

Вы должны увидеть

• Каталог /opt/antigravity/ существует
• systemctl status antigravity показывает, что сервис работает

Более надёжный способ: сначала рассмотрите скрипт

Скачайте curl -O .../install.sh, сначала прочитайте, затем sudo bash install.sh.

Шаг 5: Синхронизируйте учётные записи с локальной машины на сервер (обязательно для варианта Xvfb)

Почему Установка Xvfb только запускает программу. Чтобы обратный прокси действительно работал, вам нужно синхронизировать существующие учётные записи/конфигурацию локальной машины с каталогом данных сервера.

Проект предоставляет sync.sh, который автоматически ищет каталог данных на вашей машине по приоритету (например, ~/.antigravity_tools, ~/Library/Application Support/Antigravity Tools), затем использует rsync для синхронизации на сервер:

curl -O https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/deploy/headless-xvfb/sync.sh
chmod +x sync.sh

./sync.sh root@your-server /opt/antigravity

Вы должны увидеть

• В терминале выводится примерно: синхронизация: <local> -> root@your-server:/opt/antigravity/.antigravity_tools/
• Пытаются перезапустить удалённый сервис (скрипт вызовет systemctl restart antigravity)

Шаг 6: Проверка работоспособности и устранение неполадок (общие для обоих вариантов)

Почему После развертывания первое дело — не «подключить клиента», а сначала создать вход, который можно быстро оценить работоспособность.

1. Проверка работоспособности (служба обратного прокси предоставляет /healthz):

curl -i http://127.0.0.1:8045/healthz

2. Просмотр журналов:

## Docker
cd deploy/docker
docker compose logs -f

## Headless Xvfb
tail -f /opt/antigravity/logs/app.log

Вы должны увидеть

• /healthz возвращает 200 (конкретное содержимое ответа см. на практике)
• В журналах можно увидеть информацию о запуске службы обратного прокси

Шаг 7: Стратегия обновления (не считайте «автоматическое обновление» единственным вариантом)

Почему Обновление — это действие, которое проще всего «обновить систему до недоступного». Вам нужно знать, что именно делает каждое обновление.

• Docker: при запуске контейнера попытается получить последний .deb через GitHub API и установить (если есть ограничение скорости или сетевая аномалия, продолжит использовать кешированную версию).
• Headless Xvfb: используйте upgrade.sh для получения последнего AppImage, при сбое перезапуска откатится к резервной копии.

Команда обновления Headless Xvfb (README проекта):

cd /opt/antigravity
sudo ./upgrade.sh

Вы должны увидеть

• Выводится примерно: обновление: v<current> -> v<latest>
• После обновления сервис всё ещё active (скрипт выполнит systemctl restart antigravity и проверит статус)

Напоминания о возможных ошибках

Сценарий	Частая ошибка (❌)	Рекомендуемый подход (✓)
Потеря учётных записей/конфигурации	❌ Только заботитесь о том, чтобы «программа запустилась»	✓ Сначала подтвердите, что .antigravity_tools/ сохраняется (volume или /opt/antigravity)
Порт noVNC не обновился	❌ Изменили только NOVNC_PORT	✓ Сохраните по умолчанию 6080; если меняете, одновременно проверьте порт websockify в start.sh
Открытие 8045 в общественную сеть	❌ Не настраиваете api_key/не смотрите auth_mode	✓ Сначала выполните базовые требования согласно Безопасность и приватность, затем рассмотрите туннель/обратный прокси

Краткое содержание урока

• Docker/noVNC решает проблему «на сервере нет браузера/нет десктопа, но нужна авторизация», подходит для сценариев NAS
• Headless Xvfb больше похож на стандартную эксплуатацию: фиксированные каталоги, управление systemd, обновление/откат скриптами
• Независимо от выбранного варианта, сначала сделайте замкнутый цикл правильно: данные → проверка работоспособности → журналы → резервное копирование → обновление

Рекомендуется продолжить чтение

• Вы хотите открыть службу в локальную сеть/общественную сеть: Безопасность и приватность: auth_mode, allow_lan_access
• После развертывания возникла 401: 401/Сбой аутентификации: auth_mode, совместимость заголовков и контрольный список конфигурации клиента
• Вы хотите использовать туннель для открытия службы: Cloudflared туннель в один клик

---

Приложение: Ссылка на исходный код

Нажмите, чтобы развернуть и просмотреть местоположение исходного кода

Дата обновления: 2026-01-23

Функция	Путь к файлу	Номер строки
Вход для развертывания Docker и URL noVNC	deploy/docker/README.md	5-13
Описание переменных окружения развертывания Docker (VNC_PASSWORD/RESOLUTION/NOVNC_PORT)	deploy/docker/README.md	32-39
Отображение портов и томов данных Docker compose (antigravity_data)	deploy/docker/docker-compose.yml	1-21
Скрипт запуска Docker: автоматическое обновление версии (ограничение скорости GitHub)	deploy/docker/start.sh	27-58
Скрипт запуска Docker: запуск Xtigervnc/Openbox/noVNC/приложения	deploy/docker/start.sh	60-78
Проверка работоспособности Docker: подтверждение существования процессов Xtigervnc/websockify/antigravity_tools	deploy/docker/Dockerfile	60-79
Headless Xvfb: структура каталогов и команды эксплуатации (systemctl/healthz)	deploy/headless-xvfb/README.md	19-78
Headless Xvfb: install.sh установка зависимостей и инициализация gui_config.json (по умолчанию 8045)	deploy/headless-xvfb/install.sh	16-67
Headless Xvfb: sync.sh автоматическое обнаружение локального каталога данных и rsync на сервер	deploy/headless-xvfb/sync.sh	8-32
Headless Xvfb: upgrade.sh загрузка новой версии и откат при сбое	deploy/headless-xvfb/upgrade.sh	11-51
Конечная точка проверки работоспособности обратного прокси /healthz	src-tauri/src/proxy/server.rs	120-194