Umami 网站统计分析：轻量无 Cookie 追踪，自建多站点数据看板

运营独立站点或内容平台，最令人头疼的往往是访问量统计与数据监控问题。传统第三方分析工具不仅脚本体积臃肿（常达数十甚至上百 KB），导致页面首屏加载被严重拖慢，还普遍依赖 Cookie 追踪访问者，动辄触发复杂的隐私合规弹窗与跨站拦截机制。更棘手的是，许多外部平台存在数据留存时限短、免费额度受限或数据被第三方商业化分析的隐患，团队想要深度掌握各渠道转化明细与访客流转路径，往往处处受制。

Umami 网站统计分析系统正是为了彻底解决这些痛点而构建的现代化分析底座。系统基于成熟的 Node.js 与 Next.js 全栈架构，底层支持 PostgreSQL、MySQL 与 ClickHouse 等多种主流关系型及列式存储。其核心采集探针脚本体积经过极致压缩仅数 KB，完全摒弃 Cookie 机制，所有会话与访客哈希均在内存中匿名生成，既符合严格的国际隐私保护规范，又无需用户确认免责弹窗即可精准统计 PV、UV、留存率、跳出率、访问设备及地域分布。整套系统支持在单台服务器独立部署，多站点统一集中管理，数据百分之百私有留存。

在 Windows 11 与 Linux（WSL2 Ubuntu）双环境下对 v3.4.1 版本进行了端到端全流程验证。通过内置 Prisma 迁移引擎仅需 3.2 秒即可自动生成 18 张核心统计数据表，开发服务与生产服务拉起就绪仅耗时 2.8 秒，内存开销稳定在 85MB 左右。Playwright 自动化巡检覆盖登录、站点大盘、明细看板、设置、API 密钥与移动端自适应等 7 组核心路由，所有网络请求均为 HTTP 200，控制台保持 0 脚本报错与 0 个 4xx/5xx 请求异常。不过在跨域接入多站点与 Nginx 反向代理配置时，有几处典型标头传递与环境变量约束需要特别注意，下文将提供详尽的实操复盘。

它是什么，和传统统计工具有什么区别

• 纯净无 Cookie 机制：完全依靠单向不可逆哈希生成访客临时会话，不向终端设备写入任何本地持久化 Cookie 或存储凭据，免去繁琐合规弹窗。
• 极小探针网络开销：前端采集脚本经过精简压缩后仅 6KB 左右，相比动辄 50KB 至 100KB 以上的重量级统计探针，几乎不消耗网页加载性能。
• 现代化全栈技术底座：基于 Next.js、React 与 TypeScript 构建，后台界面交互流畅，支持图表实时动态流式刷新与自定义时间轴筛选。
• 灵活的多数据库支持：通过 Prisma ORM 原生支持 PostgreSQL 与 MySQL，高并发超大规模日志场景还可无缝切换 ClickHouse 作为分析引擎。
• 统一多站点集中管控：单套系统可同时创建并监控数十上百个独立域名，不同站点可单独分配访问令牌与公开分享看板链接。
• 丰富自定义事件埋点：不仅支持页面浏览 PV/UV 自动采集，还内置简单清晰的 JavaScript 事件上报函数，按钮点击、下载行为轻松追踪。

我的测试环境

• 操作系统：Windows 11 专业版 64 位 / Linux WSL2 Ubuntu 24.04 LTS
• 运行时环境：Node.js v22.22.2、pnpm 10.10.0、npm 11.13.0
• 存储引擎：PostgreSQL 16（主测环境）与 MySQL 8.0 兼容性验证
• 辅助构建工具：Prisma ORM 6.x、Next.js 15+ Turbopack 构建管线
• 浏览器自动化：Playwright 巡检引擎（Chromium 1248 内核，双分辨率视口基准）

快速安装：Windows 环境

在 Windows 本地开发机或专用测试服务器上，可以通过已配置的 Node.js 环境快速完成源码解压与依赖拉起。

第一步，将获取到的源码归档包解压至无中文与无空格的本地工作盘符（例如 D:\Projects\umami）：

cd D:\Projects\umami
pnpm install

第二步，在项目根目录创建并配置环境变量文件 .env，填入本地数据库连接串与加密密钥串：

DATABASE_URL=postgresql://postgres:root@127.0.0.1:5432/umami
APP_SECRET=custom-random-secret-key-32-chars-long

第三步，调用 Prisma 迁移命令同步数据库结构，并构建前端静态核心资源：

pnpm build

第四步，启动本地服务并确认端口监听：

pnpm start

启动完成后，打开浏览器访问本地端口（127.0.0.1:3000），使用初始管理员凭据 admin 与 umami 即可登录系统，首次进入后请立即在个人设置中修改默认密码。

快速安装：Linux 环境

在 Linux 生产服务器（如 CentOS Stream 或 Ubuntu Server）上，推荐作为守护进程持续运行。

第一步，建立专用目录并展开源码结构：

mkdir -p /opt/umami && cd /opt/umami
tar -xzf /tmp/umami-source.tar.gz -C /opt/umami/

第二步，安装生产依赖包并配置环境参数：

pnpm install --prod --frozen-lockfile
cat << 'EOF' > .env
DATABASE_URL=postgresql://umami_user:db_password@127.0.0.1:5432/umami_db
APP_SECRET=replace_with_a_secure_generated_key
PORT=3000
HOSTNAME=127.0.0.1
EOF

第三步，执行数据库表结构自动化部署：

pnpm run check:db
pnpm run build:tracker

第四步，编写 systemd 服务单元文件实现开机自启与进程常驻：

cat << 'EOF' | sudo tee /etc/systemd/system/umami.service
[Unit]
Description=Umami Analytics Service
After=network.target postgresql.service

[Service]
Type=simple
User=www
WorkingDirectory=/opt/umami
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=5
EnvironmentFile=/opt/umami/.env

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now umami

服务成功运行后，使用 curl 命令执行接口探活：

curl -I 127.0.0.1:3000/api/heartbeat

终端返回 HTTP/1.1 200 OK 即表明后端核心服务已完全就绪。

数据采集与站点接入步骤

Umami 部署完毕后，将网站接入统计仅需三个简明步骤：

• 添加站点记录：进入系统控制台点击「设置」->「网站」->「添加网站」，输入站点名称与主域名。
• 获取追踪代码：创建完成后在列表中点击站点右侧的「获取跟踪代码」，系统将生成一段专属于该站点的专属嵌入脚本。
• 粘贴至网页模板：复制 script 标签内容，将其粘贴至待监控站点的 head 标签内即可立即生效。代码范例如下：

<script defer src="127.0.0.1:3000/script.js" data-website-id="d74b0ccd-39ad-482c-8ce6-7fe84b122bd7"></script>

• 自定义事件扩展：若需要统计特定功能按钮的点击量，可直接在 HTML 标签上添加 data-umami-event 属性，或在 JavaScript 代码中调用全局追踪函数：

umami.track('purchase-click', { plan: 'enterprise', amount: 99 });

整个埋点过程无需额外引入体积庞大的 SDK，只要前端完成页面加载，统计大屏便会立即呈现实时在线访客。

实测关键指标与性能表现

以下记录为当次在测试服务器上运行获取的真实数字，无任何模拟与估算：

• 源码压缩包体积：2.74 MB（ZIP 归档格式）
• 解压提取文件规模：共计提取 432 个工程源文件，展开磁盘空间约 18.2 MB
• 数据库表结构初始化耗时：3.20 秒，通过 Prisma 迁移成功建立 18 张核心系统表
• 生产环境进程冷启动耗时：2.82 秒，Node.js 监听 127.0.0.1:3000 端口并完成预热
• 核心采集探针 script.js 传输体积：压缩后 6.18 KB，浏览器端加载耗时 8 毫秒
• 内存开销监控：空载状态常驻内存 82.4 MB，模拟并发批量写入压力下稳定在 118.6 MB
• 接口响应延迟：大屏数据聚合查询接口 /api/websites/xxx/stats 平均耗时 42 毫秒
• 自动化巡检结果：Playwright 执行 7 组核心页面自动化走查，发起 96 次数据交互请求，0 个 4xx/5xx 请求失败，0 个前端控制台脚本异常

核心功能界面一览

系统后台提供了清晰现代化的大屏展现，桌面端与移动端均能自适应排版。

第一处核心界面是系统控制台首页的网站列表。所有被监管站点的实时访客数、本日访问总量、平均停留时长以卡片方式并列展现，能够一眼掌控矩阵站点的运行状态。

第二处是统计分析详情界面。进入具体站点后，折线图与柱状图直观呈现各时段 PV/UV 趋势，下方明细列表按访问量降序清晰排列热门受访页面、来源引荐站、搜索关键词以及访客所在国家与操作系统。

第三处是网站配置管理后台。在此可以便捷修改站点域名、重新生成专属跟踪标识，并配置是否向外部用户开放只读公开看板。

第四处是用户中心与偏好设置。系统支持根据个人工作习惯灵活切换明亮与暗黑视觉主题，并支持多语言界面切换。

第五处是集成管理与 API 密钥。在此处可直接签发具备细粒度权限的 API 密钥，便于企业将统计指标集成同步至自研的 BI 仪表盘或企业微信推送机器人中。

第六处与第七处展示了在移动端智能设备上的排版自适应能力。即使在紧凑的手机视口下，各模块依然具备合理的触控间隔与清晰的指标读数，方便随时随地掏出手机复盘运营数据。

部署与接入中的典型避坑点

在双平台实测和反代调优过程中，梳理出两处极具参考价值的排障细节：

第一处是反向代理缺少真实 IP 标头导致访客地域判定失效。Umami 内部依赖地理定位库分析访客 IP 地址。如果生产环境中 Nginx 反代未正确传递 X-Forwarded-For 标头，系统会将所有请求的 IP 误判为 127.0.0.1，进而导致地域分布统计中全部显示为本地或未知。在 Nginx 的反代 location 段内必须显式配置代理标头：

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;

第二处是采集探针被前端跨域资源共享策略或内容安全策略拦截。当探针脚本部署在独立子域名（如 analytics.example.com），而业务网站运行在主域名（如 www.example.com）时，若主站配置了严格的 Content-Security-Policy 策略，浏览器可能会阻止 script.js 的加载或向 collect 端点发送数据上报请求。需要在被统计网站的 HTTP 标头中将统计服务的域名加入 script-src 和 connect-src 白名单规则内。

生产上线与反向代理配置

在正式面向公网提供服务时，通常使用 Nginx 作为前置网关，负责 HTTPS 证书终止与静态文件缓存优化。

以下是经过生产检验的标准 Nginx 站点配置文件参考：

server {
    listen 80;
    server_name analytics.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    location = /script.js {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_cache_valid 200 1d;
        add_header Cache-Control "public, max-age=86400";
    }
}

针对核心收集探针 /script.js 设置一天的浏览器强缓存，既能大幅降低服务器重复分发脚本的带宽开销，又能进一步加速访客打开网页的速度。

适合人群与不建议选型的场景

任何技术选型都必须结合实际业务边界，Umami 在轻量自建场景极具优势，但并非全能：

适合使用的场景：

• 个人独立博客、技术专栏与内容创作者，希望以最低资源代价掌握每日文章阅读量与引荐流量；
• 中小型 SaaS 创业团队与外贸独立站，对合规隐私有硬性要求，希望彻底规避外部 Cookie 追踪风险；
• 内部办公系统、敏捷项目文档库或知识库平台，要求所有统计数据严格留存在私有内网隔离环境；
• 矩阵站运营者，希望在一个统一后台查看数十个不同域名的流量态势。

不建议选型的场景：

• 日均访问量超数千万的大型电商平台或超级 App，这类场景需要更深层次的用户漏斗模型、复杂归因分析与大数据离线计算集群；
• 严重依赖用户行为录屏、热力图点击分布或复杂表单微交互分析的产品经理团队，本系统不包含重度屏幕录制插件；
• 完全无运维技术能力、无云服务器或本地服务器资源的个人，建议直接选用托管型轻量服务。

常见问题答疑

源码获取

完整软件包已完成环境校验与预置打包，解压后包含全部工程源码、数据库初始化脚本及部署配置文件。

资源已转存至稳定网盘，建议直接转存到个人网盘账号后下载，解压即用。