Umami 自托管：无 Cookie 站点统计的部署、对比与局限

Umami 是一个用 TypeScript 写的开源网站统计服务，常被当作 Google Analytics 的轻量替代。它不往访客浏览器里写 Cookie，数据全部落在自己的 PostgreSQL 中，一个应用容器加一个数据库就能跑起来。下面按项目定位、Docker 部署、埋点方式、同类对比和局限逐块讲。

Umami 是什么：一个跑在 Postgres 上的统计服务

它的采集范围刻意做得窄：页面浏览、会话、来源、浏览器与设备、国家地区，再加上你自己声明的事件。项目在 GitHub 仓库里的自我介绍是不使用 Cookie、不做监控，除非你主动传入身份标识，否则不认定访客是谁。这让数据表结构保持简单，也让“这个访客是谁”变成一种近似判断。

项目以 MIT 许可开源，主体是一个 Next.js 应用，只依赖 PostgreSQL，官方要求 12.14 及以上版本。v3 是一次大改版：报表从一张大屏拆成独立页面，引入分群、短链与像素，同时把 MySQL 支持整段移除，只留 Postgres。

版本节奏偏快。当前稳定版是 2026 年 10 月 23 日发布的 v3.4.1。这一版属于安全修补，升级了 Next.js、React 与 Docker 基础镜像，官方建议所有自托管实例跟上。上一版 v3.4 带来了图表标注、MCP 接口和账号级 API 密钥。

Docker 部署：一个 compose，四个变量

按 官方安装文档，仓库自带一份 compose 文件，里面只有两个服务：应用本体和 postgres:15-alpine。按下面顺序走，通常十几分钟能跑通。

1. 准备一台装了 Docker 的 Linux 机器，取回仓库里的 docker-compose.yml。
2. 把 APP_SECRET 换成随机串，用 openssl rand -hex 32 生成；打算开两步验证，再填 TWO_FACTOR_ENCRYPTION_KEY，同样是 64 位十六进制。
3. 改掉示例里的数据库账号密码，DATABASE_URL 跟着改，别沿用 compose 里那组弱口令。
4. 执行 docker compose up -d，应用默认监听 3000 端口。
5. 等健康检查通过，它探测的是 /api/heartbeat。
6. 浏览器打开面板，用 admin 与 umami 登录，先改掉密码。

环境变量页写得很明确：真正必填的只有 DATABASE_URL，其余都有默认值。但这不等于其余可以不管，APP_SECRET 决定登录令牌的签名，用默认值等于把会话交给别人算。从源码构建的话，文档要求 Node 20.19 以上，推荐 22 LTS。

套反向代理后还有一步容易漏。访客 IP 默认取直连地址，经过 Nginx 或 CDN 就变成内网 IP，国家与城市统计会整片失真。要么设 CLIENT_IP_HEADER 指定取哪个头，要么用 TRUSTED_PROXIES 列出代理网段，让它从右往左跳过可信地址。

生产环境建议固定版本标签，不要图省事写 latest。v3 属于破坏性升级，标签一浮动，某天重启就可能撞上数据库结构变更。

埋脚本与事件：一个 script 能拿到什么

在面板里新建站点，会得到一个 website-id。把官方脚本挂到页面上，src 指向自己实例的 /script.js，带上 data-website-id，页面浏览随即开始入库。属性表比想象中长，常用的几个按需开启即可。

自定义事件有两条路。给按钮加 data-umami-event 前缀的属性，点击即上报。也可以在代码里调 umami.track('signup-button', { plan: 'pro' })，第二个参数会作为事件数据存下来。已登录的场景可用 umami.identify() 把匿名浏览与账号行为接成一条会话，v3.3 起这条链路做了缝合。

还有两个变量专治广告拦截。TRACKER_SCRIPT_NAME 可以把 script.js 改名，COLLECT_API_ENDPOINT 可以把上报路径从 /api/send 换掉。改完记得清缓存再验证，拦的是路径特征而不是产品本身。

和 Plausible、Matomo 的差别

这几个项目经常出现在同一张推荐表里，实际差别在存储与运维成本上，功能清单反而接近。许可与版本时点，可以和这篇三方对比记录交叉核对。

Umami 只压一个 Postgres，备份就是一份数据库快照。Plausible 社区版要同时照顾 Postgres 与 ClickHouse，机器规格和调优都上一个台阶，换来的是大数据量下的查询速度。Matomo 历史最长，报表与插件齐全，代价是维护 PHP 环境与一串扩展。

功能边界也有落差。Plausible 社区版把漏斗、电商收入目标、单点登录留在云端。Umami 在 v3 之后自带漏斗、留存、热图与会话回放，开源版与云版的差距主要落在额度与团队能力上。选型时先确认要不要漏斗，再算愿不愿意多养一个 ClickHouse。

局限：它不解决的问题

无 Cookie 是有代价的。匿名标识的盐默认每月轮换一次（SALT_ROTATION=month），跨月的回访、跨设备的同一个人都会被拆成两段。这类指标只能当趋势看，别拿去做结算依据。

• 只支持 PostgreSQL。仍停在 MySQL 上的老实例，升级 v3 之前要先按官方迁移指南搬库。
• 没有独立时序库。数据量涨上来后，查询靠 Postgres 的索引与连接池硬扛，Redis 只是可选的缓存层，不改变存储模型。
• 不覆盖广告侧。GA4 那套受众导出、广告归因、与投放平台的双向同步，它都不做。
• 自托管不等于合规。URL 参数、事件属性、identify 传入的身份都可能夹带个人信息，data-exclude-search 与 IGNORE_IP 该开就开。
• 默认安全项要自己补。默认密码要改，APP_SECRET 要换，两步验证得先配好加密密钥才能启用。
• 脚本会被拦截器挡。改脚本名与上报路径能缓解，但缓解不等于绕过。

和站内写过的 Stirling PDF 自托管不同，Umami 没有把核心功能做成付费墙，MIT 许可下自托管功能是完整的。代价转移到了运维上：升级要自己盯，备份要自己做，出问题没有工单可提。

适合谁，怎么起步

适合个人博客、内容站，以及想自己掌握数据的小团队产品。能撑多大量取决于机器规格与查询优化，上线前按自己的流量压一遍更稳妥。不适合需要广告投放归因、或要求跨设备精确识别用户的场景。

起步按这个顺序比较稳。先单机跑通 compose，改掉默认密码与密钥，再挂测试站确认上报正常；随后配好反向代理的 IP 头，核对国家城市，最后接入正式站。机器若已经在用 Coolify 这类面板，可以直接把 compose 交给它管。服务器本身的负载，则交给 Beszel 轻量服务器监控那类工具看，站内两篇都写过具体步骤。

常见问题

能不能完全替代 GA4？流量、来源、事件、转化这几个层面可以，广告投放与受众那部分不能，硬要迁移会丢掉投放侧的闭环。

没有 Cookie 怎么区分新老访客？靠匿名标识加每月轮换的盐做近似判断，准确度足够看趋势，不足以做用户级核算。要在登录后接上真实身份，得自己调用 identify。

数据量大了要换库吗？官方没有提供 ClickHouse 或时序库的迁移路径。常见做法是先优化 Postgres、加缓存、按需归档旧数据，再按实际压测结果决定要不要拆分。

相关地址

以下为文中项目的官方入口，版本号、文档与下载以这些页面为准。

• Umami（GitHub 仓库）：https://github.com/umami-software/umami
• Umami（官网）：https://umami.is/
• Umami（安装文档）：https://umami.is/docs/install
• Umami（环境变量）：https://umami.is/docs/environment-variables
• Umami（Release 列表）：https://github.com/umami-software/umami/releases
• Plausible（GitHub 仓库）：https://github.com/plausible/analytics
• Matomo（GitHub 仓库）：https://github.com/matomo-org/matomo