O Beszel Hub armazena sistemas, usuários, dados históricos e alertas; o Agent coleta as métricas de CPU, memória, carga, disco, rede, temperatura e contêineres Docker/Podman do servidor onde é executado.

Ele é adequado para laboratórios domésticos, equipes pequenas e monitoramento rápido de até uma dúzia de VPS. Se você precisa de PromQL complexo, agregação de métricas de longo prazo ou métricas de negócio personalizadas, consulte o tutorial de Prometheus + Grafana em VPS. Se você só se importa se um site abre e com uma página de status pública, o Uptime Kuma é mais direto.

Há também uma questão prática: se o Hub e os serviços monitorados estiverem no mesmo VPS, quando essa máquina ficar totalmente offline, o Hub também não conseguirá enviar notificações. Para ambientes importantes, o melhor é executar o Hub de forma independente, ou ativar o Heartbeat externo do Beszel para enviar o status a outro serviço de monitoramento.

O Beszel não define oficialmente uma configuração mínima rígida. Para uso pessoal, você pode começar com 1 núcleo, 1 GB de memória e 10 GB de disco livre; o que realmente afeta o disco é o número de nós e o tempo de retenção do histórico, então não trate isso como um valor garantido.

Prepare um domínio, por exemplo monitor.example.com, com registros A/AAAA apontando para o VPS do Hub. Abra as portas conforme o método de conexão:

Para VPS remotos, recomenda-se WebSocket por padrão: o Agent se conecta ativamente ao endereço HTTPS do Hub, sem precisar expor a 45876 à internet. Se você escolher o modo SSH, permita a 45876 do Agent apenas a partir do IP do Hub. Antes de alterar o firewall, você pode ler o guia de UFW para evitar o bloqueio do SSH.

Registre uma linha de base antes de implantar, para depois saber pelas curvas se algo está anormal:

free -h
df -h
uptime
docker system df
timedatectl status

Se o disco já estiver quase cheio, não espere que o contêiner de monitoramento resolva; cuide primeiro dos logs e dos backups. O horário do sistema também precisa estar preciso, caso contrário os gráficos e os horários dos alertas de vários VPS não vão coincidir. Ao se preparar para monitorar mais de vinte servidores, execute primeiro alguns nós por uma semana e depois decida o disco e a política de retenção com base no crescimento real de beszel_data; isso é mais confiável do que copiar os números de capacidade de outra pessoa.

Primeiro instale o Docker Engine e o plugin Compose, depois crie o diretório:

sudo mkdir -p /opt/beszel
sudo chown "$USER":"$USER" /opt/beszel
cd /opt/beszel
mkdir -p beszel_data beszel_agent_data beszel_socket

Crie um novo docker-compose.yml. Deixe valores de espaço reservado para o Agent por enquanto e inicie apenas o Hub na primeira vez:

services:
  beszel:
    image: henrygd/beszel:0.18.7
    container_name: beszel
    restart: unless-stopped
    environment:
      APP_URL: https://monitor.example.com
    ports:
      - 127.0.0.1:8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket

  beszel-agent:
    image: henrygd/beszel-agent:0.18.7
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - ./beszel_socket:/beszel_socket
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: /beszel_socket/beszel.sock
      HUB_URL: http://localhost:8090
      TOKEN: YOUR_SYSTEM_TOKEN
      KEY: "YOUR_SYSTEM_PUBLIC_KEY"

Verifique a configuração e inicie apenas o Hub:

docker compose config
docker compose up -d beszel
docker compose ps
docker compose logs --tail=100 beszel
curl -I http://127.0.0.1:8090

Você pode conferir a versão da imagem nos Releases oficiais. Altere a tag ao atualizar; não deixe uma única reconstrução mudar de versão silenciosamente. Para verificações de integridade, logs e limites de recursos do Compose em produção, consulte a lista de configuração de produção do Docker Compose.

O Agent do Beszel pode se conectar ao Hub via WebSocket, então o proxy reverso precisa permitir conexões de longa duração. A configuração do Caddy não pode ser apenas a linha mais curta; o exemplo oficial também define o tamanho do corpo da requisição e um tempo limite de leitura de 360 segundos:

monitor.example.com {
    request_body {
        max_size 10MB
    }
    reverse_proxy 127.0.0.1:8090 {
        transport http {
            read_timeout 360s
        }
    }
}

Valide e recarregue:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://monitor.example.com
sudo ss -lntup | grep -E ':443|:8090|:45876'

A 8090 deve escutar apenas em 127.0.0.1. Para o processo de instalação completo, consulte o guia de proxy reverso Caddy. APP_URL deve ser o endereço HTTPS final; ele é usado para links de notificação e geração da configuração do Agent.

Abra https://monitor.example.com e crie a primeira conta. O Beszel é baseado no PocketBase, e a configuração inicial cria tanto um usuário do Hub quanto um superusuário do PocketBase; alterar a senha das duas contas depois não sincroniza automaticamente, então é melhor rotulá-las separadamente no seu gerenciador de senhas.

Clique em Add System no canto superior direito, preencha o nome do sistema e defina Host/IP como:

/beszel_socket/beszel.sock

A interface mostrará uma Public Key e um Token. Substitua KEY e TOKEN no Compose por eles, respectivamente, e então inicie o Agent local:

docker compose up -d beszel-agent
docker compose logs --tail=100 beszel-agent
docker compose ps

Só quando o sistema passar de Pending para Up e aparecer o primeiro conjunto de dados de CPU e memória a conexão estará concluída. Não envie Keys, Tokens ou URLs de notificação reais para um repositório Git.

A forma mais simples para nós remotos é copiar o Compose gerado na página Add System do Hub. No modo WebSocket, o Agent acessa ativamente o Hub, e você pode usar a seguinte estrutura:

services:
  beszel-agent:
    image: henrygd/beszel-agent:0.18.7
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      HUB_URL: https://monitor.example.com
      TOKEN: YOUR_SYSTEM_TOKEN
      KEY: "YOUR_SYSTEM_PUBLIC_KEY"
      DISABLE_SSH: "true"

DISABLE_SSH=true significa usar apenas WebSocket e não iniciar mais o serviço SSH do Agent. Se você mudar para o modo SSH, a direção da conexão se inverte: o Hub acessa ativamente a 45876 do Agent; um iptables FORWARD DROP rígido também pode bloquear o tráfego de saída do contêiner do Hub, e nesse caso voltar ao WebSocket é mais fácil de diagnosticar.

Cada nó usa seu próprio Token de sistema; não copie o mesmo diretório de dados do Agent em várias máquinas. Se a impressão digital mudar após uma migração do servidor, confirme o nó de destino no Hub e registre-o novamente, em vez de reiniciar repetidamente e torcer para dar certo.

O Agent lê a lista de contêineres e as estatísticas pelo Docker Socket; primeiro compare a saída dos dois lados:

docker ps
docker stats --no-stream
docker compose logs --tail=150 beszel-agent
ls -l /var/run/docker.sock

As causas comuns são caminho de Socket errado, Podman usando outro Socket, o Agent não ter sido recriado ou o contêiner estar excluído por EXCLUDE_CONTAINERS. Após alterar a montagem, execute:

docker compose up -d --force-recreate beszel-agent

:ro apenas restringe como o sistema de arquivos é montado dentro do contêiner; não transforma o Docker Socket em uma interface de baixo privilégio. Um processo que consegue acessar o Socket geralmente tem uma capacidade de controle do host muito alta. Não exponha a API do Docker em 0.0.0.0:2375, nem dê ao Agent privileged: true só para ver métricas.

Abra os alertas na lista de sistemas e primeiro defina os limites de offline, disco, memória ou CPU. Não copie os limites às cegas: um banco de dados que fica em 80% de memória a longo prazo sem oscilações de Swap não é a mesma coisa que um serviço web que de repente salta de 30% para 80%.

A entrada de notificações fica em Settings > Notifications, e o Beszel usa URLs do Shoutrrr. Por exemplo, um ntfy auto-hospedado pode ser escrito como:

ntfy://:[email protected]/beszel-alerts

Após salvar, envie primeiro uma notificação de teste e depois reduza brevemente o limite de um nó que não seja de produção para confirmar que tanto o disparo quanto a recuperação do alerta são recebidos. A URL de notificação contém credenciais, então mascare-a antes de compartilhar capturas de tela e logs. Se o Hub e o serviço de notificação também estiverem no mesmo VPS com falha, os alertas ainda não sairão.

O Beszel também permite enviar periodicamente um Heartbeat para um endereço externo. Aponte HEARTBEAT_URL para outro Uptime Kuma, Healthchecks.io ou serviço semelhante, e mesmo que o Hub fique totalmente offline, o serviço externo conseguirá detectar a interrupção do heartbeat. Ele não substitui os alertas de recursos, mas cobre especificamente o ponto cego de "o próprio sistema de monitoramento morreu e ninguém sabe". Após configurar, pare uma vez o Hub em um ambiente de teste para confirmar que o alerta externo realmente dispara, e depois restaure o serviço.

Os dados principais ficam em /opt/beszel/beszel_data. O painel de administração permite salvar em disco ou em armazenamento compatível com S3, mas ainda assim você deve fazer periodicamente um teste de recuperação. Um backup simples com parada pode ser feito assim:

cd /opt/beszel
backup_date="$(date +%F)"
docker compose stop beszel
sudo tar -czf "/var/backups/beszel-${backup_date}.tar.gz" \
  beszel_data docker-compose.yml
docker compose start beszel
sudo tar -tzf "/var/backups/beszel-${backup_date}.tar.gz" | head
curl -I https://monitor.example.com

O arquivo compactado também deve ser copiado para outra máquina ou armazenamento de objetos. Para operações formais, você pode combinar com o simulado de backup e restauração em VPS.

Consulte os Releases antes de atualizar e, após concluir o backup, altere a mesma tag de versão tanto no Hub quanto no Agent:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 beszel
docker compose logs --tail=100 beszel-agent

Só encerre a manutenção depois que a página, um Agent local e um Agent remoto estiverem funcionando normalmente. Se falhar, restaure a tag de imagem original; se a nova versão já tiver modificado a estrutura de dados, restaure o mesmo backup anterior à atualização, não apenas faça o downgrade da imagem e force.

Faça mais uma rodada de aceitação antes de entrar em produção: após reiniciar o Docker, o Hub e o Agent devem se recuperar automaticamente; desligue um Agent de teste e o alerta de offline deve chegar conforme o esperado; após a recuperação o status deve voltar a ficar verde; extraia o backup em outra máquina e você deve ver pelo menos os dados do PocketBase e o arquivo Compose. Ver curvas na página inicial não significa que os alertas, a persistência e a cadeia de recuperação funcionem.

• Quer ver rapidamente vários servidores e recursos do Docker: escolha o Beszel;
• Quer monitorar URLs, validade de certificados e uma página de status pública: escolha o Uptime Kuma;
• Quer coletar métricas de negócio, escrever consultas complexas e escalar a longo prazo: escolha Prometheus + Grafana.

A vantagem do Beszel é a implantação leve e o início rápido; o ponto fraco é que as consultas personalizadas e o ecossistema não são tão bons quanto os do Prometheus. Conecte primeiro um VPS não crítico, provoque um alerta de teste e depois faça um backup em outra máquina que você consiga extrair; só depois que os três passos passarem adicione os nós de produção em lote.