README.pt.md
March 30, 2026 · View on GitHub
DockProbe
Painel leve de monitoramento Docker com detecção de anomalias e alertas Telegram
Um contêiner. Um comando. Visibilidade total.
English | 한국어 | 日本語 | Deutsch | Français | Español | Português | Italiano
O que é o DockProbe?
DockProbe é um painel de monitoramento Docker auto-hospedado que roda como um único contêiner. Ele coleta em tempo real métricas de CPU, memória, rede e disco de todos os seus contêineres e da máquina host — e exibe tudo em uma interface web limpa com tema escuro.
O monitoramento de host com suporte a GPU rastreia a temperatura e utilização de GPUs NVIDIA junto com o uso de CPU, memória do host, pressão de disco e média de carga — tudo em gráficos em tempo real. Se você executa cargas de trabalho de ML ou contêineres intensivos em GPU, o DockProbe oferece visibilidade completa sem instalar ferramentas de monitoramento GPU separadas.
Quando algo dá errado, o DockProbe detecta automaticamente. Seis regras integradas de detecção de anomalias monitoram picos de CPU, estouro de memória, alertas de temperatura, pressão de disco, reinicializações inesperadas e surtos de rede. Cada alerta inclui ações recomendadas com comandos prontos para execução — para que você saiba exatamente o que fazer, não apenas o que deu errado. Os alertas são enviados instantaneamente via Telegram para que você possa reagir antes que os usuários percebam.
Um scanner de segurança integrado executa 16 verificações automatizadas a cada 5 minutos — cobrindo erros de configuração de contêineres, exposição de rede e hardening do host — para detectar vulnerabilidades antes que se tornem incidentes.
Não há agente para instalar em cada contêiner, nem banco de dados externo, nem configuração complexa. Basta montar o socket do Docker, executar um comando, e você terá visibilidade completa do seu ambiente Docker em https://localhost:9090. Precisa acessar de fora da sua rede? O suporte integrado ao Cloudflare Tunnel oferece HTTPS público seguro sem redirecionamento de portas.
Início rápido
git clone https://github.com/deep-on/dockprobe.git && cd dockprobe && bash install.sh
É só isso. O instalador interativo configura a autenticação, alertas Telegram e HTTPS — depois abre https://localhost:9090.
Requisitos: Docker (com Compose v2), Git, OpenSSL
Executar a partir do Docker Hub
Sem git clone, sem build — basta fazer pull e executar:
# 1. Baixar o arquivo Compose e o modelo de variáveis de ambiente
curl -fsSL https://raw.githubusercontent.com/deep-on/dockprobe/main/docker-compose.hub.yaml -o docker-compose.yaml
curl -fsSL https://raw.githubusercontent.com/deep-on/dockprobe/main/.env.example -o .env
# 2. Editar .env com suas credenciais
vi .env
# 3. (Opcional) Gerar certificado SSL autoassinado
mkdir -p certs && openssl req -x509 -newkey rsa:4096 -nodes \
-keyout certs/key.pem -out certs/cert.pem \
-days 825 -subj "/CN=dockprobe"
# 4. Iniciar
docker compose up -d
Disponível no Docker Hub:
deeponinc/dockprobe— Multi-arch (amd64 + arm64)
Pré-visualização do painel
Funcionalidades
| Categoria | O que você obtém |
|---|---|
| Painel em tempo real | Interface web escura, atualização automática a cada 10s, tabelas ordenáveis, gráficos Chart.js |
| Monitoramento de contêineres | CPU %, memória %, E/S de rede, E/S de bloco, contador de reinícios |
| Monitoramento do host | Temperatura e utilização CPU/GPU, memória, uso de disco, média de carga |
| Detecção de anomalias | 6 regras com ações recomendadas — pico de CPU, estouro de memória, alta temperatura, disco cheio, reinício, pico de rede |
| Alertas Telegram | Notificação instantânea com cooldown de 30 min por tipo de alerta |
| Segurança | Basic Auth, limitação de taxa (5 falhas = 60s de bloqueio), HTTPS |
| Scanner de segurança | 16 verificações automatizadas (contêiner/host/rede), ciclo de varredura de 5 min, badges de severidade |
| Gestão de sessões | Rastreamento de conexões ativas, máx. conexões configurável, exibição de IP ao vivo |
| Gestão de senhas | Alterar usuário/senha pela interface do painel |
| Interface de configurações | Ajustar máx. conexões em tempo de execução pelo painel |
| Modos de acesso | SSL autoassinado (padrão) ou Cloudflare Tunnel (sem redirecionamento de portas) |
| Leve | 4 pacotes Python, arquivo HTML único, SQLite com retenção de 7 dias |
Composição do painel
| Seção | Detalhes |
|---|---|
| Barra de sessão | Usuário conectado, IP, conexões ativas / limite máximo |
| Cartões do host | Temp CPU, temp GPU, CPU/GPU %, memória do host, disco %, média de carga |
| Tabela de contêineres | Ordenável por CPU/memória/rede, anomalias com código de cores |
| Gráficos (5) | Tendências de CPU e memória dos contêineres, CPU/GPU % do host, temperatura e carga do host |
| Disco Docker | Imagens, cache de build, volumes, camadas RW dos contêineres |
| Histórico de alertas | Últimas 24h com timestamps |
Regras de detecção de anomalias
| Regra | Condição | Ação |
|---|---|---|
| CPU do contêiner | >80% por 3 verificações consecutivas (30s) | Telegram + destaque vermelho |
| Memória do contêiner | >90% do limite | Alerta imediato |
| Temperatura CPU do host | >85°C | Alerta imediato |
| Disco do host | >90% de uso | Alerta imediato |
| Reinício do contêiner | restart_count incrementado | Alerta imediato |
| Pico de rede | RX aumento de 10x + >100MB | Alerta imediato |
Todos os limites são configuráveis via variáveis de ambiente.
Cada anomalia inclui recomendações acionáveis com comandos específicos:
| Anomalia | Exemplo de recomendação |
|---|---|
| Pico de CPU | docker stats <name> · docker restart <name> · docker update --cpus=2 <name> |
| Estouro de memória | docker stats <name> · docker update --memory=2g <name> |
| Loop de reinício | docker logs --tail 50 <name> · docker inspect <name> |
| Pico de rede | docker logs --tail 50 <name> · Verificar DDoS ou tráfego inesperado |
| Alta temperatura | Verificar ventilador/sistema de refrigeração · sensors -u para detalhes |
| Disco cheio | docker system prune -f · docker builder prune -f · docker volume prune |
Scanner de segurança
O DockProbe executa 16 verificações de segurança automatizadas a cada 5 minutos e exibe os resultados em uma seção dedicada do painel com badges de severidade.
| Categoria | Verificações |
|---|---|
| Contêiner (9) | Modo privilegiado, execução como root, capabilities perigosas, montagem do socket Docker, montagem de caminhos sensíveis, rootfs somente leitura, AppArmor/Seccomp desabilitados, segredos em variáveis de ambiente, sem limites de memória/CPU |
| Rede (3) | Modo de rede do host, exposição excessiva de portas, exposição da porta SSH (22) |
| Host (4) | Opções de segurança do daemon Docker, ASLR do kernel, encaminhamento de IP, estado do Linux Security Module |
Níveis de severidade:
- 🔴 Crítico — Ação imediata necessária (ex.: modo privilegiado, socket Docker com escrita)
- 🟡 Aviso — Melhoria de segurança recomendada
- 🔵 Info — Descobertas informativas
- 🟣 Indisponível — A verificação não pode ser executada devido a restrições do ambiente; mostra como habilitá-la
As verificações a nível de host requerem montagens de volume (
/proc:/host_proc:ro,/sys:/host_sys:ro). Se não montados, essas verificações são exibidas como Indisponível com instruções de configuração.
Arquitetura
┌──────────────────────────────────────────────┐
│ DockProbe Container │
│ │
│ FastAPI + uvicorn (porta 9090) │
│ ├── collectors/ │
│ │ ├── containers.py (aiodocker) │
│ │ ├── host.py (/proc, /sys, GPU) │
│ │ └── images.py (system df) │
│ ├── alerting/ │
│ │ ├── detector.py (6 regras + ações) │
│ │ └── telegram.py (httpx) │
│ ├── security/ │
│ │ └── scanner.py (16 checks) │
│ ├── storage/ │
│ │ └── db.py (SQLite WAL) │
│ └── static/ │
│ └── index.html (Chart.js) │
│ │
│ Volumes: │
│ docker.sock (ro), /sys (ro), /proc (ro), │
│ nvidia-smi (ro), SQLite named volume │
└──────────────────────────────────────────────┘
Dependências (apenas 4 pacotes):
fastapi— Framework webuvicorn— Servidor ASGIaiodocker— Cliente Docker API assíncronohttpx— Cliente HTTP assíncrono (API Telegram)
Configuração
Todas as configurações via arquivo .env:
# Autenticação (obrigatório)
AUTH_USER=admin
AUTH_PASS=your-password
# Alertas Telegram (opcional)
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id
# Limites (opcional, valores padrão exibidos)
CPU_THRESHOLD=80
MEM_THRESHOLD=90
# Limite de conexões (opcional, 0 = ilimitado)
MAX_CONNECTIONS=3
# Cloudflare Tunnel (opcional)
CF_TUNNEL_TOKEN=your-tunnel-token
Modos de acesso
Opção 1: Rede local (SSL autoassinado) — padrão
bash install.sh # escolher opção 1
Acesso via https://localhost:9090 ou https://<seu-ip>:9090
Para acessar de outros dispositivos na mesma rede, use o IP LAN do servidor (ex: https://192.168.1.100:9090). Se necessário:
- Liberar a porta no firewall:
sudo ufw allow 9090/tcp - Aceitar o aviso de certificado autoassinado no navegador
Por que o aviso do navegador? O DockProbe usa um certificado SSL autoassinado gerado durante a instalação. Como não foi emitido por uma Autoridade Certificadora (CA) confiável, o navegador exibe um aviso "Sua conexão não é particular". Isso é normal — clique em "Avançado" → "Prosseguir para o site". Para eliminar este aviso, use o Cloudflare Tunnel (Opção 3) que fornece automaticamente um certificado TLS confiável.
Opção 2: Acesso remoto por redirecionamento de portas
Para acesso externo sem Cloudflare:
- Redirecionar a porta 9090 no roteador para o IP LAN do servidor
- Acessar via
https://<seu-ip-público>:9090 - Usar um serviço DDNS (No-IP, DuckDNS, etc.) se seu IP público mudar
Nota: A porta fica diretamente exposta. Basic Auth + HTTPS estão ativados por padrão, mas recomenda-se o Cloudflare Tunnel (Opção 3) para maior segurança.
Opção 3: Cloudflare Tunnel (recomendado para acesso remoto)
Sem redirecionamento de portas, sem alterações no firewall, certificado TLS válido — a forma mais fácil e segura de acessar de qualquer lugar.
bash install.sh # escolher opção 2, colar token do túnel
Passos de configuração:
- Criar uma conta gratuita no Cloudflare Zero Trust
- Ir em Networks > Tunnels > Create a tunnel
- Nomear o túnel (ex:
dockprobe) e copiar o token - Executar
bash install.she escolher a opção Cloudflare Tunnel - Colar o token
- No painel do Cloudflare, adicionar um Public Hostname apontando para
http://localhost:9090 - Acessar via
https://your-domain.comcom certificado TLS válido
Endpoints da API
| Endpoint | Método | Descrição |
|---|---|---|
/ | GET | HTML do painel |
/api/current | GET | Último snapshot (contêineres + host + imagens + anomalias) |
/api/history/{name}?hours=1 | GET | Séries temporais dos contêineres |
/api/history/host?hours=1 | GET | Séries temporais do host |
/api/alerts?hours=24 | GET | Histórico de alertas |
/api/session | GET | Usuário atual, IP, conexões ativas |
/api/settings | GET/POST | Configurações em tempo de execução (max_connections) |
/api/change-password | POST | Alterar usuário/senha |
/api/health | GET | Verificação de saúde (sem autenticação) |
Segurança
DockProbe é projetado para auto-hospedagem segura com múltiplas camadas de proteção:
Autenticação e acesso
- Basic Auth em todos os endpoints (exceto
/api/health) - PBKDF2-SHA256 hash de senha com sal aleatório (600k iterações)
- Limitação de taxa — 5 tentativas de login falhas → 60s de bloqueio por IP
- Mínimo de 8 caracteres exigidos para a senha
- Limite de conexões — Máximo de usuários simultâneos configurável
Rede e transporte
- HTTPS — RSA-4096 autoassinado (padrão) ou Cloudflare Tunnel
- CORS — Requisições de origem cruzada bloqueadas explicitamente
- Proteção CSRF — Endpoints POST exigem o cabeçalho
X-Requested-With - Aviso de fallback HTTP — Modo texto claro avisa na inicialização (apenas túnel)
Fortalecimento do contêiner
- Não root — O contêiner executa como
appuser, não como root - Montagens somente leitura — Docker socket, /sys, /proc todos montados em read-only
- Proteção contra travessia de caminho — O serviço de arquivos estáticos valida os caminhos resolvidos
- Sem acesso de escrita — Apenas monitoramento, sem controle de contêineres
- Sem OpenAPI/Swagger — Endpoints de documentação da API desativados em produção
Limitação de taxa com reconhecimento de proxy
X-Forwarded-Forsó é confiável a partir de IPs listados na variável de ambienteTRUSTED_PROXIES- Conexões diretas sempre usam o IP real do cliente
Configuração manual
Se preferir a configuração manual:
git clone https://github.com/deep-on/dockprobe.git
cd dockprobe
# Criar .env
cp .env.example .env
vi .env
# Gerar certificado SSL (opcional)
mkdir -p certs
openssl req -x509 -newkey rsa:2048 -nodes \
-keyout certs/key.pem -out certs/cert.pem \
-days 365 -subj "/CN=dockprobe"
# Iniciar
docker compose up -d --build
Licença
Apache License 2.0 — ver LICENSE
Atribuição: Versões modificadas ou redistribuídas devem manter o logo DeepOn e o aviso "Powered by DeepOn Inc." na interface.
Desenvolvido por DeepOn Inc.