theia

Theia – Análise Server-Side Focada em Privacidade Visão Geral O Theia fornece estatísticas de tráfego de site sem qualquer JavaScript do lado do cliente. Ele monitora os logs de acesso do nginx em tempo real, analisa cada linha para extrair caminho, referenciador, user-agent, IP, código de status e bytes enviados, faz hash dos IPs por privacidade e armazena os resultados em um banco de dados SQLite local. Como todo o processamento ocorre no servidor, os dados são imunes a ad-blockers e não dependem de serviços de terceiros. Instalação Instalação rápida: baixe o script de instalação com curl ou wget e execute com sudo bash. O script detecta a arquitetura, instala o binário em /usr/local/bin/theia, adiciona um formato personalizado de log nginx para rastreamento multi-domínio (opcional), cria um serviço systemd e prepara /var/lib/theia para armazenamento de dados. A instalação manual também é suportada – clone o repositório, compile com go build, copie o binário, crie o diretório de dados e instale a unidade systemd fornecida. Executando o daemon O daemon acompanha o log de acesso do nginx e grava registros analisados no banco de dados SQLite. Comando de exemplo: sudo theia daemon --log-path /var/log/nginx/access.log --db-path /var/lib/theia/theia.db Principais flags: --log-path (padrão /var/log/nginx/access.log) e --db-path (padrão ./theia.db). Estatísticas via linha de comando O subcomando stats lê o banco de dados e exibe uma tabela resumo ou saída JSON. Uso típico: theia stats --db-path /var/lib/theia/theia.db As opções permitem alterar o período de consulta (--days), filtrar por host (--host), escolher o formato de saída (--format json|table) e ajustar o número de principais entradas (--top). Serviço HTTP API O comando serve inicia uma API HTTP/JSON (ou CSV) protegida por bearer token em 127.0.0.1:8081. Pode ser proxy através do nginx para expô-la externamente. A autenticação pode ser fornecida via arquivo de token, variável de ambiente ou flag de linha de comando. Endpoints incluem: GET /api/v1/stats – dados de série temporal GET /api/v1/stats/paths – principais caminhos GET /api/v1/stats/referrers – principais referenciadores GET /api/v1/stats/status-codes – detalhamento por códigos de status Parâmetros de query comuns: host, from, to, format, group_by, top. Completion para shell Executar theia completion detecta o shell atual e oferece instalar scripts de completion para bash, zsh ou fish. Gerenciamento de serviço O Theia executa como uma unidade systemd. Use comandos systemctl padrão para iniciar, parar, reiniciar, visualizar status e acompanhar logs. Como funciona internamente 1. Acompanha o arquivo de log nginx em tempo real. 2. Analisa cada linha para campos relevantes. 3. Faz hash de IP + user-agent + data para preservar anonimato. 4. Detecta bots e requisições de assets estáticos automaticamente. 5. Grava registros de forma assíncrona no SQLite (modo WAL) permitindo leitores concorrentes. 6. Limpeza periódica remove estatísticas horárias com mais de 60 dias. Considerações de segurança O daemon precisa de acesso root ou sudo para ler os logs do nginx. O token da API deve ser armazenado em um arquivo em vez de na linha de comando para evitar exposição via lista de processos. Limitação de taxa e regras fail2ban para scanners ruidosos são recomendadas (consulte docs/nginx-hardening.md). Limitações * Apenas contagens de visualizações de página são coletadas; sem eventos do lado do cliente. * Perda de dados possível em quedas abruptas. * Sem dashboard web integrado – os usuários podem consumir a saída CLI, a API HTTP ou consultar o SQLite diretamente. Licença Apache License 2.0.