Umami · 开源隐私友好网站统计分析｜源码与 Docker 部署全指南
项目仓库： https://github.com/umami-software/umami
开源协议：见仓库 LICENSE · 运行时：Node.js 18.18+ · 数据库：PostgreSQL v12.14+ · 默认端口：3000 · 默认账号：admin / umami · 官方文档：umami.is/docs
1 项目简介
Umami 是一个开源、隐私友好的网站分析工具，可自托管，用简洁界面统计网站访问数据。它基于 Next.js 构建，数据存储于 PostgreSQL，默认端口 3000，首次构建会自动建表并创建默认管理员账号。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | Umami |
| 仓库地址 | github.com/umami-software/umami |
| 项目定位 | 开源隐私友好网站分析 |
| 运行时要求 | Node.js 18.18+ |
| 数据库 | PostgreSQL v12.14+ |
| 默认端口 | 3000 |
| 默认账号 | admin / umami |
| 官方文档 | umami.is/docs |
1.2 适用场景
- 自托管替代 Google Analytics。
- 需要轻量、隐私友好的访问统计。
- 与现有 PostgreSQL 基础设施集成。
1.3 能力边界（官方口径）
- 需自备 Node.js 18.18+ 与 PostgreSQL 12.14+。
- 首次 build 自动建表并创建默认 admin 账号。
2 前置要求与服务器配置
2.1 软件前提
- Node.js 18.18+。
- PostgreSQL v12.14+。
- pnpm 包管理器。
3 方式一：源码部署
# 1. 克隆并安装依赖
git clone https://github.com/umami-software/umami.git
cd umami
pnpm install3.1 配置 .env
DATABASE_URL=connection-url连接 URL 格式：
postgresql://username:mypassword@localhost:5432/mydb可选配置：
| 配置 | 说明 |
|---|---|
API_URL |
内部 UI API 基础路径（如 /internal-api） |
TWO_FACTOR_ENCRYPTION_KEY |
64 位 hex，开启 2FA；用 openssl rand -hex 32 生成 |
MCP_ENABLED=1 |
启用 /mcp 端点（默认关闭） |
3.2 构建与启动
# 首次构建会自动建表并创建 admin/umami
pnpm run build
# 启动（默认 http://localhost:3000）
pnpm run start4 方式二：Docker 部署
# 拉取镜像
docker pull docker.umami.is/umami-software/umami:latest
# 用官方 compose 启动（自带 PostgreSQL）
docker compose up -d5 更新
# 源码更新
git pull
pnpm install
pnpm build
# Docker 更新
docker compose pull
docker compose up --force-recreate -d6 常见故障排查
- 构建失败：确认 Node.js >= 18.18、PostgreSQL 可连。
- 登录失败：默认账号 admin/umami，首次登录后立即改密码。
- 2FA 未生效：需设置
TWO_FACTOR_ENCRYPTION_KEY后才可用。
7 风险与说明
- 许可证：以仓库 LICENSE 为准。
- 默认凭据：生产务必修改 admin/umami。
- 非官方声明：本文基于官方仓库 README 整理，命令以最新 release 为准。