构建与发布

怎么在本机构建、版本怎么打、发布流水线产出什么，以及自己定制之后怎么出镜像。

本机构建

make build        # 构建管理界面并嵌入，编译 build/evstats
./build/evstats version

make build-dash 单独构建管理界面并复制到 evs-aggr/internal/httpserver/dist/；go build ./cmd/evstats 会把那里的文件一起打进二进制。

版本号

服务端与管理界面共用一个版本号，遵循 SemVer；SDK 各自有版本。

发布什么	标签	流水线
服务端 + 管理界面	vX.Y.Z	.github/workflows/release.yml
Web SDK	sdk-web/vX.Y.Z	sdk-release.yml：npm 与 GitHub Release
Java SDK	sdk-java/vX.Y.Z	sdk-release.yml：Maven Central
Go SDK	evs-sdks/go/vX.Y.Z	只打标签，由 Go 模块代理拉取

服务端发布产出

打 vX.Y.Z 标签后，流水线先构建管理界面，再用 goreleaser 产出：

• linux/amd64、linux/arm64、darwin/amd64、darwin/arm64、windows/amd64 的二进制压缩包，附 checksums.txt；
• ghcr.io/mosongcc/evstats 与阿里云镜像仓库的多架构镜像，标签 X.Y.Z、X.Y、X、latest；
• 二进制与镜像的 cosign 无密钥签名；
• Release 说明取仓库根 CHANGELOG.md 里对应版本的一节。

镜像分两步构建：先编译二进制，再放进 distroless 的非 root 基础镜像。运行镜像里只有 evstats 一个文件，数据目录 /var/lib/evstats/data 属于非 root 用户。

发版前

1. CHANGELOG.md 写好这个版本的「新增 / 变更 / 修复 / 需要注意」；官网 更新日志 已记录对应的变更。
2. cd evs-test && uv run main.py --case all 全绿；界面有变化时重新生成官网截图。
3. 契约有变化时，确认只增不减（见下一节），官网副本已同步。
4. 在 限制与上限 · 性能 的环境里复测，退化超过 10% 不发布。

兼容承诺

从 1.0 起：采集协议和 /api/v1 只增不减；配置键不改名；环境变量不再增加必填项；任意 1.x 可以直接升级到更新的 1.x。破坏这些的改动只会进 2.0。二次开发时新增字段、新增模块都不破坏这些承诺；删字段、改名、改语义才会。

定制之后出自己的镜像

改了代码想部署到自己的环境，不需要走官方流水线：

cd evs-aggr
docker build --platform linux/amd64,linux/arm64 -t registry.example.com/evstats:1.0.0-custom .

evs-aggr/Dockerfile 的构建上下文是这个目录，一次构建产出 linux/amd64 与 linux/arm64：第一步编译 evstats，第二步用 distroless 启动。管理界面是独立镜像，不在这里构建。可选构建参数 VERSION 会写进 evstats version。推到自己的镜像仓库后，把部署文件里的镜像地址换掉即可，其余部署步骤不变。

官网发布

官网是纯静态站点，.github/workflows/docs.yml 在 evs-docs/** 有变化时构建并跑文档用例，合入 main 后发布。官网给自己埋点用三个构建变量：EVSTATS_DOCS_KEY 为空时不插入统计脚本；设了它就必须同时给出 EVSTATS_DOCS_ENDPOINT（采集地址）和 EVSTATS_DOCS_SDK（Web SDK 脚本的地址），否则构建失败。缓存规则见 evs-docs/README.md。