Umami —— 自托管 Web 流量分析(JavaScript 埋点统计)
最后更新:2026-09-17(§2.3 新增
client-env会话级设备环境画像事件:OS 精确版本/机型/浏览器完整版/内嵌宿主/屏幕硬件网络等 27 个属性)
这个工具是做什么的
GoAccess 靠读 nginx access.log 回答"有多少访客、看了哪些页面、来自哪里",而 Umami 走的是完全相反的一条路:在网页里嵌入一段 JavaScript(script.js),由浏览器在每次页面访问时主动把事件上报到 Umami 后端。它不碰服务器日志,属于**客户端埋点(Client-Side Tracking)**流派,是自托管、隐私友好、免 Cookie 的轻量版 Google Analytics。
本文重点是原理:这套系统里有谁(实体)、数据怎么流动(数据流)、浏览器到后端怎么通信(通信过程),并在最后与 GoAccess 做横向对比。文中的 analytics.example.com、Website ID、SQL 结果均为教学示例,不对应任何真实埋点端点。
一、实体模型:这套系统里有谁
1.1 实体清单
| 实体 | 角色 | 关键属性 / 职责 |
|---|---|---|
| 浏览器 | 事件生产者 | 加载页面 → 注入脚本执行 → 主动上报 pageview / 事件 |
| script.js | 采集脚本 | 用 data-website-id 关联站点;按需 POST 到 /api/send |
| 站点 HTML | 埋点载体 | <script src="https://analytics.example.com/script.js" data-website-id="xxx"></script> |
| Umami 前端 | Next.js 应用 | 提供管理后台(Dashboard)与采集接口(/api/send) |
| Umami API | 后端服务 | 鉴权、校验 payload、写入数据库、供前端查询统计 |
| PostgreSQL | 持久化存储 | 存事件、会话、访客、站点配置;与 GoAccess 的无数据库形成对比 |
| nginx | 反向代理 | 把 analytics.example.com 请求反代到 127.0.0.1:3000,提供 HTTPS |
1.2 实体关系

核心结论:Umami 是有数据库的——浏览器 → script.js → /api/send → nginx → Umami → PostgreSQL,事件逐条落库,这是它与 GoAccess(无数据库、内存哈希聚合)最本质的区别。
二、数据流:一次页面访问怎么变成一条记录
2.1 埋点脚本的加载
浏览器打开站点页面时,HTML 里有这样一段:
<script defer src="https://analytics.example.com/script.js" data-website-id="00000000-0000-4000-8000-000000000001"></script>src指向 Umami 的采集脚本(由 nginx 反代提供)data-website-id是这个站点在 Umami 里的唯一 ID,用于把事件归到正确站点defer让脚本在文档解析后、DOMContentLoaded前执行,不阻塞渲染
2.2 pageview 事件上报(核心链路)

上报的 payload 结构(v3 版):
{
"type": "event",
"payload": {
"website": "00000000-0000-4000-8000-000000000001",
"event_type": "pageview",
"url": "/tools/cpu/top",
"referrer": "https://www.google.com/",
"hostname": "geek-doc.cn",
"language": "zh-CN",
"screen": "1920x1080",
"title": "性能分析工具速查"
}
}2.3 自定义事件(本站埋点清单)
除自动 pageview 外,前端代码调用 window.umami.track(name, props) 上报自定义事件(event_type=2,落 website_event 表、事件名进 event_name;属性拆行进 event_data 键值表,data_key + string_value/number_value,经 website_event_id 关联)。本站所有埋点集中在 .vitepress/theme/:track.ts 统一封装 trackEvent()(失败静默,tracker 被拦也不影响页面),无新增依赖、不增加脚本体积。
| 事件名 | 触发时机 | 属性 | 回答的问题 |
|---|---|---|---|
copy-command | 点击 demos/repo 卡片的复制按钮,或代码块 VitePress 原生「复制」按钮(document 级委托) | btn: demo/repo/codeblock;代码块附 lang | 读者有没有真的复制命令实操、哪类语言最多 |
image-zoom | 点击放大正文图片(medium-zoom open) | src: 图片站点相对路径(如 /plantuml/xxxx.svg) | 哪张 PlantUML 图最常被点开(= 可能不够清晰);Umami 自动附带所在页面 URL |
search-used | Pagefind 输入框停顿 1.5s 后,同一搜索词只报一次 | query: 搜索词前 30 字符;result_count: 已渲染顶层结果数 | result_count=0 的词 = 内容缺口信号;高频词反映导航是否直观(结果默认每页只渲染 5 条,1~5 只代表有命中) |
outbound-click | 点击任何 host 不同于本站的 http(s) 链接(document 级捕获委托) | url: 目标域名(host) | 读者从文章跳去哪里(GitHub/官方文档等) |
client-env | 每个标签会话首次访问上报一次(sessionStorage 去重);补 Umami session 表服务端粗解析 UA 的不足(device 只有 desktop/mobile/tablet、OS 版本被 UA 冻结抹平) | 27 个属性,见下表 | 读者到底用什么设备/系统/内嵌浏览器访问,精确版本与机型分布 |
client-env 属性明细(只报非空字段;原始 UA 截断 500 字符;数据只进自托管 PostgreSQL):
| 属性 | 含义 | 取值示例 / 精度说明 |
|---|---|---|
os / os_ver | 操作系统 / 真实版本 | Windows 版经 Client Hints 细到 11 23H2(UA 里 Win11 永远显示 NT 10.0);macOS 破除 10.15.7 冻结报真实 11~26;Android 完整三段如 14.0.0;iOS 如 18.1;另识别 iPadOS/ChromeOS/HarmonyOS;Linux 浏览器拿不到发行版 |
device_model | 设备型号 | Android 取 CH marketing 名(如 Pixel 8,部分国产机仍是型号代码);iPhone 由逻辑分辨率+DPR 反推机型族(如 iPhone 14Pro/15/15Pro/16,显示缩放模式会落到相邻机型);iPad 固定 iPad |
form | 设备形态 | phone / tablet / desktop(含 iPadOS 伪装 Mac 桌面 UA 的识别) |
browser / browser_ver / engine | 浏览器 / 完整版本 / 内核 | 版本取 CH fullVersionList 四段号(UA 冻结只剩大版本);engine=blink/webkit/gecko,可识破 iOS 上 Chrome/Edge/Firefox 实为 WebKit 套壳;另识别三星/华为/小米/QQ/夸克/UC 浏览器及 Android WebView |
host / host_ver | 内嵌浏览器宿主 / 版本 | wechat/wxwork/dingtalk/feishu/alipay/qq/weibo/douyin/bilibili/baidu + 宿主版本(如微信 8.0.49);系统浏览器为空 |
arch / bits | CPU 架构 / 位宽 | x86/arm,32/64(CH) |
ram / cores | 设备内存档位 / 逻辑核数 | 内存为 Chromium 量化档位 0.25~8 GB;核数来自 hardwareConcurrency |
screen / dpr / orient | 屏幕逻辑分辨率 / 像素比 / 方向 | 如 393x852、3、portrait |
vw / vh / touch | 视口宽高 / 触屏点数 | 视口高度可反映内嵌浏览器工具栏占用;touch=0 为纯键鼠 |
tz / tz_offset / lang | IANA 时区 / UTC 偏移分钟 / 语言 | Asia/Shanghai、+480、zh-CN |
net / save_data | 网络档位 / 省流模式 | 4g/3g/2g/slow-2g(effectiveType,非真实制式);省流 0/1 |
dark / reduce_motion | 深色模式 / 减弱动效偏好 | 0/1,决定夜间样式与动画取舍 |
ua | 原始 User-Agent | 兜底排查用,截断 500 字符 |
能力边界:iOS Safari 不支持 Client Hints,且苹果不暴露 machine id,iPhone 只能按屏幕推断到「机型族」;Linux 发行版、真机 RAM 精确值(只有量化档位)、精确 iOS 小版本在部分套壳浏览器里也拿不到——这些是 Web 平台本身的限制。
隐私:属性只进自托管 PostgreSQL,不出第三方;搜索词可能含敏感片段,统一截断 30 字符。查询示例(新版 schema:事件在
website_event,属性在event_data键值表;查 0 结果搜索词时,把第二段 SQL 的条件加上AND nr.number_value = 0):sql-- 各自定义事件的总量 / UV SELECT event_name, COUNT(*) AS cnt, COUNT(DISTINCT visit_id) AS uv FROM website_event WHERE website_id = '00000000-0000-4000-8000-000000000001' AND event_type = 2 AND created_at >= now() - interval '15 days' GROUP BY event_name ORDER BY cnt DESC; -- search-used 的搜索词 + 结果数(data_type:1 字符串 / 2 数字) SELECT ks.string_value AS query, nr.number_value AS result_count, COUNT(*) AS times FROM website_event e JOIN event_data ks ON ks.website_event_id = e.event_id AND ks.data_key = 'query' JOIN event_data nr ON nr.website_event_id = e.event_id AND nr.data_key = 'result_count' WHERE e.website_id = '00000000-0000-4000-8000-000000000001' AND e.event_name = 'search-used' AND e.created_at >= now() - interval '15 days' GROUP BY ks.string_value, nr.number_value ORDER BY times DESC;sql-- client-env:设备机型 / 操作系统版本 / 内嵌宿主 Top 分布(每会话一条) -- 把 data_key 换成 device_model / os 与 os_ver / browser 与 browser_ver / host 等即可 SELECT d.string_value AS device_model, COUNT(*) AS sessions FROM website_event e JOIN event_data d ON d.website_event_id = e.event_id AND d.data_key = 'device_model' WHERE e.website_id = '00000000-0000-4000-8000-000000000001' AND e.event_name = 'client-env' AND e.created_at >= now() - interval '30 days' GROUP BY d.string_value ORDER BY sessions DESC; -- 同一行里同时取多个属性(os + os_ver 组合分布): SELECT o.string_value AS os, v.string_value AS os_ver, COUNT(*) AS sessions FROM website_event e JOIN event_data o ON o.website_event_id = e.event_id AND o.data_key = 'os' JOIN event_data v ON v.website_event_id = e.event_id AND v.data_key = 'os_ver' WHERE e.website_id = '00000000-0000-4000-8000-000000000001' AND e.event_name = 'client-env' AND e.created_at >= now() - interval '30 days' GROUP BY o.string_value, v.string_value ORDER BY sessions DESC;
2.4 会话(Session)是怎么组织的
- 每个访客首次访问会新建一个 session,并用一个标识(session/visit token)记住
- 之后该访客的后续事件都挂到这个 session 下,直到会话超时(默认 30 分钟无活动)才开新会话
session表记录浏览器、OS、国家、设备等维度信息;event表记录每次 pageview / 自定义事件
| 表 | 存什么 | 说明 |
|---|---|---|
website | 站点配置 | id(对应 data-website-id)、域名、时区 |
session | 会话维度 | 访客的一次连续访问:浏览器/OS/国家/设备/时长 |
event | 事件明细 | 每次 pageview、事件类型、URL、时间戳 |
对比 GoAccess:GoAccess 在内存哈希表里"边读边累加",落盘只有最终 HTML;Umami 把每条事件落进 PostgreSQL,所以能支持任意时间段的自定义查询、留存分析、实时曲线——代价是需要一个数据库来承载。
三、通信过程:管理与采集两条通道
3.1 采集通道:浏览器 → nginx → Umami
script.js 从浏览器向 analytics.example.com 发请求,经 nginx 反代进入容器:
| 点 | 说明 |
|---|---|
| 走 HTTPS | 域名配了 Let's Encrypt 证书,浏览器到 nginx 全程加密,无 Cookie、无明文指纹 |
| 反代路径 | nginx 把 /api/send 等请求反代到 127.0.0.1:3000(容器内 Umami) |
| CORS | script.js 是跨域加载的,Umami API 需返回允许的 Access-Control-Allow-Origin 让浏览器能读响应 |
| 无状态 | 采集接口不依赖登录态,任何人加载页面都会上报,天然适合匿名统计 |
3.2 管理通道:浏览器 → nginx → Umami 后台
管理后台是另一个入口 https://analytics.example.com/(同一个域名、同一套反代),登录后能看到 Dashboard:

注意:管理后台页面不含
script.js埋点,所以"登录后台"这个动作本身不会被统计——这是设计使然(避免把自己灌进数据里),也是很多人后台看 Overview 为 0 的原因之一(另一个是还没用浏览器访问过主站页面)。
四、GoAccess vs Umami:两种统计流派
两个工具都回答"站点访问情况",但数据源、架构、适用场景完全不同:
| 维度 | GoAccess | Umami |
|---|---|---|
| 数据源 | 服务器日志(nginx access.log) | 客户端 JS 埋点(浏览器上报) |
| 存储 | 无数据库,内存哈希聚合,落盘 HTML | PostgreSQL 落库 |
| 部署 | 单进程读日志 | 前端 + 后端 + 数据库(docker compose) |
| 精确度 | 能统计所有请求(含爬虫、curl、API) | 只统计执行了 script.js 的浏览器 |
| 爬虫 | 能看到(需 --ignore-crawlers 过滤) | 默认看不到(爬虫不执行 JS) |
| 资源开销 | 极低(读文本) | 需维护一个数据库 + 应用容器 |
| 实时性 | WebSocket 秒级 | 秒级(落库后查询) |
| 隐私合规 | access.log 含 IP/UA 原文 | 无 Cookie、可匿名化 |
| 维度 | 依赖日志字段(IP/UA/URL/referer/status) | 前端可采集(UA/screen/language/自定义事件) |
| 典型用途 | 流量大盘、防爬监控、带宽统计 | 真实用户行为、转化、留存、渠道分析 |
互补关系
- GoAccess 管"机器视角":所有打进服务器的请求都算,适合看流量规模、被爬虫扫、带宽成本——"量"。
- Umami 管"人视角":只算真正执行了 JS 的真实浏览器,适合看用户行为、来源渠道、页面停留——"质"。
- error.log 管"病":服务端 5xx、限流、超时,两者都看不到,需独立看日志。
实践建议:全站监控用 GoAccess 做流量仪表盘 + 防爬;用 Umami 做真实用户的行为分析。两者数据可对照——若 GoAccess 显示访问暴涨而 Umami 平稳,多半是爬虫/采集脚本在刷。
五、部署形态(示例)
下面以一套自托管 Umami 的示例部署说明(域名和标识均为占位值):服务运行在容器里,由 nginx 反代对外,链路如下:
浏览器 → https://analytics.example.com → nginx(443, Let's Encrypt) → 127.0.0.1:3000 → Umami 容器
└→ PostgreSQL 容器| 层 | 配置要点 |
|---|---|
| nginx 反代 | proxy_pass http://127.0.0.1:3000; + X-Forwarded-* 头,转发 Host/Proto |
| TLS | 独立 Let's Encrypt 证书,每日 cron 自动续期 + reload |
| 端口暴露 | 容器只监听 127.0.0.1:3000,公网不可直连,必须经反代 |
| 埋点 | 主站构建时通过环境变量注入采集脚本地址与 Website ID;仓库与文档只保留占位符 |
| 凭据 | 管理后台账号存于服务器 root 只读文件,不写入文档 |
六、UTM 归因
6.1 UTM 是什么
UTM(Urchin Tracking Module)是加在 URL 后面的一组标准参数,用来标记「这个流量是从哪个渠道、哪个活动来的」。Umami 会自动识别这些参数,在后台的 UTM 面板里按来源/媒介/活动做归因统计。
| 参数 | 含义 | 示例 |
|---|---|---|
utm_source | 流量来源(哪个平台) | utm_source=zhihu |
utm_medium | 媒介类型 | utm_medium=social |
utm_campaign | 活动名称 | utm_campaign=mesi-promo |
utm_term | 关键词(付费搜索用) | utm_term=perf |
utm_content | 内容区分(A/B 测试) | utm_content=banner-a |
示例:在知乎发一个带 UTM 的推广链接:
https://geek-doc.cn/concepts/cache/mesi?utm_source=zhihu&utm_medium=social&utm_campaign=mesi-promo用户点这个链接进来,Umami 就会在 UTM 面板记一条「来源 zhihu、媒介 social、活动 mesi-promo」的数据。
6.2 为什么 UTM 面板没有数据
这是正常现象,不是 bug,原因有两个:
- UTM 参数需要主动加:只有当你自己在链接上加了
utm_参数,才有归因数据。目前站点没有做任何带 UTM 的站外投放,所以面板为空。 - 普通访问不带 UTM:用户直接输网址、从搜索引擎点进来、站内跳转,都没有
utm_参数,只记在「来源(Referrers)」里,不进 UTM 面板。
6.3 UTM 与「来源」面板的区别
| 面板 | 数据来源 | 是否需要操作 |
|---|---|---|
| 来源(Referrers) | 自动记录用户从哪点进来 | 不需要,自动有 |
| UTM | 只记录带 utm_ 参数的链接 | 需要主动在链接上加 utm 参数 |
6.4 什么时候用
站外引流时才有意义:
- 在知乎/CSDN/公众号文章里放带 UTM 的链接 → 对比哪个平台效果好
- 付费推广 → 看 ROI
- 邮件营销 → 看点击来源
现阶段未做站外投放,UTM 面板为空属正常,无需处理。
七、常见坑
| 坑 | 说明 |
|---|---|
| 后台 Overview 为 0 | ① 还没用浏览器访问过主站页面(不是后台);② 后台页面本身不含埋点;③ 时间区间/时区没选对(容器默认 UTC) |
| Performance 面板无数据 | Web Vitals(LCP/INP/CLS/FCP/TTFB)不是默认采集的——埋点标签需加 data-performance="true"(部分版本文档写作 data-web-vitals="true",以实际 tracker 为准);否则数据库只有 pageview/自定义事件 |
| 时区不一致 | Umami 容器时区默认 UTC,与宿主 CST(+8) 不同,看统计时注意按正确时区切换 |
| 爬虫不计入 | Umami 只统计执行了 JS 的浏览器,curl/脚本/搜索引擎爬虫默认不进数据——这不是 bug |
| 跨域采集 | script.js 从主站跨域加载到 analytics.example.com,需保证 API 响应正确的 CORS 头 |
| 网站 ID 不匹配 | 埋点里的 data-website-id 必须与后台网站的 id 一致,否则事件被丢弃 |
| 广告拦截器 | 部分拦截插件会屏蔽第三方统计脚本,导致该用户不计数(GoAccess 不受影响) |
七、交叉引用
- 同类工具对比:GoAccess —— 服务器日志分析的流量仪表盘,与 Umami 是互补的两条统计路线
- 反代与证书:Umami 由 nginx 反向代理 + Let's Encrypt 证书提供 HTTPS,与主站共用一套反代架构
- 防爬监控:Umami 的"人视角"需配合 GoAccess 的"机器视角"来区分真实用户与爬虫
- 事后复盘:sar 看系统资源历史,GoAccess/Umami 看访问流量历史
一句话总结:Umami 是一条"浏览器埋点 → 事件上报 → 落库 → 查询渲染"的 Web 流量分析链路——靠网页里一段
script.js采集真实用户行为并写入 PostgreSQL,由 nginx 反代 + HTTPS 提供接入,与靠读服务器日志的 GoAccess 形成"人视角 vs 机器视角"的互补,是自托管、隐私友好、免 Cookie 的轻量版 Google Analytics。