Como fazer self-host do CloudBeaver em 2026: drivers de banco de dados, workspace e acesso

A demonstração mais curta do CloudBeaver prova que um processo está escutando na porta 8978. Em produção, é preciso ter evidências mais sólidas. O sistema deve passar por este cenário mesmo depois de o container ser substituído: concluir a configuração do administrador, instalar o driver necessário, conectar-se por um hostname privado e executar uma query somente leitura.

O CloudBeaver é implantado com um objetivo claro: ser um cliente de banco de dados no navegador para Postgres, MySQL e outros bancos. A armadilha mais comum nessa implantação é as permissões do workspace falharem ou o DNS do container não conseguir resolver os hosts dos bancos de dados. Por isso, o tratamento da URL pública e o estado persistente devem receber a mesma atenção que a inicialização da imagem.

Restaurar o CloudBeaver em um host vazio

Liste o estado antes da criação do primeiro registro real: workspace, usuários, definições de conexão e armazenamento de credenciais. Monte /opt/cloudbeaver/workspace antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Confirme o mount gravando dados inofensivos, substituindo o CloudBeaver e lendo esses dados novamente.

Snapshots são valiosos para rollback rápido, mas é necessário ter um backup independente quando o host ou o volume desaparece. Restaure em um ambiente vazio usando a imagem fixada e verifique se o workspace, os usuários, os drivers e as conexões retornam, enquanto cada banco de dados subjacente segue seu próprio plano de backup. Use volumes persistentes e snapshots para manter esses dois mecanismos de recuperação distintos.

Iniciar o CloudBeaver com padrões observáveis

O comando a seguir torna visível a fronteira do container sem fingir provisionar todos os serviços externos.

docker run -d \
  --name cloudbeaver \
  --restart unless-stopped \
  -p 127.0.0.1:8978:8978 \
  -v cloudbeaver-data:/opt/cloudbeaver/workspace \
  -e CB_SERVER_NAME=CloudBeaver \
  dbeaver/cloudbeaver:latest

Antes de abrir o ingress, inspecione o ambiente resolvido, os mounts e o listener. Adicione as configurações de conexão revisadas para rotas privadas e os drivers de banco de dados para cada banco de destino; use nomes privados para serviços privados. Uma inicialização bem-sucedida termina quando você consegue concluir a configuração do administrador, instalar o driver necessário, conectar-se por um hostname privado e executar uma query somente leitura — não quando docker ps imprime Up.

Do que o CloudBeaver depende

O processo HTTP do CloudBeaver escuta na porta 8978; mantenha essa porta na rede da aplicação e publique apenas a rota da plataforma. O contrato de rede do CloudBeaver consiste em rotas privadas e drivers de banco de dados para cada banco de destino. Mantenha os endpoints privados no DNS interno, permita apenas as chamadas de saída necessárias e forneça ao CloudBeaver uma credencial de serviço com escopo limitado.

Registre a fronteira em um contrato curto: quem é responsável pelo requisito, qual credencial é usada, qual timeout é aceitável e como a falha se manifesta. Em seguida, execute esta transação: concluir a configuração do administrador, instalar o driver necessário, conectar-se por um hostname privado e executar uma query somente leitura. Observe o estado do workspace, os downloads de drivers, as sessões simultâneas e a latência de rede até cada banco de dados durante a execução, pois essa carga fornece um tamanho inicial mais útil do que um container ocioso.

Manter claras as URLs internas e externas

A fronteira pública do CloudBeaver deve ser um único hostname canônico, com TLS automático e um único destino interno na porta 8978. Configure a URL do servidor e os headers de proxy para a origem HTTPS pública, para que os clientes retornem a um endereço reconhecido pelo serviço.

Se a transação de aceitação falhar, classifique o primeiro erro. Problemas de DNS, certificado e 502 pertencem ao checklist de validação de TLS. A condição “as permissões do workspace falham ou o DNS do container não consegue resolver os hosts dos bancos de dados” pertence ao lado da aplicação, depois que uma requisição chegou com sucesso ao CloudBeaver.

Uma execução de aceitação de produção para o CloudBeaver

Não use o tráfego do primeiro usuário como teste de aceitação do CloudBeaver. Prepare um estado de exemplo inofensivo e execute a ação completa “concluir a configuração do administrador, instalar o driver necessário, conectar-se por um hostname privado e executar uma query somente leitura”. Registre a URL pública exata, o resultado, a referência da imagem e o intervalo de logs associados à execução.

Substitua o container e repita sem reconstruir os dados. Em seguida, faça a recuperação em um host vazio; a condição de recuperação é que o workspace, os usuários, os drivers e as conexões retornem, enquanto cada banco de dados subjacente segue seu próprio plano de backup. Observe o estado do workspace, os downloads de drivers, as sessões simultâneas e a latência de rede até cada banco de dados em todas as etapas e defina um alerta para a degradação da transação, não para as métricas de um container ocioso.

Uma verificação final deve falhar propositalmente: negue temporariamente à identidade de teste o acesso às rotas privadas e aos drivers de banco de dados para cada banco de destino. Verifique se a mensagem resultante do CloudBeaver identifica a fronteira relevante, em vez de acionar a exclusão de dados ou um restart infinito. Restaure a condição válida e confirme que a mesma transação de exemplo é concluída com sucesso. Mantenha esse exercício curto no checklist de release.

Diagnosticar um CloudBeaver com aparência saudável

A primeira métrica operacional útil do CloudBeaver é saber se ele consegue concluir a configuração do administrador, instalar o driver necessário, conectar-se por um hostname privado e executar uma query somente leitura. Combine isso com sinais de saturação do estado do workspace, dos downloads de drivers, das sessões simultâneas e da latência de rede até cada banco de dados. Um probe que verifica apenas o processo não deve chamar dependências dispendiosas nem reiniciar o container porque um upstream está temporariamente indisponível.

Trate os upgrades como alterações de dados, pois as migrações do workspace do CloudBeaver e a compatibilidade dos drivers devem ser testadas antes da mudança de versões da imagem. Fixe as versões, faça ensaios com o estado restaurado e mantenha a imagem anterior disponível até que um rollback continue sendo válido. Quando as permissões do workspace falharem ou o DNS do container não conseguir resolver os hosts dos bancos de dados, preserve os logs anteriores ao restart; eles geralmente contêm a mensagem causal.

Decisões de segurança específicas do CloudBeaver

Não herde as premissas de segurança de um tutorial local. A preocupação específica do CloudBeaver é permitir acesso anônimo a conexões de banco de dados de produção. Por isso, a produção deve desabilitar a administração anônima, usar usuários individuais e conceder às contas de banco de dados apenas as permissões necessárias para cada conexão.

CB_SERVER_NAME controla o comportamento, não a confidencialidade; valide seu tipo e valor e armazene as credenciais reais do CloudBeaver separadamente. Restrinja o acesso ao sistema de arquivos e à rede, proteja os endpoints de configuração e defina limites de upload, requisição ou execução em torno do estado do workspace, dos downloads de drivers, das sessões simultâneas e da latência de rede até cada banco de dados.

Uma implantação do CloudBeaver na Dockup ainda precisa de um teste de aceitação

A implantação do CloudBeaver em um clique da Dockup deve tornar a substituição segura: a rota continua apontando para a porta 8978, os secrets não são incorporados à imagem e os caminhos persistentes retornam no novo container. A mesma implantação pode ser executada no compute da Dockup ou em uma máquina conectada.

Conclua o trabalho específico da aplicação conectando-se e testando as rotas privadas e os drivers de banco de dados para cada banco de destino, aplicando o endereço público canônico e executando esta verificação de aceitação: concluir a configuração do administrador, instalar o driver necessário, conectar-se por um hostname privado e executar uma query somente leitura. Adicione o resultado da restauração ao runbook antes da chegada dos usuários reais.

Perguntas frequentes

O que o CloudBeaver precisa para uma implantação de produção?

Encaminhe o container do CloudBeaver na porta 8978 por meio de uma única origem HTTPS. O requisito de rede de suporte consiste em rotas privadas e drivers de banco de dados para cada banco de destino. Não considere o CloudBeaver pronto até conseguir concluir a configuração do administrador, instalar o driver necessário, conectar-se por um hostname privado e executar uma query somente leitura.

Quais dados do CloudBeaver devem fazer parte de um backup?

Mantenha /opt/cloudbeaver/workspace persistente e inclua o workspace, os usuários, as definições de conexão e o armazenamento de credenciais no mesmo manifesto de recuperação. Uma restauração limpa do CloudBeaver só é bem-sucedida quando o workspace, os usuários, os drivers e as conexões retornam, enquanto cada banco de dados subjacente segue seu próprio plano de backup.

O CloudBeaver precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do CloudBeaver e mantenha a porta 8978 na rota interna. Aplique corretamente a configuração do CloudBeaver: defina a URL do servidor e os headers de proxy para a origem HTTPS pública. No CloudBeaver, o HTTPS protege credenciais ou conteúdo do usuário durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do CloudBeaver?

Restaure o estado atual do CloudBeaver em uma implantação isolada, aplique a versão candidata e repita sua transação de aceitação. Dê atenção especial a esse processo, pois as migrações do workspace do CloudBeaver e a compatibilidade dos drivers devem ser testadas antes da mudança de versões da imagem. Mantenha a imagem anterior do CloudBeaver até entender os limites da migração de dados e do rollback.