开发者导读
给要读代码、改代码、在 evstats 上做定制开发的人：仓库里有什么、各部分用什么写、改一个功能会动到哪些文件，以及建议的阅读顺序。
仓库结构
evstats 是一个单仓库，每个一级目录各管一件事，各自有 README.md 和 AGENTS.md（写给开发者和编码助手的约定）。
| 目录 | 内容 | 语言与工具 |
|---|---|---|
evs-aggr/ | 服务端，二进制 evstats：采集、入库、统计、Agent、OpenAPI、账号与系统管理 | Go 1.26，标准库为主 |
evs-dash/ | 管理界面（Stats 看数与 Agent 问数两种模式），构建产物打进 evstats 二进制 | Vue 3、TypeScript、Vite、Element Plus、ECharts |
evs-docs/ | 官网与用户文档，就是你正在看的站点 | VitePress |
evs-sdks/ | web/、go/、java/ 三端采集 SDK，各自发布 | TypeScript、Go、Java 17 |
evs-test/ | 自动化测试的统一入口，以及官网截图与动图的生成 | Python（uv）、Playwright |
deploy/ | 部署示例：单机、生产环境、多节点、Nginx、systemd，以及本机开发用的 ClickHouse 与 Redis | Docker Compose |
几条贯穿全局的约定
- 统计只有一个实现：服务端
evs-aggr/internal/stat的模块注册表。管理界面的页面、/api/v1的路径、Agent 的工具、看板卡片都从注册表来，改一处，四个出口一起变。 - 契约文件是接口的唯一出处：
evs-aggr/api/openapi.yaml（手写）与go generate生成的openapi.json、modules.json、config-keys.json。仪表盘、官网、测试都对照它们。 - 名字固定：表名前缀
evs_，Redis 键前缀evs:，HTTP 头前缀X-Evstats-，写入密钥前缀evs_wk_，接口密钥前缀evs_。 - 表结构只加不删：
evs-aggr/schema/*.sql是期望的表结构，启动时自动调和，不写迁移脚本。 - 不引入功能开关、授权校验和向作者回传数据的代码；新依赖的许可证只能是 MIT、BSD、Apache-2.0、ISC、MPL-2.0（仅作依赖）、OFL（字体）。
- 改了行为就改文档：用户能感知的变化要同步改官网对应页面，并在 更新日志 里记一笔。
改一个功能会动到哪里
| 想做的事 | 主要改动 | 详见 |
|---|---|---|
| 新增一个统计分析 | internal/stat 注册表与 SQL 模板、api/openapi.yaml、evs-dash/src/modules.ts 与页面、官网看数页 | 新增一个统计模块 |
| 给事件加一个字段 | schema/data.sql、internal/collect 规范化、SDK、官网事件与属性名 | 采集协议与 SDK |
| 加一个系统配置项 | internal/confkeys，go generate 之后配置参考页自动更新 | 代码架构 |
| 改界面或加页面 | evs-dash/src/views、components、locales | 仪表盘开发 |
| 接自己的系统 | 不改代码，用 OpenAPI 或 Agent | OpenAPI |
| 支持新平台上报 | 按 HTTP 协议写一个 SDK | 采集协议与 SDK |
建议的阅读顺序
- 系统架构：组件、数据流、部署形态，先有全局。
- 开发环境：在本机把服务端、管理界面、官网跑起来。
- 代码架构：服务端各个包的职责、启动顺序、一次请求经过哪些代码。
- 新增一个统计模块：最常见的一类改动，从 SQL 到页面走一遍。
- 测试 与 构建与发布：改完怎么验证、怎么出镜像。
参考资料：指标口径、HTTP 协议、API 参考、配置项、错误码。