egoist/tinytraffic

项目介绍

tinytraffic 是面向个人站点的自托管网站分析服务。它以单个 Go 二进制分发，内嵌看板和统计脚本，启动一个进程即可使用，数据全部保存在自己的机器上。默认存储是 DuckDB 文件；流量变大或需要多个进程共用数据库时，可以改用 ClickHouse。

统计脚本 gzip 后约 1 KB，记录页面浏览（含 SPA 路由跳转）、外链点击和自定义事件，并且接受 Plausible 的事件格式，已有的 Plausible 集成可以直接沿用。隐私处理方式是把每日轮换的盐与站点、IP、User-Agent 一起哈希，不写 Cookie，不保存 IP，来源地址会去掉查询串。看板展示访客、访问、浏览量、跳出率和访问时长，以及来源、引荐、页面、地区、设备和目标，点击任意一行即可筛选。公开看板模式允许不登录分享某个站点的数据；带 API Key 的 API 支持读取统计、管理站点和从服务端发送事件。

快速使用

最直接的方式是 Docker：

docker run -d --name tinytraffic -p 8080:8080 -v tinytraffic:/data \
  -e TT_PASSWORD=change-me ghcr.io/egoist/tinytraffic:main

打开 http://localhost:8080，用设置的密码登录，新建站点，然后把生成的片段粘贴到站点 <head> 中：

<script defer data-domain="example.com" src="https://stats.example.com/js/script.js"></script>

把其中的域名和脚本地址换成自己的值。统计脚本的 data-domain、data-api、data-hash 和 data-outbound="false" 属性控制记录行为。

从源码构建需要 Go 1.26+、Bun 1.4+ 和 C 编译器，因为 DuckDB 通过 cgo 链接：

bun install        # 同时获取 GeoIP 数据库
bun run build      # 构建 tracker、看板和 bin/tinytraffic
./bin/tinytraffic  # 在 :8080 启动

配置与部署

运行参数可以用命令行 flag 或 TT_* 环境变量给出：监听地址、数据目录、DuckDB 内存上限、GeoIP MMDB 文件、ClickHouse URL 和 TT_TRUST_PROXY。首次启动时设置 TT_PASSWORD 可以防止别人抢占总初始化页面。放在 TLS 终止的反向代理后面时，应开启 TT_TRUST_PROXY=true 并只暴露代理端口；否则所有访客都会显示为代理 IP，公开看板的访问者还会共用一个限流额度。

GeoIP 数据默认来自 npm 打包的 DB-IP 免费城市库，也可以放入 MaxMind 等其他 .mmdb 文件。要迁移到 ClickHouse，停掉服务后带上目标 URL 运行 tinytraffic migrate-clickhouse，它会复制站点、API Key、设置、盐和事件，可以安全重跑。tinytraffic 面向单个 ClickHouse 服务，不支持集群，表也不会自动复制或分片。

运行约束

使用 DuckDB 时，同一个数据库文件只能被一个进程打开，因此 password、seed 等管理命令需要先停掉服务。这同样影响滚动部署：DuckDB 部署在 Dokploy 和 Docker Swarm 上必须使用 stop-first 更新顺序，而 ClickHouse 可以 start-first。多个进程共用 ClickHouse 时，每个进程各自在内存中维护访问会话，同一访客的请求应落到同一进程，避免重复计算访问。

备份方式是停服后复制数据目录，或用 DuckDB CLI 导出 Parquet；使用 ClickHouse 时应备份其数据库本身。项目采用 AGPL-3.0 许可证。

HotRepo 点评

tinytraffic 在 2026-11-10 进入 HotRepo 新项目榜，约九个半小时内新增 101 个 Star 和 3 个 Fork，而仓库在同一天创建。这只是早期信号：README 中的性能数据（2500 万事件对应 555 MB DuckDB 文件，Apple Silicon 笔记本上 30 天查询 10–100 ms）是作者自己的测量，不代表采用情况。可以确认的是项目范围：单二进制部署、兼容 Plausible 的事件格式，以及有文档的 DuckDB 到 ClickHouse 迁移路径，都让评估这件事不需要先接入托管服务。