Umami网站分析 — Umami隐私友好分析¶

一句话概述：Umami 是开源、隐私友好的网站分析工具，MIT 许可证完全免费，追踪脚本不到 2KB，支持自定义事件和漏斗分析，是 Google Analytics 最受欢迎的开源替代之一。

核心知识点速查表¶

概念	白话解释
Umami	日语"鲜味"，一个简洁的网站分析工具
无 Cookie	不使用 Cookie，不需要同意横幅
自定义事件	追踪按钮点击、注册等特定用户行为
漏斗分析	看用户从哪一步开始流失（注册→填表→付费）
用户留存	看多少用户在 N 天后还会回来

当前版本信息（2026年）¶

信息	详情
最新版本	v3.1.0（2026年4月16日）
技术栈	Next.js + PostgreSQL/MySQL
追踪脚本	<2KB
许可证	MIT（完全开源）
GitHub Stars	36,400+
官网	https://umami.is

安装配置¶

自托管部署（Docker Compose）¶

# docker-compose.yml
version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest  # 使用 PostgreSQL 版本
    ports:
      - "3000:3000"                    # 端口映射
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami  # 数据库连接
      DATABASE_TYPE: postgresql        # 数据库类型
      APP_SECRET: your-random-secret   # 应用密钥（改成随机字符串）
    depends_on:
      db:
        condition: service_healthy
    restart: always

  db:
    image: postgres:16-alpine          # PostgreSQL 数据库
    environment:
      POSTGRES_DB: umami               # 数据库名
      POSTGRES_USER: umami             # 用户名
      POSTGRES_PASSWORD: umami         # 密码
    volumes:
      - umami-db:/var/lib/postgresql/data  # 数据持久化
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: always

volumes:
  umami-db:

# 启动
docker compose up -d

# 访问 http://localhost:3000
# 默认账号：admin / umami
# 首次登录请修改密码

添加网站追踪¶

<!-- 在 Umami 中添加网站后，获取追踪代码 -->
<!-- 粘贴到你网站的 <head> 中 -->
<script defer
  src="https://your-umami.com/script.js"
  data-website-id="your-website-id">
</script>

云服务（Umami Cloud）¶

# 免费：100K 事件/月
# Pro：$20/月（1M 事件/月）
# 注册：https://cloud.umami.is

基本使用¶

仪表板¶

# Umami 仪表板显示：
# - 页面浏览量（Pageviews）
# - 独立访客（Visitors）
# - 访问量（Visits/Sessions）
# - 跳出率（Bounce Rate）
# - 平均停留时间
# - 实时在线人数
# - 流量来源（Referrers）
# - 热门页面
# - 国家/城市
# - 浏览器/OS/设备
# - UTM 参数

自定义事件追踪¶

<!-- HTML 属性方式追踪按钮点击 -->
<button data-umami-event="signup-click"
        data-umami-event-plan="premium">
  注册高级版
</button>

<!-- 追踪链接点击 -->
<a href="/download"
   data-umami-event="file-download"
   data-umami-event-file="report.pdf">
  下载报告
</a>

// JavaScript API 方式
umami.track('signup', { plan: 'premium' });        // 自定义事件
umami.track('purchase', { amount: 99, currency: 'CNY' });  // 购买事件

漏斗分析（v3 新功能）¶

# 在 Umami Web UI 中设置漏斗：
# Reports → Create Report → Funnel
# 定义步骤：
# Step 1: 访问首页 (/)
# Step 2: 访问产品页 (/products)
# Step 3: 加入购物车 (add-to-cart 事件)
# Step 4: 完成支付 (purchase 事件)
# → 可视化看到每步的转化率和流失率

API 使用¶

# 获取认证 Token
curl -X POST https://your-umami.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

# 获取网站统计数据
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-umami.com/api/websites/WEBSITE_ID/stats?startAt=1704067200000&endAt=1706745600000"

# 获取活跃访客
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-umami.com/api/websites/WEBSITE_ID/active"

高级用法¶

多网站管理¶

# Umami 支持在一个实例中管理多个网站
# 每个网站有独立的 website-id
# 可以创建团队，给不同成员分配不同网站的查看权限

防广告拦截¶

# Umami 的追踪脚本可能被 Ghostery 等拦截
# 解决方案：重命名脚本路径

# 方法1：Nginx 反向代理
# location /stats/script.js {
#     proxy_pass https://your-umami.com/script.js;
# }

# 方法2：在 Umami 配置中自定义脚本名
# 设置环境变量 TRACKER_SCRIPT_NAME=custom-name

数据导出¶

# 通过 API 导出数据
# 获取页面浏览数据
curl -H "Authorization: Bearer TOKEN" \
  "https://your-umami.com/api/websites/ID/pageviews?startAt=START&endAt=END"

# 获取事件数据
curl -H "Authorization: Bearer TOKEN" \
  "https://your-umami.com/api/websites/ID/events?startAt=START&endAt=END"

常见报错与解决¶

问题	原因	解决方案
数据不显示	脚本未加载	F12 检查 Network 和 Console
被 Ghostery 拦截	默认脚本名被识别	自定义脚本名或反向代理
数据库连接失败	DATABASE_URL 错误	检查连接字符串格式
内存不足	访问量太大	增加服务器内存或用 PostgreSQL
API 返回 401	Token 过期	重新登录获取 Token

速查表¶

# ===== Docker 管理 =====
docker compose up -d              # 启动
docker compose down               # 停止
docker compose pull               # 更新镜像
docker compose logs umami         # 查看日志

# ===== 环境变量 =====
DATABASE_URL=postgresql://...     # 数据库连接
DATABASE_TYPE=postgresql          # 数据库类型
APP_SECRET=random-string          # 应用密钥
TRACKER_SCRIPT_NAME=custom        # 自定义脚本名
DISABLE_TELEMETRY=1               # 禁用遥测

<!-- ===== 追踪代码 ===== -->
<!-- 基本追踪 -->
<script defer src="URL/script.js" data-website-id="ID"></script>

<!-- 事件追踪 -->
<button data-umami-event="event-name">Click</button>
<script>umami.track('event', {key: 'value'})</script>

特性	Umami	Plausible	Matomo	PostHog
许可证	MIT（最自由）	AGPL	GPL	MIT
免费云服务	✅ 100K/月	❌	❌	✅ 1M/月
自托管难度	低	低	中	高
漏斗分析	✅ v3	基本	✅	✅
用户留存	✅ v3	❌	✅	✅
数据库	PG/MySQL	PG+ClickHouse	MySQL	PG+ClickHouse
脚本大小	<2KB	<1KB	~22KB	~100KB

Umami网站分析 — Umami隐私友好分析¶

核心知识点速查表¶

当前版本信息（2026年）¶

安装配置¶

自托管部署（Docker Compose）¶

添加网站追踪¶

云服务（Umami Cloud）¶

基本使用¶

仪表板¶

自定义事件追踪¶

漏斗分析（v3 新功能）¶

API 使用¶

高级用法¶

多网站管理¶

防广告拦截¶

数据导出¶

常见报错与解决¶

速查表¶

同类工具对比¶