evstats

外观

在线演示源码

系统架构 ​

evstats 由一个二进制加上 ClickHouse 和 Redis 组成。这一页讲清组件分工、一条事件和一次查询各自怎么走、请求落在哪里，以及从单机到多节点的几种部署形态。

evstats 系统架构 网站、服务端、App、邮件通过 SDK、HTTP 协议或像素把事件发到 evstats 的采集接口；采集接口把事件写进 Redis 队列， 入库程序按消费组取出、攒批写进 ClickHouse，写入成功才确认。统计内核只有一个，查询 ClickHouse，结果缓存在 Redis， 管理界面、Agent、OpenAPI 三个出口都调用它。运营和分析人员用浏览器看数，Agent 调用你配置的兼容 OpenAI 接口的模型， 业务系统和外部 Agent 用接口密钥调用 OpenAPI。ClickHouse 的 s0 存系统数据和事件，更多分片只存事件与聚合。 数据从哪来谁在用数网站Web SDK服务端Go / Java SDKApp · 小程序HTTP 协议邮件像素↙ 上报 POST /sa（写入密钥）运营与分析浏览器 · 登录会话看数你选的模型兼容 OpenAI 接口调用模型业务系统外部 Agent · 接口密钥取数evstats · 一个二进制，可以多台，前面放负载均衡采集接口校验 · 过滤 · 规范化入库按分片攒批 · IP 解析统计内核 stat唯一口径 · 结果缓存管理界面/dashAgent/dash/agentOpenAPI/api/v1三个出口调用同一个查询，命中同一份缓存Redis（所有进程共用一个）采集队列 · 登录会话 · 限流 · 结果缓存ClickHouse s0（-clickhouse）账号 · 项目 · 配置 · 事件与聚合更多分片 s1、s2 …只放事件与聚合 · 在设置页追加写进队列才回复成功消费组取出写入成功才确认按项目的分片查询

组件 ​

组件职责数量
evstats采集、入库、统计、Agent、OpenAPI，管理界面的静态资源也打在二进制里一个或多台，前面放负载均衡，不需要会话粘滞
ClickHouse s0EVS_CLICKHOUSE（或 -clickhouse）指向的库：账号、角色、项目、配置、看板、操作日志等系统数据，以及落在 s0 上的项目的事件一个
ClickHouse 分片在「系统 → 分片」里追加的 s1、s2……只放事件与聚合零个或多个
Redis采集队列（Redis Stream）、登录会话、限流、验证码、查询结果缓存、配置变更通知一个，所有进程共用
SDKWeb、Go、Java 三端，把事件批量发到 POST /sa按需

没有第二个数据库，没有消息中间件，也没有单独的前端服务。进程只认三个启动设置：推荐环境变量 EVS_CLICKHOUSE、EVS_REDIS、EVS_PORT，同名启动参数写了就覆盖，都有默认值。监听对所有网卡开放。管理员、AI、IP 库在第一次打开网页时填写。

一条事件怎么走 ​

  1. SDK 生成事件 ID（messageId），攒成一批，带着写入密钥 POST /sa。
  2. 任意一台 evstats 收到后，用内存里的项目表核对写入密钥、采集开关、请求大小、域名名单、爬虫和排除 IP，规范化字段。
  3. 合法的事件写进 Redis 的采集队列，写入成功才回复 SDK 成功。被过滤的事件按原因计数，接入检查里能看到。
  4. 所有进程在同一个消费组里取消息，解析 IP 和 User-Agent，按项目所在的分片凑批，插入 ClickHouse 的 evs_event，插入成功才确认（ACK）。
  5. ClickHouse 的物化视图随插入维护日聚合、维度聚合、首次出现、点击格子和触点表。
  6. 被 ClickHouse 拒绝的单条事件转进失败事件表，不会堵住队列。

某台进程在确认之前崩溃，它没确认的消息空闲一段时间后由其它进程接着写，已经回复成功的事件不会丢。代价是重试时可能出现少量重复行。

一次查询怎么走 ​

一套数，三个出口 Stats 仪表盘、Agent 问数、OpenAPI 三路都调用同一个 stat 查询内核，内核查询 ClickHouse，结果放在 Redis 缓存里，三路命中同一份缓存。 Stats 仪表盘/dash/statsAgent 问数查询工具OpenAPI/api/v1stat 查询内核同一份口径ClickHouseRedis 结果缓存三路命中同一条

统计只有一个实现：内核里的模块注册表。一个模块（例如 funnel）同时是管理界面的页面、/api/v1 的路径、Agent 的工具、看板卡片的类型，参数名和返回形状在几处完全相同。

  1. 请求带着项目、日期和参数进来，内核先校验权限和参数，再读出项目所在的分片。
  2. 没有属性筛选时，PV、UV、排行读预先聚合好的表；有筛选或需要明细时查 evs_event。每条 SQL 都带项目和日期范围，只扫需要的分区。
  3. 结果按「模块 + 参数」存进 Redis 缓存，管理界面、Agent、OpenAPI 命中同一条缓存，所以三处的数字对得上。

口径（UV 怎么去重、会话怎么切、跳出怎么算）写在 指标口径。

请求落在哪 ​

路径谁调用鉴权
POST /sa、GET /sa.gifSDK、像素项目的写入密钥 evs_wk_xxx
GET /sdk/config、POST /replayWeb SDK写入密钥
GET /sdk/heatmap叠加在网页上的热力图一次性令牌
/dash/**管理界面（看数、Agent、看板、设置）登录后的 HttpOnly Cookie
/api/v1/**业务系统、外部 Agent用户的接口密钥 evs_xxx，Authorization: Bearer
GET /openapi.json文档、代码生成无
GET /health、GET /metrics负载均衡、监控无；/metrics 只对内网开放
其余路径浏览器管理界面的静态资源

写入密钥只能写、不能读，出现在网页源码里是正常的；接口密钥能读数据，属于人，权限跟着这个人在后台能看的项目走。两把钥匙不能互换。

数据存在哪 ​

表内容保留
evs_event全部事件明细，按项目、日期、事件排序，按天分区项目的保留天数，默认 365 天
evs_agg_*日聚合、维度聚合、首次出现按系统配置
evs_click、evs_attr_*热力图格子、首次与末次触点按系统配置
evs_replay会话回放的分块replay.retain_days
evs_user、evs_project、evs_config 等系统数据，只在 s0长期

表结构写在程序里，进程启动时对照调和：缺表建表、缺列加列、视图定义变了就重建，改了什么记在「关于」页。升级不需要人去执行迁移脚本，见 升级。

部署形态 ​

形态机器适合
单机一台机器上用 Compose 跑 ClickHouse、Redis、evstats体验、测试环境、小流量站点
生产环境ClickHouse、Redis、evstats 各自一台服务器，evstats 前面放 Nginx 终止 HTTPS正式上线的推荐形态
多节点与分片多台 evstats 共用一个 Redis；ClickHouse 追加分片，新项目落到项目数少的分片流量或项目数上来之后

三种形态用的是同一个程序、同一组环境变量，从单机换到生产环境、再到多节点，不需要换架构。步骤见 部署总览、生产环境部署、多节点与分片。

安全边界 ​

  • 访客 IP 用离线的 ip2region 库在本机解析，不发给任何第三方；程序不向作者回传任何数据。
  • 登录会话在 Redis，Cookie 是 HttpOnly，全集群即时失效；接口密钥在服务端只存 SHA-256。写入密钥校验用 SHA-256，原文单独存一份，只有管理员输入登录密码后才能看到，不进缓存、日志和列表接口。
  • Agent 调用的是你配置的模型；模型只拿到查询结果，拿不到会话回放的正文，也改不了项目。
  • 自定义 SQL 只给管理员，只能读当前项目的事件表与聚合表。

完整的安全说明见 安全与隐私。

某个组件出问题时 ​

组件影响
一台 evstats负载均衡把请求转给其它进程；它没确认的事件由其它进程接着写
Redis登录和采集暂停，SDK 把事件留在本地队列重试；已经写进 ClickHouse 的数据不受影响
某个分片只有落在它上面的项目查询失败；采集照常进队列，恢复后自动写入
s0系统数据不可用，管理界面和查询不可用；恢复后照常

排障步骤见 运维与排障。二次开发时各模块在代码里的位置见 代码架构。