快速体验

十分钟从一台空机器到在数据概览里看到 PV：保存一段 Docker Compose，打开网页，粘贴一段 SDK。三个服务放在同一台机器上，适合体验、测试环境和小流量站点；正式上线请看 生产环境部署。

1. 准备一台机器

2 核 4GB 以上的 Linux 机器，装好 Docker（带 Compose v2，docker compose version 能输出版本）。这也是 性能基线 里「单机最小」一档的环境。

2. 启动 ClickHouse、Redis 和 evstats

新建一个目录，下载 compose.yaml（也可以把下面的内容复制保存）：

mkdir evstats && cd evstats
curl -fsSLO https://evstats.mosong.cc/deploy/compose/compose.yaml

把文件里的 change-me 换成你自己的口令（ClickHouse 的几处要一致，Redis 的几处要一致），然后启动：

services:
  clickhouse:
    image: clickhouse/clickhouse-server:24.8
    environment:
      CLICKHOUSE_USER: evstats
      CLICKHOUSE_PASSWORD: change-me
      CLICKHOUSE_DB: evstats
    volumes:
      - ch-data:/var/lib/clickhouse
    healthcheck:
      test: ["CMD", "clickhouse-client", "--user", "evstats", "--password", "change-me", "--query", "SELECT 1"]
      interval: 5s
      retries: 30
    restart: unless-stopped
    # 不要把 8123 映射到公网
  redis:
    image: redis:7
    command: ["redis-server", "--appendonly", "yes", "--requirepass", "change-me"]
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "change-me", "ping"]
      interval: 5s
      retries: 30
    restart: unless-stopped
    # 不要把 6379 映射到公网
  evstats:
    image: ghcr.io/mosongcc/evstats:1
    working_dir: /var/lib/evstats
    # 推荐环境变量。同名启动参数 -clickhouse、-redis、-port 写了就覆盖。
    environment:
      EVS_CLICKHOUSE: http://evstats:change-me@clickhouse:8123/evstats
      EVS_REDIS: redis://:change-me@redis:6379/0
    volumes:
      - evstats-data:/var/lib/evstats/data
    ports:
      - "51321:51321"
    # ClickHouse 或 Redis 连不上时 evstats 按设计退出：等两个依赖健康后再启动，异常退出后自动重启
    depends_on:
      clickhouse:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/evstats", "healthcheck"]
      interval: 10s
volumes:
  ch-data:
  redis-data:
  evstats-data:

docker compose up -d
docker compose ps        # evstats 显示 healthy 即可

evstats 在这份 Compose 的 environment 里写了 EVS_CLICKHOUSE 和 EVS_REDIS。不写时默认连本机 127.0.0.1，容器里必须写成服务名。第一次启动时它会在 ClickHouse 里建好全部表。

国内网络

镜像同时发布在阿里云：把 ghcr.io/mosongcc/evstats:1 换成 registry.cn-hangzhou.aliyuncs.com/mosongcc/evstats:1。

几点说明：

• ClickHouse 和 Redis 没有映射到宿主机端口，只有 evstats 在同一个 Compose 网络里连它们。不要为了方便把 8123 或 6379 映射出来。
• 数据都在卷里：ch-data（ClickHouse）、redis-data（Redis 的 AOF，里面有还没入库的事件）、evstats-data（IP 库）。备份见 备份与恢复。
• 端口默认 51321，进程对所有网卡开放，映射是 "51321:51321"。要换端口时同时改这一行，并加上 EVS_PORT，下文的地址也换成新端口。容器里的 healthcheck 会读 EVS_PORT。

3. 打开网页，完成引导

浏览器打开 http://你的主机:51321/。第一次打开会说明：这是首次访问，请设置超级管理员账号和密码，用来初始化系统。只填账号、密码和确认密码。显示名、邮箱、AI 和项目登录后再设。

evstats

下一步选要不要创建「演示项目」。想先看看效果就选创建：服务端当场生成约 1 万条虚构的示例数据，写完自动进入，每个分析页都能点开看，见 创建演示项目。填什么、失败怎么办，见 首次引导。

4. 创建项目，粘贴 SDK

到「系统 → 项目」创建你自己的项目：名称、标识、时区。标识和时区创建后不能修改，时区决定了「今天」从几点算起。

创建完会弹出写入密钥，形如 evs_wk_xxx。关掉之后，管理员在项目的「接入」页签点「查看」、输入登录密码，还能看到完整密钥，上报片段也会一起填好。把 Web SDK 片段放进网页的 <head>：

<script src="https://unpkg.com/@evstats/web/dist/evstats.min.js"></script>
<script>
  evstats.init({
    endpoint: "http://你的主机:51321/sa",
    key: "evs_wk_xxx"
  })
</script>

endpoint 是完整的采集地址，SDK 原样请求，不会再拼路径。服务端、App 等其它接入方式见 接入概览。

evstats

5. 看到第一条事件

打开装好 SDK 的网页，再回到项目的「接入」页签：「最近收到的事件」里应该出现 $pageview，点击页面上的按钮还会出现 $WebClick。然后打开数据概览，就能看到 PV。

evstats

没有出现时，按 接入检查 的顺序排查：先看浏览器网络面板里 /sa 的响应码。

6. 下一步

想要	去做
看到访客在哪个省市	在「系统配置 → IP 库」填 geo.ip2region.url，见 系统配置
用中文问数	在「系统配置 → AI」填兼容 OpenAI 的地址，见 Agent 问数
每天打开就是自己关心的数	把常看的图加入看板，见 看板与书签
放到公网、加 HTTPS	反向代理与 HTTPS
正式上线、数据量大	生产环境部署
让业务后台取数	OpenAPI

清理

体验完不需要了：

docker compose down        # 停掉并删除容器，数据卷保留
docker compose down -v     # 连数据卷一起删除，数据不可恢复