Umami 介绍与选型指南

目标：面向需要自建网站流量统计、又对隐私合规（GDPR/无 Cookie）有要求的工程师，系统介绍 Umami 的定位、架构、功能、适用边界，并与 Google Analytics 4、Matomo、Plausible 等同类产品做选型对比；全文命令与回显均在 Umami 3.4.0（Ubuntu 22.04 LTS，x86_64，服务监听 0.0.0.0:3000，对外访问端口 13000，数据库 PostgreSQL 16.15）实测通过。

一、环境信息

本文所有示例所依赖的实测环境如下，读者对照命令回显时应保证关键项一致：

操作系统：Ubuntu 22.04 LTS（x86_64）
统计服务：Umami 3.4.0（官方发布 tag v3.4.0，2026-09-17 发布；服务内部监听 0.0.0.0:3000，本环境对外访问端口为 13000）
数据库：PostgreSQL 16.15（Umami 亦支持 MySQL/MariaDB）
运行时：Next.js 16.3.4（服务端日志实测回显 ▲ Next.js 16.3.4）+ Node.js 22.23.2
管理账号：admin / q1w2e3r4（演示口令，首次启动自动创建，默认口令为 umami，登录后已改密）
采集端点：/api/send（POST，JSON），统计脚本 /script.js（实测 4773 字节，MD5 7edb400174f8178e695beb2ad82c40b4）
社区数据：GitHub 仓库 umami-software/umami，2026-10-17 实查 stars 39,432 / forks 8,333 / open issues 108

💡 技术拓展：「网站流量统计」目前有三条主流技术路线，选型前先分清——

路线原理代表产品特点
页面埋点 JS 页面加载时执行脚本向采集端点上报 GA4、Matomo、Plausible、Umami 指标丰富，能统计事件/转化；受广告拦截器影响
服务器日志分析解析 Web 服务器 access log GoAccess、AWStats 不侵入页面、不丢请求；但无法统计 SPA 路由、事件与真实访客
产品分析（CDP）埋点 + 用户行为全量入库 + 会话回放 PostHog、Mixpanel 面向增长分析，体量与成本远高于纯流量统计

本文选型对象为 Umami，属于「隐私优先的页面埋点式流量统计」：面向"想知道流量从哪来、页面表现如何、活动转化如何"的站点运营场景，不需要 Cookie 授权横幅，也不收集个人身份信息。

路线	原理	代表产品	特点
页面埋点 JS	页面加载时执行脚本向采集端点上报	GA4、Matomo、Plausible、Umami	指标丰富，能统计事件/转化；受广告拦截器影响
服务器日志分析	解析 Web 服务器 access log	GoAccess、AWStats	不侵入页面、不丢请求；但无法统计 SPA 路由、事件与真实访客
产品分析（CDP）	埋点 + 用户行为全量入库 + 会话回放	PostHog、Mixpanel	面向增长分析，体量与成本远高于纯流量统计

二、软件概述

Umami 是一个开源的隐私优先（privacy-first）网站分析平台，2020 年 7 月创建（GitHub 仓库创建时间 2020-07-17，实查），采用 MIT 许可证发布。官方对它的定位描述是："Umami 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."（流量、活动、行为、转化与收入一站式，无 Cookie、无监控，可自托管或上云）。

它的核心卖点是三个"替代"：替代 Google Analytics 4 时不需要 Cookie 授权横幅（不使用 Cookie、不采集跨站个人身份）、替代 Matomo 时部署更轻（一个 Next.js 应用 + 一个关系库，无插件体系）、替代 Plausible 时可完全自托管且不限网站数与事件数。Umami 官方镜像同时提供 PostgreSQL 与 MySQL 两种数据库变体，单一服务进程即可运行，非常契合单台服务器从 0 到 1 自建。

版本与发布节奏（2026-10-17 实查 GitHub Releases）：

最新稳定版：v3.4.0（2026-09-17 发布），本文实测版本即 3.4.0（服务内 /app/package.json 版本号实测回显 3.4.0）；
上一批版本：v3.3.1（2026-08-20）、v3.3.0（2026-08-12）、v3.2.0（2026-06-24）、v3.1.0（2026-04-16）；
2.x 维护分支止于 v2.20.2（2025-12-12），当前主线为 3.x；
发布节奏约为每 1~2 个月一个 minor 版本，GitHub Releases 不附二进制附件（实测 assets: 0），交付物为 Docker 镜像与源码。

一句话概括定位：如果你想要"一个 MIT 协议、一个服务进程、一个关系库"的自建统计平台，能接受自己嵌码采集，并且不被广告拦截器完全拦截也能接受（支持自定义脚本名/端点规避），Umami 是当前自托管路线里工程复杂度最低的选项之一。

三、核心架构

理解 Umami 的架构要抓住四层：采集层、应用层、存储层、会话识别与地理定位机制。本节每一层都给出实测依据。

3.1 采集层：/script.js + /api/send 上报协议

Umami 在被统计页面嵌入一段统计脚本（默认路径 /script.js），脚本采集页面上下文后 POST 到采集端点（默认 /api/send）。实测脚本内容（响应 200，4773 字节，单行压缩）：

curl -s http://localhost:13000/script.js | head -c 260

实测回显（首段节选）：

!function(){"use strict";(t=>{const{screen:{width:e,height:a},navigator:{language:n,doNotTrack:r,msDoNotTrack:i},location:o,document:c,history:s,top:d,doNotTrack:l}=t,{currentScript:u,referrer:f}=c;if(!u)return;const{hostname:h,href:m,origin:p}=o;

从脚本源码可确认其上报行为：采集 screen（分辨率）、navigator.language（语言）、document.title、location.hostname、当前路径与 referrer，组装为 payload 后执行 fetch(R,{keepalive:!0,method:"POST",body:JSON.stringify({type:a,payload:e}),headers:{"Content-Type":"application/json","x-umami-website-id":S,"x-umami-hostname":h,...}})。也就是上报协议为 POST JSON {"type":"event","payload":{...}}，并携带 x-umami-website-id 与 x-umami-hostname 两个请求头。实测一次真实上报：

curl -s -X POST http://localhost:13000/api/send \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36' \
  -d '{"type":"event","payload":{"website":"bd69fdbf-f8bd-48c3-93d4-877c51c93fb4","hostname":"demo.example.com","language":"zh-CN","referrer":"https://www.google.com/","screen":"1920x1080","title":"首页","url":"/home"}}'

实测回显（HTTP 200，JWT 字段较长做截断展示）：

{"cache":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3ZWJzaXRlSWQiOiJiZDY5ZmRiZi1mOGJkLTQ4YzMtOTNkNC04NzdjNTFjOTNmYjQi...（截断）","sessionId":"fde4be7f-48eb-53e3-bf52-aeec53107c","visitId":"e6253175-384d-55a1-b122-820fc700e3e2"}

要点：响应体里的 cache 是 Umami 签发的站点级缓存令牌（JWT），浏览器下次上报时会通过 x-umami-cache 头带回，用于减少服务端重复会话计算；sessionId/visitId 标识本次访问归属的会话与访问。上报协议的完整字段与更多实测见《Umami 3.4 API 使用详解》。

3.2 应用层：单体 Next.js 应用

Umami 服务端是一个单体 Next.js 应用（实测启动日志回显 ▲ Next.js 16.3.4、✓ Ready in 0ms），同一进程同时承载三部分：

Web 控制台：React 前端 + 服务端渲染，提供网站列表、实时面板、报表（漏斗/留存/收入/旅程/归因/热图）与系统设置；
管理 API 与采集 API：/api/websites、/api/me 等管理接口走登录令牌（Bearer JWT），/api/send 采集接口无登录态；
遥测与升级检查：默认情况下控制台页面会加载 /telemetry.js，向官方遥测像素 https://i.umami.is/a.png?v=3.4.0（实测回显）发送一次匿名版本上报；用 DISABLE_TELEMETRY=1 或 PRIVATE_MODE=1 可关闭（实测关闭后 /telemetry.js 返回 /* telemetry disabled */）。

应用通过 Prisma ORM 访问数据库（启动日志实测回显 Loaded Prisma config from prisma.config.ts、Datasource "db": PostgreSQL database "umami", schema "public" at "umami-db:5432"、26 migrations found in prisma/migrations），首次启动自动执行全部迁移并创建初始管理员。

3.3 存储层：关系库单库存储 + 可选 Redis

所有数据（用户、网站、会话、事件、事件属性、报表定义、API Key 等）都存在一个关系库里，实测 PostgreSQL 中核心表包括 user、team、website、website_event、session、session_data、event_data、report、api_key 等。页面浏览（pageview）与事件（event）都落在 website_event 一张表（eventType 区分：1 为浏览，2 为命名事件）。

从 v3.0.1 起 Umami 支持可选的 REDIS_URL，用于缓存与多实例协调；不配置时相关特性关闭，单实例部署无需 Redis。

💡 技术拓展：同为"分析数据落关系库"，与专用 OLAP 引擎的取舍——

方案代表写入与聚合运维复杂度
关系库单库 Umami（PG/MySQL）中小流量足够，索引聚合低，单库备份即全量备份
专用 OLAP PostHog（ClickHouse）海量事件聚合快高，多组件栈
嵌入式分析库 Plausible（ClickHouse）中大流量中

Umami 选择了最朴素的关系库路线：换来的是"一个库、一份备份、一条迁移命令"的极低运维成本，代价是超大数据量（日千万级事件）下的聚合性能需要自己扩容数据库。本文与官方推荐一致采用 PostgreSQL 16。

方案	代表	写入与聚合	运维复杂度
关系库单库	Umami（PG/MySQL）	中小流量足够，索引聚合	低，单库备份即全量备份
专用 OLAP	PostHog（ClickHouse）	海量事件聚合快	高，多组件栈
嵌入式分析库	Plausible（ClickHouse）	中大流量	中

3.4 会话识别与地理定位机制

Umami 不用 Cookie 也不存原始 IP，而是对来源 IP + User-Agent + hostname 做哈希生成匿名会话标识，并用可配置的盐值轮换（SALT_ROTATION，默认 month）防止长期跟踪。实测验证：同一 UA 重复上报 /home 与 /docs 两次，两次响应返回同一 sessionId（5e25034a...），说明会话按 IP+UA+hostname 聚合。

地理定位支持两种来源（可并用）：CDN/反代注入的地理位置头（如 Cloudflare 的 CF-IPCountry），或本地 MaxMind 兼容 MMDB 库（GEO_DATABASE_URL 指定下载地址）。两者都没有时国家维度为空——实测未配置 GeoIP 库时 metrics?type=country 返回 []，这是预期行为而非故障。

四、功能特性

以下特性均在 3.4.0 实例上核实（控制台与 API 双通道）：

无 Cookie、无个人身份采集：不设 Cookie，不存原始 IP，GDPR/CCPA 合规友好，通常可免除 Cookie 横幅；
多网站、多团队：单实例不限网站数（实测连续创建两个站点均成功）；支持 Teams 协作与权限分级（admin/user 角色实测）；
实时面板：/api/websites/<id>/active 实时活跃访客（实测上报后立即返回 {"visitors":3}）；
页面与来源分析：路径、来源站点、浏览器/操作系统/设备/语言维度（实测 metrics?type=path|referrer|browser|os|device|language 全部 200 并返回计数）；
UTM/活动追踪：自动解析 utm_* 参数（官方常量含 UTM_PARAMS: ["utm_campaign","utm_content","utm_medium","utm_source","utm_term"]）；
事件与自定义属性：/api/send 支持 name + data 自定义事件属性（实测上报 download-doc 事件后 metrics?type=event 返回 [{"x":"download-doc","y":1}]）；
报表体系：漏斗（funnels）、留存（retention）、收入（revenue）、旅程（journeys）、归因（attribution）、热图（heatmaps）、UTM 报表（API 路由实测存在，均在 /api/websites/<id>/ 前缀下）；
开放 API：完整 REST API（本系列有 API 专篇实测）+ API Key 认证（实测创建 umami_ 前缀密钥并以 Bearer 方式调用成功）；
MCP 端点（v3.4 新增）：MCP_ENABLED=1 后在 /mcp 暴露 Model Context Protocol 端点，可让 AI 助手直接查询统计数据（官方文档标注 v3.4.0 引入）；
两步验证：v3.3.0 起支持 2FA（/api/2fa/* 路由实测存在，需先配置 TWO_FACTOR_ENCRYPTION_KEY）；
多语言界面：控制台支持多语言（含中文）。

五、快速开始（最小可用示例）

本节给出一条最快路径：Docker Compose 启动 → 登录改密 → 建站拿 website id → 嵌码/直报 → 看统计增长。完整部署细节（镜像选型、数据目录、备份升级）见《Umami Docker Compose 部署指南》。

5.1 最小部署

在一台装有 Docker 的 Ubuntu 22.04 服务器上创建 compose.yml：

services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - "13000:3000"
    environment:
      DATABASE_URL: postgresql://umami:q1w2e3r4@umami-db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: 9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d
    depends_on:
      umami-db:
        condition: service_healthy
  umami-db:
    image: postgres:16
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: q1w2e3r4
    volumes:
      - /opt/data/umami-pg:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 5s
      timeout: 5s
      retries: 10

docker compose up -d
curl -s http://localhost:13000/api/heartbeat

实测回显：

{"ok":true}

5.2 登录并改密

首次启动会在数据库自动创建初始管理员 admin / umami（全新空库实测：启动后 user 表自动出现 admin 行，POST /api/auth/login 用 admin/umami 返回 200 与令牌）。登录后立即改密：

TOKEN=$(curl -s -X POST http://localhost:13000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"umami"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])')
curl -s -X POST http://localhost:13000/api/me/password \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"currentPassword":"umami","newPassword":"q1w2e3r4"}'

实测回显（HTTP 200，改密后旧口令登录 401、新口令 200）：

{"id":"41e2b680-648e-4b09-bcd7-3e2b10c06264","username":"admin","role":"admin","createdAt":"2026-10-17T09:29:10.286Z"}

5.3 建站与上报

curl -s -X POST http://localhost:13000/api/websites \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Demo Site","domain":"demo.example.com"}'

实测回显（HTTP 200，拿到 website id，节选）：

{"id":"bd69fdbf-f8bd-48c3-93d4-877c51c93fb4","name":"Demo Site","domain":"demo.example.com","resetAt":null,"userId":"41e2b680-648e-4b09-bcd7-3e2b10c06264","createdAt":"2026-10-17T11:00:12.086Z","shareId":null,...}

在目标页面嵌码（正式网站用法）：

<script defer src="http://your-umami-host:13000/script.js" data-website-id="bd69fdbf-f8bd-48c3-93d4-877c51c93fb4"></script>

无页面环境可直接按上报协议打点验证（连续上报 3 个不同来源，HTTP 均为 200）：

WID=bd69fdbf-f8bd-48c3-93d4-877c51c93fb4
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:13000/api/send \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/131.0.0.0 Safari/537.36' \
  -d '{"type":"event","payload":{"website":"'$WID'","hostname":"demo.example.com","language":"zh-CN","referrer":"https://www.google.com/","screen":"1920x1080","url":"/home"}}'

实测回显：200（响应体含 cache/sessionId/visitId）。

5.4 验证统计增长

curl -s -H "Authorization: Bearer $TOKEN" \
  "http://localhost:13000/api/websites/$WID/stats?startAt=0&endAt=$(date +%s000)"

实测回显（上报前 pageviews:0，连续上报多个不同来源后增长到 8，独立访客 5）：

{"pageviews":8,"visitors":5,"visits":5,"bounces":3,"totaltime":61,"comparison":{"pageviews":0,"visitors":0,"visits":0,"bounces":0,"totaltime":0}}

💡 说明：stats 接口存在秒级缓存，上报后立即查询可能看到 0，等待数秒再查即为最新值（实测：立即查返回全 0，约 3 秒后查询返回 8）。实时活跃数无此延迟，/api/websites/<id>/active 上报后立即返回 {"visitors":3}。

六、适用场景与限制

适用场景（实测可支撑）：

企业官网/产品站/博客的流量统计：页面浏览、来源、设备、地理维度一应俱全，嵌一行 <script> 即接入；
营销活动归因：UTM 参数自动解析，配归因/收入报表可度量投放效果；
产品行为分析（轻量）：自定义事件 + data 属性可承载按钮点击、下载、注册等转化指标；
对隐私合规要求高的站点：无 Cookie、无 PII、可完全内网部署（PRIVATE_MODE=1 切断全部外联，实测遥测随之关闭）；
多产品线团队共用：Teams 与角色分离，API Key 供自动化查询。

限制与注意（选型前必须接受）：

无官方单机二进制分发：GitHub Releases 无附件（实测 assets: 0），部署走 Docker 镜像或源码构建（Node.js + pnpm），裸机安装不如传统服务顺滑；
海量事件聚合依赖数据库能力：单库架构在日均千万级事件时需要自行给 PostgreSQL 扩容/分区，官方未内置分布式方案；
广告拦截器可能拦截 /script.js 与 /api/send：官方提供 TRACKER_SCRIPT_NAME 与 COLLECT_API_ENDPOINT 规避（两者均在 3.4.0 实测生效），但无法保证全部拦截规则都被绕开，统计必然存在低估；
地理定位需自配数据源：默认无 GeoIP 库时国家维度为空（实测 type=country 返回 []），需要配置 GEO_DATABASE_URL（MaxMind 兼容 MMDB）或使用 CDN 地理头；
报表/回放等高级能力部分依赖云版：会话回放（session replay）等重能力在自托管版需额外组件与许可，选型时以官方文档的功能页为准。

七、同类选型对比

从"自托管隐私统计"场景出发，与四款同类产品对比（社区数据 2026-10-17 实查或为官方公开口径）：

维度	Umami	Plausible	Matomo	Fathom	GA4
许可	MIT	AGPLv3（部分功能商业）	GPLv3	商业	闭源
自托管	支持，一进程一库	社区版受限/单机版收费	支持，PHP+MySQL	支持（商业授权）	不支持，仅云
Cookie/横幅	无需	无需	需（或配置无 Cookie 模式）	无需	需
事件与自定义属性	不限量	事件计费	不限量	事件计费	有配额
数据库	PostgreSQL/MySQL	ClickHouse	MySQL/MariaDB	PostgreSQL	Google 内部
报表（漏斗/收入等）	内置	部分（付费档）	插件体系	部分	内置
API 开放度	全量 REST + API Key	全量	全量	有限	全量但绑定生态
典型部署体量	Next.js + 1 关系库	多组件（含 ClickHouse）	PHP + MySQL + 定时任务	单进程	—
GitHub stars（2026-10-17）	39,432	25,000+	20,000+	7,000+	—

关键差异与如何选：看三处——许可（MIT vs AGPL/商业）、部署体量（一进程一库 vs 多组件）、开放度（API 与 API Key 是否全量开放）。这三处 Umami 都占优，代价是高级报表深度不如 Matomo 插件生态。

社区活跃度与版本节奏（量化）：Umami 2020 年创建至今 6 年，star 39,432、fork 8,333、open issues 108（处理较及时），2026 年内发布 v3.1.0/v3.2.0/v3.3.0/v3.3.1/v3.4.0 共 5 个版本，节奏稳定在 1~2 月一版；同档 Plausible 社区活跃度相近，Matomo 体量更大但版本节奏更慢，Fathom 以商业授权为主。

兼容矩阵（Umami 3.4.0 实测/官方口径）：

数据库：PostgreSQL（推荐，本文实测 16.15）或 MySQL/MariaDB（官方提供 mysql-latest 镜像变体）；
运行环境：Docker（ghcr.io 官方镜像，postgresql/mysql 两族 tag）或源码构建（Node.js 22.x + pnpm）；
浏览器端：现代浏览器（脚本使用 keepalive fetch 上报）；
可选组件：Redis（v3.0.1+，缓存/协调，可选）、MaxMind 兼容 MMDB 地理库（可选）、MCP 客户端（v3.4.0+）。

选型结论：

要最低运维成本的完全自托管（一个进程 + 一个库 + MIT 许可）：选 Umami；
要开箱即用、不操心统计脚本被拦截且能接受单机版收费：选 Plausible；
要传统 PHP 栈、插件生态、已有 MySQL 运维经验：选 Matomo；
要行为分析/会话回放/产品分析（超出流量统计范畴）：选 PostHog；
能接受数据出境与 Cookie 横幅、重度依赖 Google 生态：GA4。

本文与整个 Umami 系列采用 Umami 3.4.0 + PostgreSQL 16 的组合，理由：MIT 许可无授权顾虑、部署拓扑最小（两条 docker run 等价命令即可复现）、API 全量开放便于自动化。

八、参考链接

官网：https://umami.is
官方文档（环境变量）：https://docs.umami.is/docs/environment-variables
GitHub 仓库：https://github.com/umami-software/umami
Releases：https://github.com/umami-software/umami/releases
相关文档：《Umami Docker Compose 部署指南》《GoAccess 介绍与选型指南》《Uptime Kuma 介绍与选型指南》