Umami | 隐私优先的开源网站分析平台，支持自托管部署

如果你希望掌握网站流量与转化数据，又不想把分析链路完全交给第三方平台，GitHub 上的 Umami 提供了一套值得研究的开源方案。项目将自己定位为隐私优先的分析平台，覆盖流量、活动、行为、转化和收入等维度，并支持从源码或 Docker + PostgreSQL 自托管。本文依据官方仓库 README、源码目录、package.json、Docker Compose 配置和 v3.3.1 Release 整理；版本与页面统计按 2026 年 9 月 2 日核对结果记录。

截至核对时，仓库最新 Release 为 v3.3.1，发布时间为 2026 年 8 月 20 日；GitHub 页面显示约 3.85 万 stars、7.9k forks。仓库主语言为 TypeScript，采用 MIT 许可证，官方站点为 umami.is。这些动态数据会随 GitHub 页面和后续发布变化，使用前应以仓库当前内容为准。

Umami 适合解决什么分析问题

Umami 的核心价值不只是展示访问量，而是把网站运营中常见的几个问题放到同一套分析界面里：哪些页面带来访问，哪些活动带来流量，访客怎样浏览内容，目标事件是否完成，以及转化或收入如何变化。仓库 README 还列出了 audience segmentation、cohort analysis、product analytics 和 user journey 等主题，说明它既能服务内容站，也能作为产品分析的自托管基础。

流量与活动：围绕网站访问、来源和营销活动观察流量结构。
行为分析：把页面浏览与事件数据放在可视化报表中，便于定位用户路径。
转化与收入：支持围绕目标、漏斗和价值数据做进一步分析，适合产品或商业站点。
隐私取向：README 将项目描述为 privacy-first、no cookies、no surveillance，但这属于项目定位，不等于自动完成所有地区的隐私合规。
部署选择：可以自己维护数据库和应用，也可以按项目提供的云端形态评估使用成本与数据边界。

源码结构与技术栈：分析界面之外还有哪些组件

从仓库根目录看，src/ 是应用源码，prisma/ 和 db/ 与数据库模型、迁移及初始化相关，public/ 放置静态资源，scripts/ 承担构建辅助，tests/ 提供测试，Dockerfile 与 docker-compose.yml 则对应容器化交付。package.json 显示项目基于 Next.js 16.3、React 19、TypeScript 和 Prisma 7.9.1，依赖中还包含 Chart.js、Redis、ClickHouse 客户端以及 rrweb 等组件。这里的依赖清单是当前版本的实现细节，不代表每种部署都必须启用所有外部服务。

Umami GitHub 仓库文件结构与项目概览 — Umami GitHub 仓库页面：可看到 `src`、`prisma`、`docker` 等目录，以及主分支、MIT 许可证和 v3.3.1 Release。页面信息核对于 2026-09-02。

层次	当前仓库可核验的技术	作用或观察
应用框架	Next.js 16.3、React 19	承载服务端渲染、路由与分析后台界面
主要语言	TypeScript	GitHub 语言统计中占比约 97.6%
数据访问	Prisma 7.9.1、PostgreSQL 适配器	连接关系数据库并执行迁移、查询
可视化与采集	Chart.js、tracker / recorder 构建脚本	支撑图表展示与前端数据采集产物
交付方式	源码构建、Docker、Docker Compose	适应自托管服务器或容器环境

从源码自托管：Node.js + PostgreSQL 路线

官方 README 给出的源码安装条件是 Node.js 18.18 及以上版本，以及 PostgreSQL 12.14 及以上版本。基础流程是先取得仓库并安装依赖：

git clone https://github.com/umami-software/umami.git
cd umami
pnpm install

随后在项目根目录创建 .env，至少配置 DATABASE_URL=connection-url。如果需要调整内部 UI API 的基础地址，可以设置 API_URL；如果要启用双因素认证，则需要配置 64 位十六进制的 TWO_FACTOR_ENCRYPTION_KEY，README 给出的生成命令为 openssl rand -hex 32。完成配置后执行 pnpm run build，再用 pnpm run start 启动，默认地址为 http://localhost:3000。

安全提醒：README 说明首次构建会创建数据库表和登录用户，默认用户名为 admin、密码为 umami。这只是初始化行为，不应作为生产凭据；首次登录后应立即修改密码，并为数据库、应用密钥和反向代理配置独立的安全策略。本文没有在本地实际安装或运行 Umami，上述命令和要求以官方 README 为准。

Docker Compose：更快启动，但仍要自己负责密钥与数据

仓库同时提供 Docker 镜像和 Compose 示例。README 给出的镜像拉取命令是 docker pull docker.umami.is/umami-software/umami:latest，仓库中的 docker-compose.yml 使用 ghcr.io/umami-software/umami:latest，并以 PostgreSQL 15 Alpine 容器作为数据库，映射应用的 3000 端口，同时挂载 umami-db-data 卷和 /api/heartbeat 健康检查。直接在包含 Compose 文件的目录执行 docker compose up -d 即可按示例启动服务。

示例文件中的 APP_SECRET、数据库密码和 TWO_FACTOR_ENCRYPTION_KEY 都是占位值，部署前必须替换为随机且妥善保管的值；不要把示例密码、密钥或公开端口配置原样暴露到生产环境。容器化只改变交付方式，并不会自动完成备份、升级回滚、域名证书、访问控制或隐私告知。

升级与 v3.3.1：维护时应关注的变化

源码部署的官方更新流程是先拉取代码，再安装依赖并重新构建：git pull、pnpm install、pnpm build。Docker 部署则使用 docker compose pull 和 docker compose up --force-recreate -d 更新镜像。无论哪种方式，都建议先备份 PostgreSQL 数据并在预发布环境观察迁移结果。

v3.3.1 是一次维护型版本。Release 记录包含更安全的双因素认证配置反馈、根路径与 tracker 会话状态修复、事件属性过滤和关系事件分页修复、扩展指标查询性能改进、空值漏斗处理，以及用户名冲突和管理菜单等问题修复。仓库还加入了 prisma/migrations/24_lowercase_username，用于把 3.2 之前安装中的用户名规范化为小写，并处理与软删除账号的冲突。升级前请阅读完整变更记录，不要只根据版本号判断是否可以直接覆盖。

MIT 许可、适用人群与现实边界

Umami 使用 MIT License。通常可以在遵守许可证文本、保留版权和许可声明的前提下使用、修改和再分发，但许可证也明确包含免责声明。对个人博客、内容站、独立开发者产品和希望控制数据存储位置的团队，它适合作为隐私取向的网站分析基础；对需要复杂数据仓库、极大规模实时计算或完整企业级治理的平台，则应先评估其当前版本、扩展架构和运维能力，不能仅凭开源标签下结论。

“隐私优先”也不等于“无需合规”。自托管后，服务器日志、数据库备份、访问控制、Cookie 或事件配置、用户告知和数据保留周期仍由部署方负责；是否需要取得同意、如何处理个人信息，要结合所在地区法律和组织自己的隐私政策判断。Umami 的优势在于可审计源码和可控的部署边界，而不是替使用者做完所有隐私决策。