5 分钟看懂 Umami 实时数据推送：从事件采集到实时看板的完整指南

5 分钟看懂 Umami 实时数据推送从事件采集到实时看板的完整指南【免费下载链接】umamiUmami is a privacy-first analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place — no cookies, no surveillance, self-hosted or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/um/umami访客刚点下立即购买你自托管的 Umami 仪表盘上那条分钟级曲线几乎同步抬升——不用导出报表不用等 T1也不需要种任何 cookie。Umami 是一个隐私优先、可自托管的 Web 分析平台它的实时数据推送本质上是一条链路前端追踪脚本上报事件 → 后端接口校验并落库 → 实时看板拉取最新数据渲染数据量大时还能通过 Kafka 把事件流直接推给外部系统。下面按原理 → 配置 → 落地 → 排障的顺序把这条链路拆清楚。原理先行一个事件要闯过的四道关理解整条链路只需要记住四个环节每个环节都有明确的源码位置可以定位。第一关前端追踪脚本追踪脚本 src/tracker/index.js 干了三件事监听路由变化自动记录页面浏览带 300ms 防抖避免重复上报、拦截带有事件标记的点击、把数据以POST形式发到后端收集接口。它会在浏览器里挂出window.umami对象后续所有自定义事件都从这里发出。第二关接口校验与会话识别所有上报最终汇入 src/pages/api/send.ts。这里有一套严格的 yup 校验规则type只接受event或identify两种取值payload.website必须是合法 UUID主机名、IP 等字段都有格式和长度限制不符合直接打回。校验通过后src/lib/session.ts 会用站点 ID 主机 IP UA算出一个稳定的会话 ID访客 30 分钟session.iat超过 1800 秒没有动静就会换发新的visitId从而被统计为一次新访问。返回的 token 会被脚本缓存进x-umami-cache请求头后续上报可跳过会话查询省一次数据库往返。第三关落库与外发真正的写入在 src/queries/analytics/events/saveEvent.ts它按数据库类型分流关系库模式PostgreSQL / MySQL直接通过 Prisma 写入website_event表自定义属性存到website_event_dataClickHouse 模式事件不直接落库而是以 JSON 形式发布到 Kafka 的event主题由外部管道消费写入这是官方为高吞吐场景预留的数据外推出口。事件名、URL、标题都有长度上限各 500/50 字符定义在 src/lib/constants.ts超长部分会被截断而不是报错。第四关实时看板读取看板侧走 src/pages/api/realtime/[websiteId].ts 接口聚合逻辑在 src/queries/analytics/getRealtimeData.ts统计窗口固定 30 秒REALTIME_RANGE前端 hook src/components/hooks/queries/useRealtime.ts 每 10 秒REALTIME_INTERVAL轮询一次并刷新图表。所以实时的准确含义是事件落库后最多 10 秒出现在看板上。配置步骤三步跑通自定义事件前提是先自托管一个 Umami 实例克隆仓库后按 README 配置数据库即可git clone https://gitcode.com/GitHub_Trending/um/umami第 1 步在你的网站挂上追踪脚本在head里加入一行data-website-id填管理后台生成的站点 UUIDscript defer srchttps://你的umami域名/umami.js>umami.track(purchase, { plan: pro, amount: 99 });DOM 属性声明——适合按钮、链接这类可直接标记的元素事件名写在data-umami-event上其余data-umami-event-*属性会自动收集为事件属性button>KAFKA_URL协议://用户名:密码你的kafka地址 KAFKA_BROKERbroker1,broker2URL 里带凭据时会自动启用 SASLscram-sha-256。下游用 Flink、Spark 或数仓的 Kafka 连接器订阅这两个主题就拿到了和看板同源的事件流用于告警、营销触发、实时大屏都可行——这也是 Umami 推送能力最正规的出口。排障清单事件没出现时按顺序查这 6 处是不是被当成爬虫了send.ts里用isbot检查 User-Agent命中后直接静默返回。自己写脚本测试时要注意 UA或部署时设置DISABLE_BOT_CHECK关闭该检查。返回 403检查IGNORE_IP环境变量它是按逗号分隔的封禁名单支持 CIDR 网段写法。400 校验失败对照 schema 逐项核对type只能是event/identifywebsite必须是 UUIDdata必须是对象字段超长主机名 100、语言 35 等也会被拒。事件发了但没算新访客30 分钟内同一浏览器重复访问会复用旧会话想模拟新访客要等窗口过期或换环境。脚本根本没发请求三种常见原因脚本上写了data-auto-trackfalse、data-domains白名单没包含当前域名、浏览器 localStorage 里存在umami.disabled标记。看板数字不涨先确认轮询链路正常10 秒一次再看时间窗口实时视图只看最近 30 秒历史事件不会补进去。一句话总结Umami 的实时数据推送 一个带校验的收集接口 10 秒轮询的实时看板 可选的 Kafka 外推管道配置成本几乎只有两行脚本。建议从转化链路上最值钱的一两个事件注册、下单开始埋点验证实时看板无误后再决定是否接入 Kafka 把事件流推向你的数仓。【免费下载链接】umamiUmami is a privacy-first analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place — no cookies, no surveillance, self-hosted or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/um/umami创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考