Umami 自托管：Compose 拉起 PostgreSQL，上线前先改掉默认密码

项目信息

• GitHub：https://github.com/umami-software/umami
• 文档：https://umami.is/docs/
• Demo：https://cloud.umami.is/share/LGazGOecbDtaIwDr/umami.is
• Docker 镜像：docker.umami.is/umami-software/umami:latest
• License：MIT

Umami 是一个隐私优先的分析平台，把流量、campaign、行为、转化、收入放在同一个面板里看。它不做 Cookie 追踪，自托管时所有数据落在自己的 PostgreSQL 里。

先说要不要自托管

如果站点流量极小，只是想知道每天有多少 PV，那挂一个第三方 SaaS 分析更省事：不用维护 Node 进程，也不用管 Postgres 的备份和版本升级。自托管换来的是数据不出自己的库、统计口径自己定，代价是多一个数据库和一台常驻服务要照看。

成本上，第三方分析按事件量计价，量涨上去是持续支出；自托管基本是一次性的机器投入加上维护时间。

从源码安装

环境要求：Node.js 18.18+、PostgreSQL v12.14+。

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

然后在 .env 里配置数据库连接，DATABASE_URL 是必填项：

DATABASE_URL=connection-url

连接串格式：

postgresql://username:mypassword@localhost:5432/mydb

其他可选配置项：

• API_URL：用于改变内部 UI 调用 API 时的 base URL。相对路径按 BASE_PATH 提供，绝对 URL 会通过本地 /api 路由代理。例如 API_URL=/internal-api 或 API_URL=https://api.example.com/api。
• TWO_FACTOR_ENCRYPTION_KEY：设置为 64 位 hex 字符串才启用两步验证，可用 openssl rand -hex 32 生成。这个 key 没设之前，2FA 不可用。
• MCP_ENABLED：MCP 默认关闭。设为 1 才会开启 /mcp 端点，之后在 Settings → API keys 里生成 API key 做认证。

构建和启动：

pnpm run build
pnpm run start

构建这一步在第一次执行时会自动建表，并创建登录用户 admin / 密码 umami。默认监听 http://localhost:3000，可以在前面放 web server 做代理，或者直接改端口。

这两个默认凭据是公开的，服务只要能被外网访问，上线前就必须改掉。

Docker 方式

docker pull docker.umami.is/umami-software/umami:latest
docker compose up -d

docker compose up -d 会同时把 Umami 和 PostgreSQL 一起拉起来，不需要单独准备数据库。

反代与端口

Umami 默认跑在 3000 端口，前面挂反向代理时要注意两件事：

• 用相对路径部署在子路径下，BASE_PATH 决定了这些路径从哪里提供服务，代理要转发到 3000 上的对应路径。
• 用绝对 URL 时，内部调用会经由本地 /api 路由代理，反代规则别把这条路由拦掉。

另外，需要 2FA 的部署要先配好 TWO_FACTOR_ENCRYPTION_KEY，否则该功能无法启用。

升级

源码部署：

git pull
pnpm install
pnpm build

Docker 部署：

docker compose pull
docker compose up --force-recreate -d

Docker 这条路走的是 --force-recreate，容器会用新镜像重建，数据仍在 PostgreSQL 卷里。源码方式则需重新构建产物再启动。