Countly 25.03.45：几个小修复，解决实际踩坑问题

Countly 是一个开源的实时移动与 Web 分析平台，自建部署的用户不少。25.03.45 版本没有大功能更新，但修了几个在日常使用中容易遇到的麻烦——事件键带点号导致统计失真、图表笔记颜色验证报错、禁用插件后任务列表仍残留脏数据。这些 bug 不修，数据可信度会打折扣。

事件键含 . 的 topEvents 计算修复

在 Countly 中，事件键（event key）是标识用户行为的核心字段。很多团队习惯用层级命名，比如 purchase.button.click 或 login.form.submit，键里自然带上了 .。

问题在于，Countly 内部在计算 topEvents 时，对包含 . 的键做了不当处理——可能是把 . 当成了 MongoDB 查询里的路径分隔符，导致聚合结果丢失或错位。25.03.45 修复了这一计算逻辑。

影响判断：如果你的事件键从未用过 .，这个修复与你无关。但一旦用了层级命名，之前的 topEvents 报表数据可能是不准确的，升级后建议重新审视相关报表。

图表笔记颜色验证不再报错

Countly 支持在图表上添加笔记（note），用来标注关键时间节点——比如"这天上线了新版本"。创建或编辑笔记时可以指定颜色，但旧版 saveNote 的 schema 只接受字符串类型的颜色值。

实际使用中，前端传过来的颜色值有时是数值（比如从颜色选择器返回的整数色值），schema 校验直接拒绝，笔记就保存失败。25.03.45 放宽了校验，数值颜色也能通过。

这个修复虽小，但体验影响不小——之前用户可能反复尝试保存笔记却始终报错，还很难定位原因。

禁用插件的任务不再污染任务列表

Countly 的插件体系允许按需启用/禁用。但旧版在获取任务列表（jobs list）时，没有过滤掉属于已禁用插件的任务。结果是：插件关了，它的定时任务还在列表里挂着，既占展示空间，又可能误导运维人员以为任务仍在执行。

25.03.45 在查询任务列表时加入了插件启用状态的过滤，列表更干净，也避免了误操作。

findGroups 聚合修复

摘要中提到 [groups] 的 findGroups 聚合也有修复，但具体细节被截断。从命名推断，这涉及用户分组查询的聚合逻辑——可能是分组条件组合时结果不准确，或某些边界条件下返回空集。如果你在使用 Countly 的用户分群功能，升级后留意分组结果是否与预期一致。

实践：自建部署 Countly 并追踪带层级的事件

下面给出一个最小化的 Docker Compose 部署示例，以及一段发送带 . 事件键的追踪代码，正是本次修复覆盖的场景。

Docker Compose 部署（最简配置）

# docker-compose.yml
version: "3.8"
services:
  countly-api:
    image: countly/api:25.03.45
    ports:
      - "6001:6001"
    environment:
      - COUNTLY_CONFIG__MONGODB=mongodb://countly-mongo:27017/countly
      - COUNTLY_CONFIG__REDIS=redis://countly-redis:6379
    depends_on:
      - countly-mongo
      - countly-redis

  countly-front:
    image: countly/frontend:25.03.45
    ports:
      - "6000:6000"
    depends_on:
      - countly-api

  countly-mongo:
    image: mongo:6.0
    volumes:
      - countly-mongo-data:/data/db

  countly-redis:
    image: redis:7-alpine
    volumes:
      - countly-redis-data:/data

volumes:
  countly-mongo-data:
  countly-redis-data:

启动：

docker compose up -d

访问 http://localhost:6000 进入管理界面，完成初始设置后获取 App Key。

Python SDK 发送层级事件键

# countly_event_demo.py
# 需要安装: pip install countly-sdk-python

import countly

# 替换为你的 App Key 和 Countly 服务器地址
COUNTLY_APP_KEY = "YOUR_APP_KEY"
COUNTLY_URL = "http://localhost:6001"

countly.init(COUNTLY_APP_KEY, COUNTLY_URL)

# 发送一个带 "." 的事件键——正是 25.03.45 修复的场景
countly.track_event(
    key="purchase.button.click",   # 层级命名，包含点号
    segmentation={
        "item_category": "electronics",
        "payment_method": "credit_card",
    },
    count=1,
    sum=299.99,
)

# 会话结束前必须调用，否则数据可能丢失
countly.end_session()

print("事件已发送，等待 Countly 处理后查看 topEvents 报表")

运行前把 YOUR_APP_KEY 替换成实际值。升级到 25.03.45 后，purchase.button.click 这类键在 topEvents 中会被正确聚合；旧版本则可能统计异常。

升级建议

整体来看，25.03.45 是一个偏修复的版本，没有破坏性变更。自建部署的用户可以直接拉新镜像滚动升级，云端托管用户等待平台更新即可。如果你的事件键用了层级命名，这个版本值得尽快跟进——数据准确性不该因为一个点号而妥协。