Beszel: Monitorização Leve de Servidores

O Monit vigia processos e o Monitorix desenha gráficos de um servidor, mas nenhum dos dois dá a vista de conjunto: uma tabela com todos os servidores da PME, CPU e memória ao minuto, e histórico de semanas para comparar. O Beszel é essa vista — um hub leve com interface web, agentes por sistema, métricas de Docker e Podman, alertas e histórico, tudo em dois containers e sem base de dados externa: o hub usa PocketBase embutido. MIT, escrito em Go, com a v0.20.0 de Setembro de 2026, e um footprint menor do que as soluções líderes — o próprio projecto dimensiona-se por aí.

O guia instala o hub em Docker, liga o primeiro agente e configura alertas.

Neste artigo

  1. Arquitectura: hub + agentes
  2. Instalar o hub
  3. Ligar o primeiro sistema
  4. Alertas e notificações
  5. Beszel, Netdata e Uptime Kuma

1. Arquitectura: hub + agentes

Duas peças. O hub é a aplicação web (PocketBase) que agrega, desenha e guarda o histórico — a porta 8090, com os dados em /beszel_data. O agente corre em cada máquina monitorizada e envia métricas ao hub: CPU, memória (com swap e ZFS ARC), disco e I/O, rede, load average, temperaturas e ventoinhas, GPU (Nvidia, AMD, Intel), bateria, S.M.A.R.T. dos discos, e o consumo por container Docker/Podman. Desde versões recentes há também monitores de rede — ICMP, TCP, HTTP e DNS, com tempo de resposta e perda de pacotes —, avaliados a partir do próprio agente.

A comunicação tem dois modos, definidos na documentação de segurança. No SSH é o hub que inicia a ligação ao agente, na porta 45876: o hub gera uma chave ED25519 no primeiro arranque e o servidor SSH do agente só aceita ligações com essa chave, sem terminal nem execução de comandos. No WebSocket é o agente que inicia a ligação ao hub, no caminho /api/beszel/agent-connect, com um handshake de autenticação mútua: o agente apresenta o token de registo, o hub responde com a assinatura desse token pela chave privada ED25519, e o agente valida e responde com o seu fingerprint, que fecha o registo à máquina onde corre. Desde a v0.12.0 há um token universal em Settings → Tokens que liga agentes sem configuração prévia no hub. A autenticação do hub aceita contas locais e OAuth/OIDC — a documentação lista Authelia, authentik, Gitea, GitLab, Kanidm, Keycloak, mailcow, Pocket ID, VoidAuth e ZITADEL —, com multi-utilizador: cada utilizador gere os seus sistemas, e os admins partilham sistemas entre contas.

2. Instalar o hub

Em Docker, o compose oficial traz hub e agente local num ficheiro:

services:
beszel:
image: henrygd/beszel
container_name: beszel
restart: unless-stopped
environment:
APP_URL: http://192.168.1.10:8090
ports:
– 8090:8090
volumes:
– ./beszel_data:/beszel_data
beszel-agent:
image: henrygd/beszel-agent
container_name: beszel-agent
restart: unless-stopped
network_mode: host
volumes:
– ./beszel_socket:/beszel_socket
– /var/run/docker.sock:/var/run/docker.sock:ro
environment:
LISTEN: 45876
KEY: '<chave pública>'

O APP_URL muda para o endereço pelo qual a equipa acede ao hub (IP ou domínio com porta) — é o URL usado nos links e redirects. No agente, o KEY é a chave pública que o diálogo Add System gera. Arrancar e criar a conta:

mkdir beszel && cd beszel
nano docker-compose.yml
docker compose up -d

O primeiro acesso a http://192.168.1.10:8090 pede a criação da conta de administração. Quem preferir sem Docker: o hub também corre de binário único, e o compose oficial inclui healthchecks comentados que se activam à vontade.

3. Ligar o primeiro sistema

No hub: Add System → nome, endereço do agente (IP interno e porta 45876, ou o socket Unix na instalação local) e o par chave/token que o diálogo gera. No servidor a monitorizar, o agente instala-se com o script oficial — o comando vem pronto no diálogo Add System:

curl -sL https://get.beszel.dev -o /tmp/install-agent.sh
sudo bash /tmp/install-agent.sh -p "<porta>" -k "<chave pública>"

O script cria o utilizador beszel, instala o binário, cria o serviço systemd e arranca o agente, e com a opção de updates diários automáticos activada, o agente mantém-se actualizado sozinho. O sistema aparece no hub em segundos — verde na agulha. Em vermelho, o checklist dos erros comuns resolve a maioria: no modo SSH a causa típica é a porta 45876 inacessível a partir do hub, no modo WebSocket é o agente sem rota para o hub ou um reverse proxy sem upgrade WebSocket.

Para Docker/Podman em vez do binário, o diálogo Add System fornece o compose do agente — com o socket do Docker em /var/run/docker.sock:ro para as métricas de containers.

Beszel: vista de conjunto dos sistemas e detalhe de um host com métricas de containers

Hub do Beszel: tabela de todos os sistemas com CPU, memória, disco, rede e estado do agente, e a página de sistema com histórico e métricas por container (imagem oficial do projecto).

4. Alertas e notificações

Cada métrica tem alertas configuráveis por limiar: CPU acima de X%, memória acima de Y%, disco quase cheio, agente offline, temperatura, utilização por container. Os alertas criam-se na página de sistema (ou globalmente) com um clique, e as notificações saem por Shoutrrr — um único URL por serviço:

telegram://<token>@telegram?chats=<chat-id ou @canal>
mattermost://<host>/<token>/<canal>
generic://hooks.empresa.pt/alerta?template=json

A lista cobre cerca de 23 serviços: Bark, Discord, Gotify, Google Chat, IFTTT, Mattermost, Matrix, MQTT, ntfy, OpsGenie, Pushbullet, Pushover, Rocketchat, Signal, Slack, Teams, Telegram, Twilio, WeCom, Zulip, entre outros. O generic:// é um webhook genérico (não email): envia o payload para qualquer endpoint HTTP que a equipa tenha. O caso típico da PME: alerta de disco >90% e agente offline para o canal de sistemas no Mattermost — que é também onde correm os playbooks de incidente.

5. Beszel, Netdata e Uptime Kuma

Beszel Netdata Uptime Kuma
Modelo hub + agentes agente por nó monitor de serviços
Peso mínimo (Go, PocketBase) pesado (1 agente por nó) leve
Métricas de sistema sim (host + containers) sim, detalhado não (só HTTP/portas)
Histórico e dashboards sim sim não
Alertas limiares por métrica muitos por monitor

O Beszel preenche o meio: mais histórico e containers do que o Uptime Kuma, mais leve do que o Netdata — e o dashboard único que o Monit e o Monitorix não têm. Nota honesta sobre o peso: o “menor footprint” é a afirmação do próprio projecto (“Smaller and less resource-intensive than leading solutions”), não uma medição independente — e o modelo de 1 agente por nó que penaliza o Netdata aplica-se igualmente ao Beszel. A doc também lista monitores de rede no agente — ICMP, TCP, HTTP e DNS (tempo de resposta e perda de pacotes) —, o que aproxima o Beszel do território do Uptime Kuma, que continua a ter mais tipos de monitor e uma comunidade maior nesse campo. Para quem já tem Zabbix, o Beszel cobre os servidores pequenos e o homelab sem a infra-estrutura do Zabbix. O histórico de semanas e meses só fica completo se o agente estiver sempre a correr: os dados vêm do agente, e períodos em baixo ficam em branco nos gráficos.

Erros Comuns

Erro Causa provável Correcção
Sistema fica vermelho no hub No SSH, porta 45876 inacessível do hub. No WebSocket, o agente não alcança o hub ou o reverse proxy não faz upgrade systemctl status beszel-agent, abrir a 45876 no modo SSH, e no modo WebSocket permitir a chegada do agente a /api/beszel/agent-connect (proxy com suporte WebSocket)
Métricas Docker ausentes Socket não montado, cgroup memory accounting desligado ou agente rootless Montar /var/run/docker.sock:ro. Se docker stats mostra memória a zero, activar o cgroup memory accounting. Em agente rootless, socket do utilizador e delegação de CPU no cgroup (issue #640)
Hub inacessível depois de funcionar Container parado, porta 8090 não publicada ou reverse proxy em baixo (o APP_URL é só o URL de acesso usado nos links e redirects, não impede o arranque) docker logs beszel, confirmar docker ps e o proxy
Agente não actualiza Updates diários desactivados na instalação Re-executar o install script com a opção de updates

Checklist

  • [ ] Hub activo na 8090 com beszel_data persistente
  • [ ] Conta de administração criada (ou OAuth/OIDC ligado)
  • [ ] Agente instalado em cada servidor a monitorizar
  • [ ] Socket do Docker montado nos servidores com containers
  • [ ] Alertas de disco, memória e agente offline configurados
  • [ ] Notificações Shoutrrr configuradas (a verificação faz-se gerando um alerta de teste)
  • [ ] Backup activo em Settings → Backups (disco ou S3) — a doc também aceita copiar a pasta beszel_data com o hub parado
  • [ ] Dashboard partilhado com a equipa

Artigos Relacionados

Fontes Oficiais