数据产品说明

本项目没有独立的“北极星/数据中台”产品；可用的数据能力内嵌在控制台与 Open API 中：运营看板（metrics/overview、stats/dimensions）、全局/按天趋势、推送统计、消息检索与轨迹、告警事件、回调投递与操作审计。本页说明每个数据产品的口径、时效、可导出性与限制，避免把它当成计费账单或 BI 数仓。

概念​

数据产品清单​

数据产品入口回答的问题时效 / 保留
运营看板GET /api/admin/apps/{appkey}/metrics/overview今天/近 7 天 DAU、消息、在线峰值、错误率事件驱动；按 UTC 日聚合
维度统计GET /api/admin/apps/{appkey}/stats/dimensions用户/群/群消息/聊天室/消息/在线及按天趋势同上；days 1–90
全局统计GET /api/admin/stats、/stats/trend跨应用汇总与趋势同上
统计 Open APIPOST /im/v2/stats/app、/stats/trend应用服务器侧拉取统计同上
推送统计GET /apps/{appkey}/push/stats、push.stats.day/byId推送发送/送达/失败与按天趋势push_logs 聚合；无通道级拆分
消息检索/轨迹/apps/{appkey}/messages、/{messageId}/trace单条消息是否入库/投递/离线/路由落盘消息；聊天室不落盘
告警事件/apps/{appkey}/alerts/events限流/回调失败/掉线/5xx 触发记录内存环 1000/指标
回调投递/apps/{appkey}/callbacks/deliveries事件投递结果与重试内存 10000 条
操作审计/apps/{appkey}/audit管理端写操作谁/何时/对什么内存环 5000 条

指标口径​

指标定义注意
DAU当日活跃去重用户单应用单日去重上限 10000；UTC 日界
消息量落盘消息条数（单聊/群/系统通知等）不含聊天室 ephemeral 消息；不等于 API 调用数
群消息量落盘群消息条数消息量的子集
聊天室消息量固定 0聊天室消息不落盘，无法统计
在线峰值当日在线用户数峰值由维护周期采样
错误率errors / (messages + errors)演示级近似，不是 HTTP 5xx 比例
推送 sent/delivered/failedwebhook 推送尝试/成功/失败厂商通道未实现，无通道维度
不是计费系统

自托管版没有计费、账单、发票或用量结算。这里的“消息量/推送量”只用于运营观察，不产生费用，也不保证与任何外部账单一致。

前置条件​

  • 服务端已启动，Admin API 可达（http://127.0.0.1:8080）；统计随服务端状态持久化。
  • 知道要回答的问题属于哪个数据产品（运营、推送、消息、告警、审计），避免用错误口径解释。
  • 需要跨系统分析时，由使用方按分页接口拉取并落库；服务端不提供 BI 连接、SQL 查询或数据仓库导出。
  • 自托管版无“数据产品购买/订阅”；所有数据能力随服务端提供（不适用项）。

步骤​

  1. 先定义问题与时间窗

    区分“现在是否健康”（概览）、“为什么这条没到”（消息轨迹）、“这周趋势”（dimensions/trend）。

  2. 选数据源并读口径

    按下表选择接口；先看 notes 与字段说明，特别是聊天室消息为 0、错误率为近似值。

  3. 交叉核对

    单应用异常时对照全局统计；推送失败对照回调投递日志；消息缺失对照轨迹与在线连接。

  4. 导出与留存

    消息用 CSV 导出（limit/beforeSeq）；其它数据按分页接口拉取落库，服务端环缓冲会淘汰旧数据。

  5. 接入告警

    把 rate_limited/callback_failure/online_drop/error_5xx 配成告警规则，事件通过 HMAC webhook 推送。

参数表​

数据方法与路径参数
应用概览GET /api/admin/apps/{appkey}/metrics/overview—
维度统计GET /api/admin/apps/{appkey}/stats/dimensionsdays 1–90
全局统计 / 趋势GET /api/admin/stats、/stats/trenddays、appkey
推送统计GET /api/admin/apps/{appkey}/push/statsdate、days
消息检索GET /api/admin/apps/{appkey}/messagesuserId/conversationType/targetId/keyword/from/to/offset/limit
消息导出GET /api/admin/apps/{appkey}/messages/exportlimit、beforeSeq
告警事件GET /api/admin/apps/{appkey}/alerts/eventsmetric、分页
回调投递GET /api/admin/apps/{appkey}/callbacks/deliverieseventType/status/from/to
操作审计GET /api/admin/apps/{appkey}/auditactor/action/object/from/to

示例​

一屏看健康度​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/metrics/overview" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/stats/dimensions?days=7" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/connections/stats" \
  -H 'X-Admin-Secret: dev-admin'

推送与回调交叉核对​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/push/stats?days=7" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/callbacks/deliveries?status=failed&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/alerts/events?metric=callback_failure&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

消息审计与导出​

Shell
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/messages?userId=alice&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/messages/export?limit=1000" \
  -H 'X-Admin-Secret: dev-admin' | jq -r '.data.csv' > messages.csv

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/audit?action=admin.users.ban&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

常见问题​

有“北极星/数据中台”页面吗？​

没有。数据能力分布在控制台看板与 Admin/Open API；本页不虚构不存在的产品入口。

能接 BI 工具直连数据库吗？​

不提供。请通过分页接口拉取并落到自己的数仓；PostgreSQL 模式下的日统计表属于内部实现，不是对外契约。

为什么统计和客户端看到的不一致？​

统计按 UTC 日界、落盘消息与去重用户计算；客户端本地可能包含未发送/本地消息，聊天室消息也不计入。

数据保留多久？​

统计随服务端快照保留；告警/回调/审计是内存环缓冲（1000/10000/5000），重启或淘汰会丢失旧记录。

如何做长期留存？​

消息用 CSV 导出；其它数据按接口分页拉取后写自有存储，并自行做脱敏与访问控制。

错误率为什么不是 5xx 比例？​

实现按 errors/(messages+errors) 聚合，属于演示级近似；需要精确 HTTP 指标请在网关层采集。

多实例部署统计会合并吗？​

不会。当前统计是单实例内存聚合；多实例需要外部汇总。

相关链接​