安全与隐私

evstats 会保存哪些数据、钥匙怎么管、默认做了哪些防护，以及上线前要核对的部署基线。发现漏洞请按 报告安全问题 私下报告。

两把钥匙

	写入密钥 evs_wk_xxx	接口密钥 evs_xxx
属于	项目	用户
能做	给这个项目写事件	只读，能看的项目和这个人在后台一样
暴露了会怎样	别人能往这个项目里灌事件，但读不到任何数据。轮换即可	别人能读到这个人能看的全部项目的统计。立即停用

• 两种密钥都用加密安全的随机数生成，校验只用 SHA-256，列表和日志里只有前缀，界面默认遮盖。
• 接口密钥服务端只存 SHA-256，创建时只完整显示一次。写入密钥本来就要写进网页源码，服务端另存一份原文：管理员在项目的「接入」页签输入自己的登录密码才能看到，输错 5 次锁 10 分钟，每次查看都记操作日志。原文不进缓存、不进列表接口。
• 密钥不要进仓库、不要进截图。像素地址的查询参数里带着写入密钥，不要把像素地址贴到公开的地方。
• 写入密钥调 OpenAPI、接口密钥调采集，都会被拒绝。

会保存的数据

数据	说明
事件明细	页面地址、来源、UTM、事件属性、终端信息，按项目的保留天数（默认 365 天）自动清理
访客 IP	会保存，并解析出国家、省、市。解析用本机内存里的离线库，访客 IP 不发给任何第三方
匿名 ID	Web SDK 存在访客浏览器的 localStorage，不用 Cookie
会话回放	只有打开回放时才有，默认 15 天
账号	密码用 bcrypt 保存

明细里有 IP 是为了地域分析，用保留天数约束它的寿命。本期没有按人删除事件的功能，确有需要时由管理员在 ClickHouse 里处理。

登录与会话

• 登录状态是 HttpOnly、SameSite=Lax 的 Cookie，页面脚本读不到；检测到 HTTPS 时加 Secure。会话 ID 不放 localStorage。
• 会话存在 Redis 里，退出、改密码、重置密码后所有进程上立即失效。
• 登录与找回密码都要服务端生成的验证码；登录失败有限流。
• 后台的所有写操作都必须是 Content-Type: application/json，普通表单和图片请求发不出这样的请求。管理端不要和不可信的站点放在同一个父域的可写子路径下。
• 页面带 Content-Security-Policy、X-Frame-Options: DENY、X-Content-Type-Options: nosniff 等响应头。

采集面

• 引导没完成时不收数。
• 请求体和解压后都不超过 1MB，每批最多 100 条；队列有长度上限，顶满返回 42901。
• http.trusted_proxies 为空时，不采信任何 X-Forwarded-For，伪造的转发头改变不了入库 IP。
• 被过滤的原因不告诉 SDK，只在管理员的接入检查里可见。
• 调试回显在密钥错误时不返回任何事件。

全埋点与回放

• 全埋点只记点击的元素和停留时长，不读输入框、密码框、可编辑区域的内容；元素文本截断到 100 字。
• 回放默认关闭；打开后按比例抽样，所有输入框默认遮罩，遮罩选择器命中的区域整块屏蔽。
• 回放正文只在登录且有项目权限时播放，不进 OpenAPI，也不交给模型；播放器在禁止执行脚本的沙箱里。

查询与 Agent

• 所有查询只访问当前项目；维度、粒度这类标识符走白名单，事件名、路径、筛选值都用参数绑定。
• 自定义 SQL 只给管理员，只能查本项目的事件和聚合表，只读。
• CSV 里以 =、+、-、@ 开头的单元格会被转义，不会在 Excel 里当公式执行。
• Agent 没有 SQL 工具；查询的项目由对话决定，模型改不了。提问时，查询结果会发给你在 ai.base_url 配置的模型服务。
• 热力图叠加的令牌只能读一个项目、一个路径的热力图，10 分钟过期，打开页面后立即从地址栏删掉。

操作日志

管理员能看操作日志：登录、授权、配置、密钥、导出、SQL 等操作都有记录，日志正文里没有密钥原文和密码。见 操作日志。应用日志和访问日志里同样没有口令、连接串、密钥和 Cookie。

不回传数据

evstats 不向作者回传任何数据：没有遥测、没有联网检查更新、没有授权服务器。「自监控」埋点默认关闭，打开后也只发到你填写的地址。

部署基线

上线之前逐条核对：

1. Compose 里的示例口令 change-me 已经换掉。
2. ClickHouse（8123 / 9000）和 Redis（6379）不对公网开放，只让 evstats 连接。
3. /metrics 只在内网可访问。
4. 前面有 HTTPS 反代，site.public_url 和 http.trusted_proxies 已填。
5. 反代对 /dash/agent/ 关掉了缓冲。
6. 每个节点的 data/geo 在本地盘；所有进程共用同一个 Redis，不按节点拆库。
7. 备份包括每个分片的 ClickHouse 数据目录和 Redis 的 AOF。
8. 回放如果打开，已经在隐私政策里告知访客，并给敏感区域加了遮罩。

许可证

evstats 以 Apache-2.0 发布。再分发（包括修改后再分发）时，保留 LICENSE 和 NOTICE，见 许可证。