theia

Theia – Análisis server-side centrado en la privacidad Resumen Theia proporciona estadísticas de tráfico web sin ningún JavaScript del lado del cliente. Observa los logs de acceso de nginx en tiempo real, analiza cada línea para extraer ruta, referrer, user-agent, IP, código de estado y bytes enviados, cifra las IPs por privacidad y almacena los resultados en una base de datos SQLite local. Dado que todo el procesamiento ocurre en el servidor, los datos son inmunes a ad-blockers y no dependen de servicios de terceros. Instalación Instalación rápida: descarga el script de instalación con curl o wget y ejecútalo con sudo bash. El script detecta la arquitectura, instala el binario en /usr/local/bin/theia, añade un formato de log personalizado de nginx para el seguimiento multi-dominio (opcional), crea un servicio systemd y prepara /var/lib/theia para el almacenamiento de datos. También se admite la instalación manual: clona el repositorio, compila con go build, copia el binario, crea el directorio de datos e instala la unidad systemd proporcionada. Ejecutar el daemon El daemon sigue el log de acceso de nginx y escribe registros analizados en la base de datos SQLite. Ejemplo de comando: sudo theia daemon --log-path /var/log/nginx/access.log --db-path /var/lib/theia/theia.db Flags principales: --log-path (valor por defecto /var/log/nginx/access.log) y --db-path (valor por defecto ./theia.db). Estadísticas por línea de comandos El subcomando stats lee la base de datos e imprime una tabla resumen o salida JSON. Uso típico: theia stats --db-path /var/lib/theia/theia.db Las opciones permiten cambiar el período de consulta (--days), filtrar por host (--host), elegir el formato de salida (--format json|table) y ajustar el número de entradas principales (--top). Servicio HTTP API El comando serve inicia una API HTTP/JSON (o CSV) protegida con token bearer en 127.0.0.1:8081. Puedearse a través de nginx para exponerla externamente. La autenticación puede suministrarse mediante un archivo de token, una variable de entorno o un flag de línea de comandos. Los endpoints incluyen: GET /api/v1/stats – datos de serie temporal GET /api/v1/stats/paths – rutas más visitadas GET /api/v1/stats/referrers – referrers principales GET /api/v1/stats/status-codes – desglose de códigos de estado Parámetros comunes de consulta: host, from, to, format, group_by, top. Completado de shell Ejecutar theia completion detecta el shell actual y ofrece instalar scripts de completado para bash, zsh o fish. Gestión del servicio Theia se ejecuta como una unidad systemd. Usa los comandos systemctl estándar para iniciar, detener, reiniciar, ver el estado y seguir los logs. Funcionamiento interno 1. Seguimiento en tiempo real del archivo de log de nginx. 2. Análisis de cada línea para obtener los campos relevantes. 3. Cifrado de IP + user-agent + fecha para preservar el anonimato. 4. Detección automática de bots y solicitudes de activos estáticos. 5. Escritura asíncrona de registros en SQLite (modo WAL) permitiendo lecturas concurrentes. 6. Limpieza periódica elimina estadísticas horarias anteriores a 60 días. Consideraciones de seguridad El daemon necesita acceso root o sudo para leer los logs de nginx. El token de la API debe almacenarse en un archivo en lugar de en la línea de comandos para evitar su exposición a través de la lista de procesos. Se recomienda limitar la tasa de peticiones y reglas de fail2ban para escáneres ruidosos (ver docs/nginx-hardening.md). Limitaciones * Solo se recopilan conteos de páginas vistas; no hay eventos del lado del cliente. * Posible pérdida de datos ante cierres abruptos. * Sin dashboard web integrado: los usuarios pueden consumir la salida CLI, la API HTTP o consultar SQLite directamente. Licencia Apache License 2.0.