Implantação em Servidor: Docker noVNC vs Headless Xvfb (Seleção e Operação)
Você quer fazer implantação de servidor do Antigravity Tools, rodar em NAS/servidor, geralmente não é para "abrir GUI remotamente para ver", mas para tratá-lo como um gateway de API local de execução longa: sempre online, pode verificar vivacidade, pode atualizar, pode fazer backup, pode localizar problemas quando ocorrerem.
Esta aula só fala dois caminhos já dados no projeto que podem ser implementados: Docker (com noVNC) e Headless Xvfb (gerenciado por systemd). Todos os comandos e valores padrão seguem os arquivos de implantação no repositório.
Se você só quer "rodar uma vez primeiro"
O capítulo de instalação já cobriu comandos de entrada de Docker e Headless Xvfb, você pode primeiro ver Instalação e Atualização, depois voltar para esta aula para completar o "ciclo de operação".
O que você poderá fazer após concluir
- Selecionar a forma de implantação correta: saber o que Docker noVNC e Headless Xvfb resolvem respectivamente
- Completar um ciclo fechado: implantação -> sincronizar dados de conta -> verificar vivacidade
/healthz-> ver logs -> backup - Fazer atualização uma ação controlável: saber a diferença entre "atualização automática ao iniciar" do Docker e Xvfb
upgrade.sh
Seu dilema atual
- O servidor não tem desktop, mas você não pode viver sem operações como OAuth/autorização que "precisam de navegador"
- Rodar uma vez não é suficiente, você quer mais: recuperação automática após reinicialização de energia, pode verificar vivacidade, pode fazer backup
- Você está preocupado que expor porta 8045 terá risco de segurança, mas não sabe por onde começar a restringir
Quando usar esta estratégia
- NAS/servidor doméstico: espera poder abrir GUI em navegador para completar autorização (Docker/noVNC é muito conveniente)
- Servidor de execução longa: você mais quer usar systemd para gerenciar processo, logs gravados em disco, script de atualização (Headless Xvfb é mais como "projeto operacional")
O que é "implantação de servidor"?
Implantação de servidor significa: você não roda as Antigravity Tools no desktop local, mas as coloca em uma máquina de execução longa, e usa a porta de proxy reverso (padrão 8045) como entrada de serviço externo. O núcleo não é "ver interface remotamente", mas estabelecer um ciclo de operação estável: persistência de dados, verificação de vivacidade, logs, atualização e backup.
Ideia central
- Primeiro selecione "a capacidade que mais falta": falta de autorização de navegador escolha Docker/noVNC; falta de controle operacional escolha Headless Xvfb.
- Depois determine "dados": contas/configuração estão em
.antigravity_tools/, ou use Docker volume, ou fixe em/opt/antigravity/.antigravity_tools/. - Finalmente faça "ciclo de operação": verificar vivacidade com
/healthz, em caso de falha ver logs primeiro, depois decidir reiniciar ou atualizar.
Aviso prévio: primeiro determine linha de base de segurança
Se você vai expor 8045 para LAN/pública, primeiro veja Segurança e Privacidade: auth_mode, allow_lan_access, e design de "não vazar informações de conta".
Seleção rápida: Docker vs Headless Xvfb
| O que mais importa | Mais recomendado | Por que |
|---|---|---|
| Precisa de navegador para OAuth/autorização | Docker (noVNC) | Container vem com Firefox ESR embutido, pode operar diretamente em navegador (ver deploy/docker/README.md) |
| Quer gerenciamento systemd/logs em disco | Headless Xvfb | Script de instalação instalará serviço systemd, e gravará logs em logs/app.log (ver deploy/headless-xvfb/install.sh) |
| Quer isolamento e limites de recursos | Docker | Compose naturalmente isola, e é mais fácil configurar limites de recursos (ver deploy/docker/README.md) |
Siga-me
Passo 1: Primeiro, confirme onde está o "diretório de dados"
Por que Implantação bem-sucedida mas "sem contas/configuração", essencialmente é porque o diretório de dados não foi levado ou não foi persistido.
- Solução Docker montará dados em
/home/antigravity/.antigravity_toolsno container (compose volume) - Solução Headless Xvfb colocará dados em
/opt/antigravity/.antigravity_tools(e fixará local de gravação através deHOME=$(pwd))
Você deve ver
- Docker:
docker volume lspode verantigravity_data - Xvfb:
/opt/antigravity/.antigravity_tools/existe, e contémaccounts/,gui_config.json
Passo 2: Rodar Docker/noVNC (adequado para autorização de navegador)
Por que A solução Docker empacota "monitor virtual + gerenciador de janelas + noVNC + aplicativo + navegador" em um container, poupando você de instalar muitas dependências gráficas no servidor.
No servidor, execute:
cd deploy/docker
docker compose up -dAbra noVNC:
http://<server-ip>:6080/vnc_lite.htmlVocê deve ver
docker compose psmostra container rodando- Navegador pode abrir página noVNC
Sobre porta noVNC (recomendado manter padrão)
deploy/docker/README.md menciona que pode usar NOVNC_PORT para personalizar porta, mas na implementação atual start.sh ao iniciar websockify escuta porta 6080 codificada. Para modificar porta precisa ajustar simultaneamente mapeamento de porta do docker-compose e porta de escuta do start.sh.
Para evitar configuração inconsistente, recomendo usar diretamente 6080 padrão.
Passo 3: Persistência, verificação de vivacidade e backup do Docker
Por que Disponibilidade do container depende de duas coisas: saúde do processo (se ainda está rodando) e persistência de dados (contas ainda lá após reinício).
- Confirme volume de persistência montado:
cd deploy/docker
docker compose ps- Backup do volume (README do projeto fornece método de backup tar):
docker run --rm -v antigravity_data:/data -v $(pwd):/backup alpine \
tar czf /backup/antigravity-backup.tar.gz /data- Verificação de saúde do container (Dockerfile tem HEALTHCHECK):
docker inspect --format '{{json .State.Health}}' antigravity-manager | jqVocê deve ver
.State.Health.Statuséhealthy- Arquivo
antigravity-backup.tar.gzgerado no diretório atual
Passo 4: Instalação Headless Xvfb com um clique (adequado para operação systemd)
Por que Headless Xvfb não é "modo puramente backend", mas usa monitor virtual para rodar programas GUI no servidor; mas em troca traz método de operação mais familiar: systemd, diretório fixo, logs em disco.
No servidor, execute (script de um clique fornecido pelo projeto):
curl -fsSL https://raw.githubusercontent.com/lbjlaq/Antigravity-Manager/main/deploy/headless-xvfb/install.sh | sudo bashVocê deve ver
- Diretório
/opt/antigravity/existe systemctl status antigravitymostra serviço rodando
Prática mais estável: primeiro reveja o script
curl -O .../install.sh baixe primeiro e veja, depois sudo bash install.sh.
Passo 5: Sincronizar contas locais para o servidor (necessário para solução Xvfb)
Por que Instalação Xvfb só roda o programa. Para o proxy realmente funcionar, você precisa sincronizar contas/configurações existentes da máquina local para o diretório de dados do servidor.
O projeto fornece sync.sh, que automaticamente procurará diretório de dados na sua máquina por prioridade (como ~/.antigravity_tools, ~/Library/Application Support/Antigravity Tools), depois rsync para o servidor:
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/antigravityVocê deve ver
- Saída do terminal similar:
sincronizar: <local> -> root@your-server:/opt/antigravity/.antigravity_tools/ - Serviço remoto tentará reiniciar (script chamará
systemctl restart antigravity)
Passo 6: Verificação de vivacidade e solução de problemas (comum para ambas as soluções)
Por que A primeira coisa após implantação não é "conectar cliente primeiro", mas estabelecer uma entrada que possa julgar saúde rapidamente.
- Verificação de vivacidade (serviço de proxy fornece
/healthz):
curl -i http://127.0.0.1:8045/healthz- Ver logs:
## Docker
cd deploy/docker
docker compose logs -f
## Headless Xvfb
tail -f /opt/antigravity/logs/app.logVocê deve ver
/healthzretorna 200 (corpo de resposta específico conforme realidade)- Logs podem ver informações de início do serviço de proxy
Passo 7: Estratégia de atualização (não trate "atualização automática" como única solução)
Por que Atualização é a ação mais fácil para "atualizar sistema para indisponível". Você precisa saber exatamente o que cada solução de atualização faz.
- Docker: ao iniciar container tentará baixar último
.debvia API do GitHub e instalar (se limitado ou exceção de rede, continuará usando versão em cache). - Headless Xvfb: usa
upgrade.shpara baixar último AppImage, e reverta para backup se reinício falhar.
Comando de atualização Headless Xvfb (README do projeto):
cd /opt/antigravity
sudo ./upgrade.shVocê deve ver
- Saída similar:
atualizar: v<current> -> v<latest> - Após atualização serviço ainda active (script chamará
systemctl restart antigravitye verificar estado)
Avisos sobre armadilhas
| Cenário | Erro comum (❌) | Prática recomendada (✓) |
|---|---|---|
| Contas/configuração perdidas | ❌ Só se importa com "programa rodando" | ✓ Primeiro confirme que .antigravity_tools/ é persistente (volume ou /opt/antigravity) |
| Porta noVNC alterada não entra em vigor | ❌ Só muda NOVNC_PORT | ✓ Mantenha 6080 padrão; se mudar, verifique simultaneamente porta websockify em start.sh |
| Expor 8045 para pública | ❌ Não configura api_key/não olha auth_mode | ✓ Primeiro faça linha de base conforme Segurança e Privacidade, depois considere túnel/proxy reverso |
Resumo desta aula
- Docker/noVNC resolve problema de "servidor sem navegador/sem desktop mas precisa autorização", adequado para cenário NAS
- Headless Xvfb é mais como operação padrão: diretório fixo, gerenciamento systemd, atualização/rollback por script
- Não importa qual solução, primeiro faça o ciclo certo: dados -> verificar vivacidade -> logs -> backup -> atualização
Continuação recomendada
- Você quer expor serviço para LAN/pública: Segurança e Privacidade: auth_mode, allow_lan_access
- Após implantação encontrar 401: 401/Falha de autenticação: auth_mode, compatibilidade de Header e lista de configuração de cliente
- Você quer usar túnel para expor serviço: Túnel Cloudflared com um clique
Apêndice: Referências de código-fonte
Clique para expandir e ver localizações do código-fonte
Atualizado em: 2026-01-23
| Funcionalidade | Caminho do arquivo | Número da linha |
|---|---|---|
| Entrada de implantação Docker e URL noVNC | deploy/docker/README.md | 5-13 |
| Descrição de variáveis de ambiente de implantação Docker (VNC_PASSWORD/RESOLUTION/NOVNC_PORT) | deploy/docker/README.md | 32-39 |
| Mapeamento de porta e volume de dados do docker compose (antigravity_data) | deploy/docker/docker-compose.yml | 1-21 |
| Script de início Docker: atualização automática de versão (GitHub rate limit) | deploy/docker/start.sh | 27-58 |
| Script de início Docker: iniciar Xtigervnc/Openbox/noVNC/aplicativo | deploy/docker/start.sh | 60-78 |
| Verificação de saúde Docker: confirmar processos Xtigervnc/websockify/antigravity_tools existem | deploy/docker/Dockerfile | 60-79 |
| Headless Xvfb: estrutura de diretório e comandos operacionais (systemctl/healthz) | deploy/headless-xvfb/README.md | 19-78 |
| Headless Xvfb: install.sh instalar dependências e inicializar gui_config.json (padrão 8045) | deploy/headless-xvfb/install.sh | 16-67 |
| Headless Xvfb: sync.sh descobrir automaticamente diretório de dados local e rsync para servidor | deploy/headless-xvfb/sync.sh | 8-32 |
| Headless Xvfb: upgrade.sh baixar nova versão e revertar em caso de falha | deploy/headless-xvfb/upgrade.sh | 11-51 |
Endpoint de verificação de vivacidade do serviço de proxy /healthz | src-tauri/src/proxy/server.rs | 120-194 |