开发环境

在本机把 evstats 跑起来：起一套开发用的 ClickHouse 与 Redis，运行服务端，打开管理界面的开发服务器，需要时再跑官网和 SDK。

需要的工具

工具	版本	用在哪
Git		拉代码
Docker	带 Compose v2	本机的 ClickHouse 与 Redis
Go	服务端 1.26（以 evs-aggr/go.mod 为准），Go SDK 1.22	服务端、Go SDK
Node	22	管理界面、官网、Web SDK
Yarn	1.x	Node 项目的包管理，安装用 yarn install；yarn.lock 等锁文件不提交
uv	最新	自动化测试 evs-test
JDK	17 及以上	只在改 Java SDK 时需要
ffmpeg		只在重新生成官网动图时需要

Go、Node 与 Yarn、JDK 的版本以仓库里的文件为准：evs-aggr/go.mod 的 toolchain、package.json 的 engines.node、evs-sdks/java/pom.xml 的 maven.compiler.release。自动化测试入口 evs-test 启动前按这些文件检查，本机版本不符时自动下载到 ~/sdk，只给这次运行用，不改系统设置。手工运行 go run、yarn dev 前，可以先让当前终端用上同样的版本：

eval "$(cd evs-test && uv run python -m lib.toolchain go node)"

1. 拉代码，起 ClickHouse 与 Redis

git clone https://github.com/mosongcc/evstats.git
cd evstats
docker compose -f deploy/dev/compose.yaml up -d --wait

deploy/dev/compose.yaml 起单节点 ClickHouse 24.8 和 Redis 7，端口只绑 127.0.0.1（8123、6379），口令都是 evstats-dev，只能用于本机开发。

用途	ClickHouse 库	Redis 库
手工开发	evstats	0 号
自动测试	evstats_test（及 evstats_test_*）	1 号

自动测试会清空测试库，不会碰手工开发的数据。make dev-down 停掉容器，make dev-reset 连数据一起删掉。

2. 运行服务端

cd evs-aggr
EVS_CLICKHOUSE='http://evstats:evstats-dev@127.0.0.1:8123/evstats' \
EVS_REDIS='redis://:evstats-dev@127.0.0.1:6379/0' \
  go run ./cmd/evstats

不写 EVS_CLICKHOUSE 时用 http://evstats:evstats@127.0.0.1:8123/evstats（账号、口令、库名都是 evstats），不写 EVS_PORT 时听 51321 并对所有网卡开放，不写 EVS_REDIS 时连 redis://127.0.0.1:6379/0（无口令）。同名启动参数 -clickhouse、-redis、-port 写了就覆盖环境变量。上面的开发用 Compose 口令是 evstats-dev，所以这里要带上 ClickHouse 和 Redis。要换端口时设置 EVS_PORT。服务端第一次启动会在 evstats 库里建好全部表。浏览器打开 http://127.0.0.1:51321/ 创建管理员。

go run 起的服务端用的是 internal/httpserver/dist/ 里已经构建好的管理界面；刚拉下来的代码里这个目录是空的，页面只显示一行「仪表盘未嵌入，请用 yarn dev 访问 51322」。改前端时用下一步的开发服务器，不需要每次构建。

3. 运行管理界面的开发服务器

cd evs-dash
yarn install
yarn dev            # http://localhost:51322

开发服务器只代理以 /ENV_EVS_API_BASE_URL 开头的请求，去掉这个前缀后转到 http://127.0.0.1:51321，所以要先按上一步启动服务端。改了 Vue 文件会热更新。

4. 构建一个完整的二进制

make build          # 在仓库根：构建管理界面、放进 evs-aggr/internal/httpserver/dist/、编译 build/evstats
./build/evstats

5. 往本机实例里发数据

最快的办法是在项目的「接入」页签复制 Web SDK 片段，放进任意一个本地网页；也可以直接用 HTTP 协议发：

curl -sS http://127.0.0.1:51321/sa \
  -H 'Authorization: Basic '"$(printf 'evs_wk_xxx:' | base64)" \
  -H 'Content-Type: application/json' \
  -H 'X-Evstats-Debug: 1' \
  -d '{"batch":[{"type":"page","messageId":"00000000-0000-4000-8000-000000000001","anonymousId":"dev-user","context":{"page":{"url":"http://localhost/pricing","path":"/pricing"}}}]}'

X-Evstats-Debug: 1 会回显规范化之后的事件，方便对字段。压测用 evs-aggr/bench：go run ./bench -url http://127.0.0.1:51321/sa -key evs_wk_xxx -rate 200 -duration 30s。

6. 运行官网

cd evs-docs
yarn install
yarn dev            # http://localhost:51320

官网是独立项目，不依赖服务端运行。

7. 跑测试

cd evs-test
uv run main.py --list              # 全部用例
uv run main.py --case unit         # 不连库的单元测试与静态检查
uv run main.py --case T-Q23        # 一个接口用例
uv run main.py --case T-S          # 管理界面的浏览器场景

详见 测试。

常见问题

go run 先下载了一个 Go：evs-aggr/go.mod 锁定了 toolchain，本机 Go 版本不符时 go 命令会按它自动下载，这是预期的。不要设 GOTOOLCHAIN=local，否则会用本机的旧版本编译失败；下载慢时设置 GOPROXY。

compile: version "go1.x" does not match go tool version：环境变量 GOROOT 指向了另一个版本的 Go。去掉 GOROOT（新版本的 Go 不需要设置）；evs-test 入口和 Makefile 都不使用外面传进来的 GOROOT。

页面只有一行「仪表盘未嵌入」：用 yarn dev 的 51322 端口访问，或先在仓库根执行 make build-dash。

ClickHouse 起不来：Docker Desktop 给的内存太少时 ClickHouse 会退出，至少分给 Docker 4GB。