Instalar o Apache Guacamole em uma VPS (2026): Docker, gateway de desktop remoto, HTTPS e configuração de segurança

O Apache Guacamole é um gateway de desktop remoto sem cliente. O navegador se comunica com o aplicativo web do Guacamole, que entrega a conexão ao processo proxy guacd, e o guacd se conecta ao destino real RDP, VNC, SSH, Telnet ou Kubernetes.

A estrutura de implantação deste artigo é a seguinte:

浏览器
  -> HTTPS 443
  -> Caddy
  -> Guacamole Web / Tomcat 8080
  -> guacd 4822（仅 Docker 内网）
  -> RDP 3389 / SSH 22 / VNC 5900 等目标主机

Guacamole Web
  -> MariaDB 3306（仅 Docker 内网）

O limite de segurança mais importante aqui é: a internet pública só vê o 80/443 do Caddy, o 8080 do Guacamole se vincula apenas ao endereço de loopback da VPS, e nem o guacd:4822 nem o banco de dados 3306 são mapeados para a rede pública do host.

A Apache adverte oficialmente que o guacd é um proxy passivo e não realiza nenhuma autenticação. Se o 4822 for exposto a uma rede não confiável, atacantes podem usá-lo como trampolim para outros sistemas. Por isso este artigo não configura ports para o guacd.

Se você tem apenas dois ou três dispositivos próprios, entrar primeiro na rede privada por meio de uma VPN WireGuard costuma ser mais simples. O Guacamole é mais adequado a cenários que precisam de acesso pelo navegador, atribuição centralizada de conexões, várias contas de usuário, histórico de conexões ou gerenciamento misto de RDP/VNC/SSH.

O Guacamole também não substitui a segurança do host de destino: o Windows ainda precisa de patches, NLA e senhas fortes; o Linux ainda deve restringir usuários SSH e privilégios de sudo; o VNC ainda precisa de autenticação confiável. O gateway apenas muda o caminho de acesso; ele não corrige vulnerabilidades nos serviços de backend.

O Guacamole em si não armazena um sistema de desktop completo, mas precisa transcodificar atualizações de tela e lidar com áudio, área de transferência, transferência de arquivos e várias conexões simultâneas. A latência e a largura de banda geralmente afetam a experiência de uso mais diretamente do que a capacidade de disco.

Resolução de tela, taxa de atualização, conteúdo de vídeo, áudio e qualidade da rede alteram o tráfego real. Navegar por uma interface de administração estática pode exigir pouca largura de banda, enquanto reproduzir vídeo ou rolar a tela com frequência aumenta muito os dados. Não compre com base em um "X Mbps fixos por usuário"; primeiro faça testes de carga com cargas de trabalho reais e depois monitore picos e tráfego mensal.

O data center deve estar próximo tanto dos usuários quanto dos hosts de destino. O caminho de acesso é "usuário → VPS do Guacamole → host de destino", e a latência alta em qualquer trecho se soma. Se os usuários estão na Ásia e o host de destino na Europa, colocar o gateway nas Américas normalmente não melhora a experiência.

Este artigo usa:

A 3389, a 22 ou a 5900 do host de destino também não precisa estar aberta para toda a internet. Se o destino for outro servidor público, o firewall deve permitir apenas o IP fixo da VPS do Guacamole; se o destino estiver em uma rede interna doméstica ou de escritório, primeiro estabeleça WireGuard, uma VPN site a site ou outro túnel controlado.

Atualizar o Ubuntu:

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg openssl ufw

Instale o Docker Engine e o plugin Compose a partir do repositório oficial do Docker e verifique:

docker version
docker compose version
sudo systemctl enable --now docker
sudo systemctl status docker --no-pager

Para rotação de logs, limites de recursos, reversão e gerenciamento de segredos em produção, você pode conferir a lista de verificação de configuração de produção do VPS Docker Compose.

Criar o diretório do projeto:

sudo install -d -m 750 /opt/guacamole
sudo chown "$(id -u):$(id -g)" /opt/guacamole
cd /opt/guacamole

Em agosto de 2026, a versão estável mais recente do Apache Guacamole é a 1.6.0. Este artigo fixa explicitamente as versões das imagens web e guacd para evitar que o latest mude de versão sem ninguém perceber. Antes de implantar, ainda vale consultar os Apache Guacamole Release Archives para confirmar se já existe uma versão mais nova.

Gerar o SQL de inicialização do MariaDB com o script integrado à imagem oficial:

docker run --rm guacamole/guacamole:1.6.0 \
  /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

test -s initdb.sql
chmod 600 initdb.sql
head -n 5 initdb.sql

O Guacamole não cria automaticamente as tabelas de autenticação JDBC; é preciso inicializar o banco de dados primeiro. Esse arquivo SQL é executado na primeira vez que o diretório de dados do MariaDB está vazio; se depois você reutilizar um volume de banco de dados existente, o script de entrada do Docker não o executará novamente.

Criar o /opt/guacamole/.env com um valor aleatório:

cd /opt/guacamole
umask 077

GUAC_DB_PASSWORD=$(openssl rand -hex 32)
GUAC_ROOT_PASSWORD=$(openssl rand -hex 32)

{
  printf 'MARIADB_DATABASE=guacamole_db\n'
  printf 'MARIADB_USER=guacamole_user\n'
  printf 'MARIADB_PASSWORD=%s\n' "$GUAC_DB_PASSWORD"
  printf 'MARIADB_ROOT_PASSWORD=%s\n' "$GUAC_ROOT_PASSWORD"
} > .env

unset GUAC_DB_PASSWORD GUAC_ROOT_PASSWORD
chmod 600 .env

Confirme que o nome da variável existe, mas não imprima o valor da senha em um terminal compartilhado ou em uma captura de tela:

cut -d= -f1 .env

O .env, os backups do banco de dados e as configurações de conexão do Guacamole podem conter informações sensíveis e não devem ser enviados a um repositório Git público.

Criar o /opt/guacamole/compose.yaml:

services:
  mariadb:
    image: mariadb:11.4
    container_name: guacamole-mariadb
    environment:
      MARIADB_ROOT_PASSWORD: "${MARIADB_ROOT_PASSWORD}"
      MARIADB_DATABASE: "${MARIADB_DATABASE}"
      MARIADB_USER: "${MARIADB_USER}"
      MARIADB_PASSWORD: "${MARIADB_PASSWORD}"
    volumes:
      - mariadb-data:/var/lib/mysql
      - ./initdb.sql:/docker-entrypoint-initdb.d/001-guacamole.sql:ro
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

  guacd:
    image: guacamole/guacd:1.6.0
    container_name: guacamole-guacd
    environment:
      LOG_LEVEL: info
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

  guacamole:
    image: guacamole/guacamole:1.6.0
    container_name: guacamole-web
    depends_on:
      mariadb:
        condition: service_healthy
      guacd:
        condition: service_started
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_ENABLED: "true"
      MYSQL_HOSTNAME: mariadb
      MYSQL_DATABASE: "${MARIADB_DATABASE}"
      MYSQL_USERNAME: "${MARIADB_USER}"
      MYSQL_PASSWORD: "${MARIADB_PASSWORD}"
      WEBAPP_CONTEXT: ROOT
      REMOTE_IP_VALVE_ENABLED: "true"
      TOTP_ENABLED: "true"
      BAN_ENABLED: "true"
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: "3"

volumes:
  mariadb-data:

Esta configuração aplica deliberadamente as seguintes restrições:

1. O Guacamole Web é mapeado apenas para 127.0.0.1:8080;
2. O guacd não tem mapeamento de porta no host e só é acessível pelo aplicativo web na rede do Compose;
3. O MariaDB não tem porta pública e persiste apenas em um volume nomeado;
4. O SQL de inicialização do banco de dados é montado como somente leitura;
5. A rotação de logs é configurada para web, guacd e banco de dados;
6. O Guacamole ativa o TOTP e mantém o bloqueio por falhas de login fornecido por padrão na imagem Docker 1.6.0;
7. O RemoteIpValve permite que o aplicativo atrás do proxy reverso reconheça o IP real do cliente; caso contrário, todos os logins com falha podem parecer vir do Caddy.

O WEBAPP_CONTEXT=ROOT coloca a página de login diretamente em /, em vez do padrão /guacamole/. Se você remover essa variável, tanto o Caddy quanto a URL de acesso precisam ser alterados para o subcaminho correspondente; não dá para mudar só um lado.

Primeiro deixe o Compose expandir e validar a configuração:

cd /opt/guacamole
docker compose config > /tmp/guacamole-compose-resolved.yaml
docker compose pull
docker compose up -d
docker compose ps

Ver os logs de inicialização:

docker compose logs --tail=200 mariadb
docker compose logs --tail=200 guacd
docker compose logs --tail=200 guacamole

Verificar as tabelas do banco de dados:

docker compose exec mariadb sh -c \
  'mariadb -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE" -e "SHOW TABLES;"'

Você deve ver tabelas como guacamole_user e guacamole_connection. Se as tabelas estiverem vazias, verifique primeiro se o MariaDB já havia criado um volume de dados antes de o initdb.sql ser gerado. O script de inicialização só é executado na primeira inicialização com um diretório de dados vazio; não tente a sorte reiniciando repetidamente.

Testar o web na própria VPS:

curl -I http://127.0.0.1:8080
sudo ss -lntp | grep ':8080'

Neste ponto, o http://VPS-IP:8080 não ser acessível pela internet pública é o resultado correto.

Acesse temporariamente do seu computador pessoal por um túnel SSH:

ssh -L 8080:127.0.0.1:8080 [email protected]

O 203.0.113.10 é um endereço de exemplo da documentação e deve ser substituído pelo IP público real da VPS. Mantenha a sessão SSH aberta e abra no navegador:

http://127.0.0.1:8080

O SQL de inicialização oficial do banco de dados cria um administrador padrão:

用户名：guacadmin
密码：guacadmin

Essas credenciais padrão são informações públicas e servem apenas para o primeiro login. Imediatamente após entrar no sistema:

1. Troque a senha do guacadmin por uma senha forte e aleatória gerada por um gerenciador de senhas;
2. Conclua o cadastro do TOTP e guarde com segurança o processo de recuperação;
3. Crie uma nova conta de administrador para o uso diário;
4. Crie um usuário de teste não administrador;
5. Depois de verificar que a nova conta consegue fazer login, pare de usar o administrador padrão no dia a dia;
6. Não conceda a usuários comuns permissão para criar usuários, modificar o sistema ou gerenciar todas as conexões.

Se você ainda não alterou a senha padrão, não exponha o domínio HTTPS para toda a internet e não comece a criar conexões de backend.

Aponte o registro DNS A/AAAA de remote.example.com para a VPS. O domínio de exemplo deve ser substituído pelo seu domínio real.

Adicione o seguinte ao Caddyfile:

remote.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8080
}

O Caddy lida automaticamente com o proxy WebSocket de que o Guacamole precisa; em geral, não é necessário escrever os cabeçalhos Upgrade manualmente. Valide e recarregue:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
sudo journalctl -u caddy -n 100 --no-pager

Abrir a porta web:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp comment 'Caddy HTTP'
sudo ufw allow 443/tcp comment 'Caddy HTTPS'
sudo ufw enable
sudo ufw status numbered

Não abra a 8080, a 4822 nem a 3306. Para o processo completo de instalação do Caddy, DNS e certificados automáticos, consulte o guia completo de Caddy como proxy reverso em uma VPS.

O Guacamole recomenda oficialmente encerrar o TLS no proxy reverso. O REMOTE_IP_VALVE_ENABLED=true faz o Tomcat usar o endereço do cliente e as informações de protocolo repassadas pelo proxy, o que é importante para o bloqueio de login, a auditoria e as restrições baseadas no IP de origem.

Depois de entrar na interface de administração, crie Connections nas configurações. Comece com uma conta de teste de baixo privilégio e destinos que não sejam de produção.

Protocol: SSH
Hostname: 10.20.0.10
Port: 22
Username: ops-test

Protocol: RDP
Hostname: 10.20.0.20
Port: 3389
Username: remote-user
Domain: 按实际环境填写
Security mode: NLA

Protocol: VNC
Hostname: 10.20.0.30
Port: 5900

nc -vz 10.20.0.10 22
nc -vz 10.20.0.20 3389
nc -vz 10.20.0.30 5900

Não torne todo mundo administrador nem deixe todos os usuários compartilharem a mesma conta do sistema de destino.

Camadas recomendadas:

• Administradores do sistema: responsáveis apenas pela configuração e auditoria do Guacamole;
• Administradores de conexão: gerenciam conexões específicas, não todos os usuários do sistema;
• Usuários comuns: só podem usar as conexões atribuídas a eles;
• Usuários somente leitura ou de demonstração: desative área de transferência, transferência de arquivos e capacidades de entrada que não sejam necessárias;
• Usuários temporários: defina um prazo de expiração explícito e revogue o acesso após o término da tarefa.

Para conexões sensíveis, considere:

• Não armazenar senhas de destino permanentemente no Guacamole; exigir a digitação no login;
• Cada usuário usar uma conta de destino independente, para facilitar auditoria e revogação;
• Desativar área de transferência, mapeamento de unidade, impressão, áudio e transferência de arquivos que não sejam necessários;
• Colocar ambientes de produção, teste e clientes em grupos de conexão diferentes;
• Restringir os horários e as sub-redes de origem a partir dos quais os usuários podem fazer login;
• Revisar periodicamente Active Sessions e History.

Os privilégios de administrador devem ser mínimos. Os administradores do sistema normalmente não são afetados por algumas restrições de login, então restrições por horário ou por endereço de origem não podem ser a única defesa das contas de administrador.

A imagem Docker oficial do Guacamole 1.6.0 oferece suporte a TOTP padrão via TOTP_ENABLED=true. Este artigo ativa tanto a autenticação por banco de dados quanto o TOTP, então os usuários precisam digitar um código de verificação dinâmico depois da senha.

Antes de entrar em produção, teste pelo menos:

• Administradores e usuários comuns concluem o cadastro do TOTP;
• A hora do servidor está correta, para que o TOTP não falhe continuamente por desvio de relógio;
• Existe um processo de recuperação controlado em caso de perda do celular;
• A recuperação exige verificação do administrador em vez de desativar todo o MFA;
• O IP do cliente repassado pelo proxy reverso está correto.

A imagem Docker do Guacamole 1.6.0 inclui por padrão uma extensão de bloqueio por falhas de login. O limite padrão oficial é de 5 falhas da mesma origem, com bloqueio de 300 segundos. Isso reduz a taxa de adivinhação de senhas online, mas não substitui senhas fortes, TOTP, restrições de origem e monitoramento de logs.

Ver os logs relacionados a logins com falha e bloqueios:

docker compose logs --since=1h guacamole | grep -i -E 'auth|fail|ban|invalid'

Se todas as solicitações aparecerem como 127.0.0.1 ou o mesmo endereço Docker, primeiro corrija o repasse do IP do cliente pelo proxy reverso e depois configure políticas baseadas no endereço de origem.

Os usuários, conexões, permissões e histórico do Guacamole ficam principalmente no banco de dados. Fazer backup apenas do compose.yaml não permite restaurar esses dados.

Criar um backup:

cd /opt/guacamole
backup_stamp=$(date +%Y%m%d-%H%M%S)
sudo install -d -m 700 /var/backups/guacamole

docker compose exec -T mariadb sh -c \
  'mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" --single-transaction "$MARIADB_DATABASE"' \
  | gzip > "/var/backups/guacamole/database-${backup_stamp}.sql.gz"

sudo tar -C /opt/guacamole -czf \
  "/var/backups/guacamole/config-${backup_stamp}.tar.gz" \
  compose.yaml .env initdb.sql

sudo chmod 600 /var/backups/guacamole/*

Verificar o backup:

gzip -t "/var/backups/guacamole/database-${backup_stamp}.sql.gz"
sudo tar -tzf "/var/backups/guacamole/config-${backup_stamp}.tar.gz"
ls -lh /var/backups/guacamole

Os arquivos de backup contêm hashes de senhas, informações de conexão e credenciais do banco de dados, por isso devem ser transferidos criptografados e com acesso restrito. Não deixe os backups apenas no mesmo disco da VPS; para um simulado completo de restauração, consulte o tutorial de simulado de backup e restauração em VPS.

Consulte as Guacamole Release Notes antes de atualizar. O esquema do banco de dados pode exigir a execução de SQL de atualização na ordem das versões; não basta alterar a tag da imagem e iniciar.

Registrar o estado atual:

cd /opt/guacamole
docker compose images
docker image inspect guacamole/guacamole:1.6.0 \
  --format '{{index .RepoDigests 0}}'
docker image inspect guacamole/guacd:1.6.0 \
  --format '{{index .RepoDigests 0}}'
docker compose ps

Processo de atualização:

1. Escolha uma janela de manutenção e avise os usuários ativos;
2. Interrompa novas conexões e confirme que as sessões ativas terminaram;
3. Faça backup do MariaDB, do .env, do Compose e dos arquivos de inicialização;
4. Leia todas as notas de Schema Upgrade da versão atual até a versão de destino;
5. Baixe as novas imagens e verifique as versões;
6. Execute o SQL de atualização do banco de dados na ordem oficial;
7. Atualize web e guacd para a mesma versão;
8. Recrie os contêineres e teste login, TOTP, SSH, RDP, VNC e histórico de auditoria;
9. Mantenha as imagens antigas e os backups e só limpe depois de confirmar a estabilidade.

Os componentes do Guacamole 1.x têm certa compatibilidade de protocolo, mas manter web, guacd, extensões e esquema do banco de dados na mesma versão ao longo do tempo é mais fácil de manter. Extensões de terceiros precisam ter a compatibilidade de API confirmada separadamente.

• Use uma versão estável do Guacamole atualmente suportada e versões correspondentes de web e guacd;
• Use autenticação por banco de dados e não trate o user-mapping.xml como solução de produção pública;
• O guacadmin / guacadmin padrão foi alterado imediatamente;
• O TOTP está ativado tanto para administradores quanto para usuários comuns;
• REMOTE_IP_VALVE_ENABLED=true, e a auditoria consegue ver o IP real do cliente;
• O 8080 se vincula apenas a 127.0.0.1;
• O 4822 e o 3306 não têm mapeamentos de porta no host;
• O HTTPS do Caddy funciona e o HTTP redireciona automaticamente para HTTPS;
• RDP, SSH e VNC de destino permitem acesso apenas da VPS do Guacamole ou da sub-rede da VPN;
• Usuários comuns não têm permissões de administração do sistema nem de todas as conexões;
• Área de transferência, transferência de arquivos, impressão e mapeamento de unidade desnecessários estão desativados;
• O banco de dados, o .env e as configurações de conexão têm backups criptografados;
• A restauração do banco de dados, a recuperação do TOTP e a reversão de imagem foram testadas;
• Logins com falha, sessões ativas, CPU, memória, largura de banda e disco são monitorados;
• Existe um processo fixo para remover usuários temporários, conexões antigas e permissões de funcionários desligados.

• Apache Guacamole 1.6.0 Release Notes
• Documentação de instalação do Apache Guacamole com Docker
• Documentação de autenticação de banco de dados MariaDB / MySQL
• Guia de implantação segura do Guacamole
• Autenticação multifator TOTP do Guacamole