# evstats

**Repository Path**: mosongcc/evstats

## Basic Information

- **Project Name**: evstats
- **Description**: evstats
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="evs-docs/src/public/brand/logo-dark.svg">
  <img alt="evstats 标识：松树、上扬的趋势线与一笔圆" src="evs-docs/src/public/brand/logo.svg" width="120">
</picture>

# evstats

**自己部署的事件统计**。SDK 采集，管理界面看数，用中文问 Agent，用 OpenAPI 取数——四处是同一套数，全部存在你自己的 ClickHouse 里。

中文 · [English](README.en.md) · [官网](https://evstats.mosong.cc) · [快速体验](https://evstats.mosong.cc/zh/deploy/quickstart) · [生产部署](https://evstats.mosong.cc/zh/deploy/production) · [在线演示](https://evstats-dash-demo.mosong.cc) · [API 参考](https://evstats.mosong.cc/zh/api/)

![evstats 管理界面：概览、趋势、来源、漏斗、留存、热力图，最后把热力图叠加到真实页面上](evs-docs/src/public/demo/stats.gif)

evstats（墨松事件统计）把页面浏览和业务事件存进你自己的 ClickHouse：流量、页面、用户、事件、行为五组分析，看板，热力图、会话回放、归因、A/B 实验，会查表的 Agent 和只读的 OpenAPI，全部在同一个开源版本里，没有授权开关。

> 本页的动图与截图都是真实界面，数据是自动化测试生成的示例数据。

## 四种用法

### 管理界面看数

流量、页面、用户、事件、行为五组，三十多个分析页。日期、对比、筛选都写在地址栏里；每张图都能切成表、导出 CSV、加入看板；指标名旁边写着口径。

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="evs-docs/src/public/screenshots/dark/overview.webp">
  <img alt="evstats 数据概览" src="evs-docs/src/public/screenshots/light/overview.webp">
</picture>

### Agent 对话问数

用中文提问，模型只调用和图表相同的统计查询，不写 SQL。每次查询在对话里是一张卡片，点「在 Stats 打开」就是同一张图。兼容 OpenAI Chat Completions 接口，模型自己选。

![Agent 问数：提问、查询卡片、回答、在 Stats 打开](evs-docs/src/public/demo/agent.gif)

### OpenAPI 取数

只读的 `/api/v1`，OpenAPI 3.0.3 契约。参数和返回与管理界面完全一样，命中同一份缓存；接口密钥属于人，权限跟着他在后台能看的项目走。

![用 curl 调用 OpenAPI，返回与数据概览同一个查询的结果](evs-docs/src/public/demo/openapi.gif)

### SDK 采集

Web、Go、Java 三端 SDK，其它平台按 HTTP 协议直接发。页面浏览、点击、停留自动采集，业务事件自己埋；接入检查实时显示收到了什么、丢了多少、为什么。

![两行代码接入，在网站上点几下，接入检查里实时出现这些事件](evs-docs/src/public/demo/collect.gif)

## 专业的统计分析

| | | |
| --- | --- | --- |
| **埋点采集**：全埋点 + 自定义事件，事件日志逐条可查 | **流量与来源**：来源网站、渠道（UTM）、搜索词、地域、设备 | **实时访问**：最近 15～180 分钟的分钟曲线 |
| **事件统计**：次数、人数、人均，按维度或属性拆分 | **漏斗**：2～8 步有序漏斗，窗口可调 | **留存**：起始事件与回访事件自选，按日或周 |
| **路径**：做完一件事之后最常见的下一步 | **用户画像**：触点、终端、按会话分组的时间线 | **热力图**：点击与停留，叠加在你自己的网页上 |
| **会话回放**：按比例抽样，默认遮住输入框 | **归因**：首次、末次、线性三种模型 | **A/B 实验**：本地分流，z 检验给出是否显著 |

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="evs-docs/src/public/screenshots/dark/heatmap-overlay.webp">
  <img alt="热力图叠加在网页上" src="evs-docs/src/public/screenshots/light/heatmap-overlay.webp">
</picture>

完整的功能清单见 [功能全景](https://evstats.mosong.cc/zh/product/features)，全部界面见 [界面一览](https://evstats.mosong.cc/zh/product/tour)。

## 架构

```mermaid
flowchart LR
  src["网站 · 服务端 · App<br/>Web / Go / Java SDK、HTTP 协议"] -->|POST /sa| collect
  subgraph evstats["evstats：一个二进制，可以多台"]
    collect["采集接口"]
    ingest["入库：按分片攒批"]
    kernel["统计内核 stat<br/>唯一口径 · 结果缓存"]
    dash["管理界面 /dash"]
    agent["Agent 问数"]
    api["OpenAPI /api/v1"]
    kernel --> dash
    kernel --> agent
    kernel --> api
  end
  collect -->|写进队列才回复成功| redis[("Redis<br/>采集队列 · 会话 · 缓存")]
  redis -->|消费组取出| ingest
  ingest -->|写入成功才确认| ch[("ClickHouse<br/>s0 + 分片")]
  kernel -->|按项目的分片查询| ch
  dash --> people["运营与分析"]
  agent --> llm["你选的模型<br/>兼容 OpenAI 接口"]
  api --> biz["业务系统 · 外部 Agent"]
```

| 部分 | 说明 |
| --- | --- |
| `evstats` | 一个二进制：采集、入库、统计、Agent、OpenAPI，管理界面打在里面。镜像 `ghcr.io/mosongcc/evstats` |
| ClickHouse | 事件、聚合、账号、项目、配置，全部在这里；流量大了在设置页追加分片 |
| Redis | 采集队列、会话、限流、结果缓存，多台进程共用一个 |
| SDK | [Web](evs-sdks/web)（`@evstats/web`）、[Go](evs-sdks/go)、[Java](evs-sdks/java)；其它平台按 [HTTP 协议](https://evstats.mosong.cc/zh/sdk/http) 上报 |

详见 [系统架构](https://evstats.mosong.cc/zh/product/architecture)。

## 安装使用

### 快速体验：一台机器

一台 2 核 4GB 以上、装好 Docker 的机器：

```bash
curl -fsSLO https://evstats.mosong.cc/deploy/compose/compose.yaml
# 把文件里的 change-me 换成你自己的口令（ClickHouse 的几处一致，Redis 的几处一致）
docker compose up -d
```

浏览器打开 `http://你的主机:51321/`：创建管理员，再创建项目，把页面给出的 Web SDK 片段放进网页：

```html
<script src="https://unpkg.com/@evstats/web/dist/evstats.min.js"></script>
<script>evstats.init({ endpoint: "http://你的主机/sa", key: "evs_wk_xxx" })</script>
```

打开项目的「接入」页签就能看到第一条事件。完整步骤见 [快速体验](https://evstats.mosong.cc/zh/deploy/quickstart)。

### 生产环境：三类服务器分开

正式上线建议 ClickHouse、Redis、evstats 各用一台服务器，evstats 前面放 Nginx 终止 HTTPS。每台一份 Compose 文件，在 [deploy/production/](deploy/production)：

| 服务器 | 文件 | 对谁开放 |
| --- | --- | --- |
| ClickHouse | `deploy/production/clickhouse/` | 8123 只对 evstats 服务器 |
| Redis | `deploy/production/redis/` | 6379 只对 evstats 服务器 |
| evstats（可以多台） | `deploy/production/evstats/` + `deploy/nginx/evstats.conf` | 443 对公网 |

每台机器的命令、防火墙、HTTPS、上线核对清单见 [生产环境部署](https://evstats.mosong.cc/zh/deploy/production)。

## 文档

| 你是 | 从这里开始 |
| --- | --- |
| 做产品调研 | [产品概览](https://evstats.mosong.cc/zh/product/) · [功能全景](https://evstats.mosong.cc/zh/product/features) · [为什么是 evstats](https://evstats.mosong.cc/zh/product/why) |
| 部署运维 | [部署总览](https://evstats.mosong.cc/zh/deploy/) · [生产环境部署](https://evstats.mosong.cc/zh/deploy/production) · [运维与排障](https://evstats.mosong.cc/zh/deploy/operations) |
| 接入与使用 | [使用指南](https://evstats.mosong.cc/zh/guide/) · [接入概览](https://evstats.mosong.cc/zh/guide/collect) · [Agent 问数](https://evstats.mosong.cc/zh/guide/agent) |
| 二次开发 | [开发者导读](https://evstats.mosong.cc/zh/dev/) · [代码架构](https://evstats.mosong.cc/zh/dev/architecture) · [新增一个统计模块](https://evstats.mosong.cc/zh/dev/module) |

## 承诺

- **完全开源**：服务端、仪表盘、三端 SDK、官网，全部 Apache-2.0。
- **没有功能开关**：不存在社区版、专业版、企业版，不做授权服务器。
- **不做官方 SaaS**：只提供自己部署的软件。
- **不回传数据**：程序不向作者发送任何数据；自监控埋点默认关闭，只发到管理员自己填的地址。
- **收费只针对人工**：交流群、咨询、代运维是服务，不影响任何功能。

从 v1.0 起：采集协议和 `/api/v1` 只增不减；配置键不改名；环境变量不再增加必填项；任意 1.x 可以直接升到更新的 1.x。破坏这些只会发生在 2.0。

## 仓库

| 目录 | 内容 |
| --- | --- |
| [evs-aggr](evs-aggr) | Go 服务端，二进制 `evstats` |
| [evs-dash](evs-dash) | Vue 仪表盘 |
| [evs-docs](evs-docs) | 官网与用户文档（VitePress） |
| [evs-sdks](evs-sdks) | Web、Go、Java SDK |
| [evs-test](evs-test) | 自动化测试入口（Python，uv）与官网截图、动图的生成 |
| [deploy](deploy) | 单机、生产环境、多节点 Compose，Nginx、systemd，以及本机开发环境 |

## 参与

- 缺陷、建议、提问：[Issue](https://github.com/mosongcc/evstats/issues/new/choose)；使用经验：[Discussions](https://github.com/mosongcc/evstats/discussions)
- 贡献代码：[CONTRIBUTING.md](CONTRIBUTING.md)，行为准则：[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- 安全漏洞：按 [SECURITY.md](SECURITY.md) 私下报告
- 更新日志：[官网更新日志](https://evstats.mosong.cc/zh/change/)（按月）、[CHANGELOG.md](CHANGELOG.md)（按版本）

## 许可证

[Apache License 2.0](LICENSE)。再分发时请保留 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。