部署总览

先选部署方式，再按对应的页面一步步做。这一页列出各种方式的区别、要准备的东西、端口、环境变量、镜像版本和资源建议。

选一种方式

方式	机器	适合	步骤
快速体验	一台机器，Docker Compose 跑 ClickHouse、Redis、`evstats`	先看看、测试环境、小流量站点	快速体验
生产环境	ClickHouse、Redis、`evstats` 各一台服务器，`evstats` 前面放 Nginx 终止 HTTPS	正式上线，推荐	生产环境部署
二进制	不用容器，`evstats` 用 systemd 管理；ClickHouse 与 Redis 按官方文档安装	不方便装 Docker 的机器	二进制与 systemd
多节点与分片	多台 `evstats` 共用一个 Redis，ClickHouse 追加分片	流量或项目数上来之后	多节点与分片

几种方式用的是同一个程序、同一组环境变量，之后从单机换到独立服务器、再加节点，都不需要换架构。无论哪种方式，装好后都要在浏览器里走一遍首次引导。

要准备什么

项	要求
操作系统	Linux（amd64 或 arm64）。二进制另有 macOS 与 Windows 版本，只建议用于开发
Docker	带 Compose v2，`docker compose version` 能输出版本
ClickHouse	24.8 及以上，用 HTTP 接口（8123）
Redis	7，打开 AOF
域名与证书	放到公网时需要，例如 `stats.example.com`
发信	可选。找回密码需要 SMTP，没有也能用
模型	可选。Agent 问数需要一个兼容 OpenAI 接口的模型服务

端口与网络

端口	谁监听	对谁开放
443 / 80	Nginx（或 `evstats` 本身）	公网：浏览器、SDK、调用 OpenAPI 的系统
51321	`evstats`	快速体验时对宿主机开放；前面有 Nginx 时只映射到本机
8123	ClickHouse	只对 `evstats` 服务器开放
6379	Redis	只对 `evstats` 服务器开放

不要把 ClickHouse 和 Redis 暴露到公网

示例配置都没有把 8123、9000、6379 映射到公网。生产环境里它们只绑内网地址，防火墙只放行 evstats 服务器。

evstats 需要访问的外部地址只有你配置的几个：IP 库的下载地址（只下载一次）、SMTP、模型服务。它不向作者回传任何数据。

镜像与版本

渠道	地址
GitHub Container Registry	`ghcr.io/mosongcc/evstats`
阿里云（国内）	`registry.cn-hangzhou.aliyuncs.com/mosongcc/evstats`

标签有 X.Y.Z、X.Y、X 和 latest，支持 linux/amd64 与 linux/arm64。示例里用 :1，跟随 1.x 的最新版本；生产环境可以钉到 X.Y.Z。镜像基于 distroless，以非 root 运行，没有 shell 和 curl。二进制在 GitHub Release 发布，见二进制与 systemd。升级方法见升级。

启动参数

三个设置都可以不写，不写就用默认值。推荐用环境变量。启动参数写了且非空时覆盖同名环境变量；空字符串视为没写。环境变量名是 EVS_ 加上参数名的全大写。以后新增的启动参数也按这个命名。旧名 EVSTATS_CH、EVSTATS_REDIS、EVSTATS_PORT、EVSTATS_HTTP_ADDR 不读取。

text

EVS_CLICKHOUSE=http://evstats:evstats@127.0.0.1:8123/evstats
EVS_REDIS=redis://127.0.0.1:6379/0
EVS_PORT=51321

环境变量（推荐）	启动参数	默认	含义
`EVS_CLICKHOUSE`	`-clickhouse`	`http://evstats:evstats@127.0.0.1:8123/evstats`	ClickHouse 连接，账号、口令、库名都是 `evstats`。同时存放账号、配置等系统数据，也是默认的数据分片 `s0`
`EVS_REDIS`	`-redis`	`redis://127.0.0.1:6379/0`	Redis 连接，默认无口令。会话、采集队列和限流都在这里
`EVS_PORT`	`-port`	`51321`	监听端口。进程对所有网卡开放，不能绑到某一张网卡

默认主机是 127.0.0.1。容器和正式环境要写成服务名或内网地址，并换成自己的口令。没有配置文件。值不合法或连不上时，日志只点名实际生效的那一个（环境变量名或启动参数名），不回显内容；应用本身不会打印连接串。

部署方式	`EVS_REDIS` 示例
单机 Compose（服务名 `redis`）	`redis://:你的口令@redis:6379/0`
Redis 在别的机器	`redis://:你的口令@10.0.0.12:6379/0`
需要 TLS	`rediss://:你的口令@redis.example.com:6380/0`

命令

命令	作用
`evstats [-clickhouse URL] [-redis URL] [-port N]`	启动服务。三个参数都可以省略；省略时用同名环境变量，再没有才用默认值
`evstats version`	打印版本、提交、构建时间
`evstats healthcheck [-port N]`	请求本机 `127.0.0.1` 上该端口的 `/health`，200 时退出码 0，否则 1（给容器健康检查用）。端口同样是 `-port`，然后 `EVS_PORT`，然后默认

数据目录

进程的工作目录下的 data/ 存下载的 IP 库。容器里工作目录是 /var/lib/evstats，示例把 /var/lib/evstats/data 挂成卷；二进制部署时 systemd 的 WorkingDirectory 决定它在哪。多台进程各用各的 data/，不要共用。

资源建议

部署	建议
快速体验：三个服务一台机器	不少于 2 核 4GB
`evstats` 自身	可用内存不少于 512MB，要留出把 IP 库整个载入内存的空间
ClickHouse	按官方的小实例建议起步；事件多了以后先加内存和 SSD
Redis	留出采集积压的空间：积压上限由 `ingest.stream_max` 决定（默认 100 万条）

各档的实测吞吐与查询耗时在测过之后公布在限制与上限。

ClickHouse 账号

EVS_CLICKHOUSE（或 -clickhouse）用的账号至少要能建库、建表、插入、查询、加列、建物化视图。应用每次启动都会对照表结构，缺表建表、缺列加列，见升级。口令写在环境变量里，也可以写在启动参数里。

探活与指标

路径	用途
`GET /health`	不需要登录，给负载均衡和监控用
`GET /metrics`	Prometheus 文本格式的过程指标，只对内网开放

/health 的返回：

json

{
  "version": "0.1.0",
  "setup": "ok",
  "meta": "up",
  "shards": [{ "id": "s0", "status": "up" }],
  "geo": "ok",
  "redis": "up",
  "ingest_lag": 0
}

字段	取值
`setup`	`need_admin`、`ok`。Redis 在启动时连接，连不上进程会退出
`meta`	`up`、`down`。连不上时 HTTP 状态是 503，其余情况都是 200
`shards[].status`	`up`、`down`
`geo`	`unset`（没配 IP 库）、`ok`、`down`（下载或载入失败）
`redis`	`up`、`down`
`ingest_lag`	采集队列里还没写入 ClickHouse 的条数

组件降级只写在字段里，不会让负载均衡把整台摘掉。响应里没有连接串、密钥和配置原文。/metrics 的指标见运维与排障。

装好之后

浏览器打开 evstats，按首次引导创建管理员，再选择是否创建演示项目。
放到公网：反向代理与 HTTPS，并填好 site.public_url 与 http.trusted_proxies。
接入第一个网站：接入概览。
日常运维：运维与排障、升级、备份与恢复。

部署总览 ​

选一种方式 ​

要准备什么 ​

端口与网络 ​

镜像与版本 ​

启动参数 ​

命令 ​

数据目录 ​

资源建议 ​

ClickHouse 账号 ​

探活与指标 ​

装好之后 ​