theia

Theia – 隐私优先的服务器端分析 概述 Theia 提供网站流量统计，无需任何客户端 JavaScript。它实时监控 nginx 访问日志，解析每行以提取路径、来源、用户代理、IP、状态码和发送的字节数，对 IP 进行哈希以保护隐私，并将结果存储在本地 SQLite 数据库中。由于所有处理都在服务器端进行，数据免受广告拦截器的影响，也不依赖第三方服务。 安装 快速安装：使用 curl 或 wget 下载安装脚本，然后用 sudo bash 运行。脚本会检测架构，将二进制文件安装到 /usr/local/bin/theia，添加自定义的 nginx 日志格式以实现多域跟踪（可选），创建 systemd 服务并准备 /var/lib/theia 用于数据存储。也支持手动安装——克隆仓库，使用 go build 编译，复制二进制文件，创建数据目录并安装提供的 systemd 单元。 运行守护进程 守护进程会跟踪 nginx 访问日志并将解析后的记录写入 SQLite 数据库。 示例命令： sudo theia daemon --log-path /var/log/nginx/access.log --db-path /var/lib/theia/theia.db 关键标志：--log-path（默认 /var/log/nginx/access.log）和 --db-path（默认 ./theia.db）。 命令行统计 stats 子命令读取数据库并打印摘要表或 JSON 输出。 典型用法： theia stats --db-path /var/lib/theia/theia.db 选项允许更改回溯时期（--days），按主机过滤（--host），选择输出格式（--format json|table）以及调整顶部条目数量（--top）。 HTTP API 服务 serve 命令在 127.0.0.1:8081 启动 bearer‑token 保护的 HTTP/JSON（或 CSV）API。可以通过 nginx 代理以对外暴露。身份验证可以通过令牌文件、环境变量或命令行标志提供。端点包括： GET /api/v1/stats – 时间序列数据 GET /api/v1/stats/paths – 热门路径 GET /api/v1/stats/referrers – 热门来源 GET /api/v1/stats/status-codes – 状态码分布 常见查询参数：host, from, to, format, group_by, top。 Shell 自动补全 运行 theia completion 会检测当前 shell 并提供安装 bash、zsh 或 fish 的补全脚本。 服务管理 Theia 作为 systemd 单元运行。使用标准的 systemctl 命令启动、停止、重启、查看状态和跟踪日志。 内部工作原理 1. 实时跟踪 nginx 日志文件。 2. 解析每行以提取相关字段。 3. 对 IP + 用户代理 + 日期进行哈希以保持匿名。 4. 自动检测机器人和静态资源请求。 5. 以异步方式将记录写入 SQLite（WAL 模式），允许并发读取。 6. 定期清理删除超过 60 天的小时统计。 安全注意事项 守护进程需要 root 或 sudo 权限才能读取 nginx 日志。API 令牌应存储在文件中而非命令行，以避免通过进程列表泄露。建议使用速率限制和 fail2ban 规则来应对噪声扫描器（参见 docs/nginx-hardening.md）。 局限性 * 仅收集页面浏览次数；不收集客户端事件。 * 在突然崩溃时可能出现数据丢失。 * 没有内置的 Web 仪表盘——用户可以通过 CLI 输出、HTTP API 或直接查询 SQLite 来消费数据。 许可证 Apache License 2.0。