核心概念
用 evstats 之前值得先弄清的几个名词：项目、两把钥匙、两种模式、模块、看板、分片和时区。
项目
项目是一套独立的事件空间。一个网站、一个 App 或一组服务，通常对应一个项目。每个项目有：
| 属性 | 说明 |
|---|---|
| 名称 | 显示用，随时可改 |
标识 project_code | 小写字母开头的短名（[a-z][a-z0-9_-]{1,31}），创建后不能改，删除后也不能再用。给人看、给支持用，SDK 不靠它鉴权 |
| 时区 | 创建时选定，之后不能改。事件入库时就按它算好日期 |
| 写入密钥 | 上报凭证，见下一节 |
| 保留天数 | 明细保留多久，默认 365 天 |
| 分片 | 事件存在哪个 ClickHouse 上，创建时自动选定 |
不同项目的数据互不相通，不能放在同一张图里对比。
两把钥匙
| 写入密钥 | 接口密钥 | |
|---|---|---|
| 样子 | evs_wk_xxx | evs_xxx |
| 发给谁 | 项目，创建项目时生成 | 用户，一个人最多 10 把 |
| 用在哪 | SDK 上报 /sa | 调用 OpenAPI /api/v1，Authorization: Bearer |
| 能做什么 | 只能给这个项目写事件 | 只读，能看的项目和这个人在后台能看的一样 |
| 保存 | 校验用 SHA-256；管理员输入登录密码可以再看完整密钥 | 服务端只存 SHA-256，创建时只显示一次 |
写入密钥会出现在网页源码里，这是正常的：它只能写，不能读。接口密钥能读数据，不要放进前端代码、仓库和截图。两把钥匙不能互换：写入密钥调 OpenAPI 一律 40101，接口密钥也不能用来上报。
Stats 与 Agent
工作台有两种模式，顶栏切换，项目和日期保持不动。
- Stats（数据看板）：分析菜单、图表、表格、看板。
- Agent：用中文提问，模型调用和 Stats 相同的查询，每次查询在对话里是一张卡片。
模块
「模块」是一个统计查询的名字，例如 overview（数据概览）、funnel（漏斗）、retention（留存）。同一个模块贯穿所有出口：
| 出口 | 例子 |
|---|---|
| 仪表盘页面 | /stat/funnel |
| OpenAPI | GET /api/v1/projects/{projectId}/funnel |
| Agent 工具 | funnel |
| 看板卡片、书签 | module: "funnel" |
参数名在这几处完全相同，返回的数据形状也相同。所以三处的数字对得上，也命中同一份结果缓存。
看板与书签
看板是你自己组合的一页卡片，每张卡片是「一个模块 + 参数」，打开时按当时的数据重新查询。书签保存一整页的查询条件。两者都不保存数字。见 看板与书签。
分片
分片是存放事件的 ClickHouse。EVS_CLICKHOUSE（或启动参数 -clickhouse）指向的那一台叫 s0，同时存放账号、配置等系统数据。更多分片在「系统 → 分片」里追加。
- 新建项目时，自动落到当前项目数最少的分片，之后固定不变。
- 一个项目的全部事件都在一个分片上，UV、漏斗、留存都在分片内算完，不跨库合并。
- 追加分片只影响之后新建的项目，已有项目不会自动搬走。
小规模部署只有 s0 一个分片，不用关心这些。见 多节点与分片。
时区与日期
- 日期按项目时区算。
from、to都是YYYY-MM-DD，包含首尾两天。一周从周一开始。 - 顶栏写明当前项目的时区，避免把 UTC 当成当地日期。
- 时区创建后不能改：事件入库时已经按它算好日期，改了会让新旧数据的日期边界对不上。
distinct_id：谁是「一个人」
有登录用户 ID（SDK 里 identify 过）时，distinct_id 就是用户 ID；否则是浏览器里的匿名 ID。登录前的匿名浏览不会自动并进登录后的人，UV 按 distinct_id 去重。见 接入概览。