Umami 部署完全指南

前段时间一直想把站点统计这块重新整理一下。

原因其实也不复杂：传统统计方案不是不能用，而是对个人站来说经常太重；我自己更想要的是一个界面干净、数据够看、还能自己掌控的数据统计系统。翻了一圈之后，最后还是回到了 Umami。

Umami 是一款开源网站分析工具，可以把它理解成一个更轻量、更现代、也更适合个人站和小项目的统计方案。它不依赖那种非常重的后台逻辑，界面也比较清爽，拿来看日常访问数据很舒服。

为什么我最后还是选 Umami

如果只是想给博客或者网站加一个统计系统，其实能选的东西很多。

但对个人站来说，我最后还是更偏向 Umami，核心原因就几个：

• 开源并且界面简洁

• 自部署隐私可控

• 数据在自己手里而且对个人站和小项目来说功能够用

如果你的需求主要是：

• 看 PV / UV和页面访问情况

• 统计来源、设备、地区、浏览器

那 Umami 基本已经够用了。

而且它真正吸引我的地方，不只是“简洁”，而是“可控”。你可以把它放在自己的服务器上，可以自己决定什么时候更新、要不要迁移、数据库怎么备份，统计数据也不会完全依赖某个第三方平台。

为什么不是不蒜子或者 Google Analytics

不蒜子

不蒜子的优点很直接：

• 接入简单

• 几乎不用部署

• 很适合博客展示访问量和阅读量

但它本质上更像一个计数器，不是一个完整的统计系统。但如果你想长期做数据管理和分析，它的上限就比较明显了：

• 数据维度有限

• 更偏展示，不偏分析

• 服务依赖第三方

• 可控性比较低

所以不蒜子适合轻量展示，不太适合长期维护一套自己的统计系统。

Google Analytics

Google Analytics 的问题不是不强，反而是它太强了。

它更适合：

• 商业站点

• 广告投放分析

• 更复杂的用户行为分析

• 和 Google 生态深度联动的场景

但如果只是个人博客或小项目，经常会有几个问题：

• 后台复杂

• 学习成本高

• 基础数据查看不够轻量

• 隐私和第三方脚本问题始终存在

所以对个人站来说，GA 更像是能力最全的商业方案，但不一定是最适合长期自己维护的方案。

Umami 的优势到底在哪里

对我来说，Umami 最关键的优势就是下面这几件事：

• 可以自部署：怎么部署、什么时候更新、要不要迁移，都是自己决定

• 数据在自己手里：不依赖第三方平台规则，迁移和备份更自由

• 更容易做稳定：服务器、数据库、反代、备份都能自己掌控

这也是我最后更愿意折腾 Umami，而不是继续靠外部统计方案凑合用的主要原因。

部署前的基础要求

先说结论：

不管你最后选哪种方式部署，数据库都是必须的。

常见的连接格式如下：

postgresql://user:password@host:port/dbname

Umami 常见需要的环境变量主要有：

• DATABASE_URL

• APP_SECRET

其中：

• DATABASE_URL 用来连接数据库

• APP_SECRET 用来保证应用内部加密和会话安全

如果你打算自己构建源码，还需要准备：

• Node.js 18.18+

• Git

• pnpm

如果你现在还没决定用哪种部署方式，可以先简单判断：

• 想最快上线：Zeabur、Railway、Netlify、Vercel 这一类平台型方案更轻松

• 想把数据和服务长期握在自己手里：Docker Compose 自托管更合适

• 想完全自己掌控运行环境：源码手动部署也可以

方式一：Zeabur 一键部署

如果你想最快把 Umami 跑起来，Zeabur 属于很省事的一种选择。

部署步骤

1. 登录 Zeabur。

2. 创建新项目。

3. 从模板或 GitHub 仓库导入 Umami。

4. 添加 PostgreSQL 数据库服务。

5. 在环境变量中填写：

DATABASE_URL=postgresql://用户名:密码@主机:5432/数据库名
APP_SECRET=替换成随机字符串

1. 等待构建完成。

2. 绑定域名（可选）。

优点

• 部署快

• 不用自己维护服务器

• 适合先体验再说

缺点

• 平台限制更多

• 自由度不如自建

• 长期成本要自己评估

方式二：Vercel + 在线数据库部署

如果你已经在用 GitHub 和 Vercel，这套方式会非常顺手。

部署步骤

1. 打开 Umami 官方仓库：

https://github.com/umami-software/umami

1. Fork 到你自己的 GitHub 账号。

2. 登录 Vercel，点击 Add New Project。

3. 选择你刚刚 Fork 的仓库。

4. 配置环境变量：

DATABASE_URL=postgresql://用户名:密码@host:5432/dbname
APP_SECRET=替换成随机字符串

1. 开始部署。

2. 部署完成后绑定域名（可选）。

适合谁

• 不想自己维护服务器

• 已经习惯 GitHub + Vercel 工作流

• 想先快速把 Umami 跑起来

注意点

• 数据库还是要自己准备

• 平台成本和限制要自己评估

• 自由度不如自建高

方式三：Docker Compose 自托管

如果你拥有一台云服务器，那么使用 Docker 是数据掌握在自己手中、也最可控的方案。

环境要求

• 已安装 Docker 和 Docker Compose。

部署步骤

1. 在服务器上创建一个目录：

mkdir umami && cd umami

1. 下载 docker-compose.yml 文件：

wget https://raw.githubusercontent.com/umami-software/umami/master/docker-compose.yml

如果网络不通，可手动创建文件并粘贴以下内容：

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      APP_SECRET: replace-me-with-a-random-string
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

1. 启动服务：

docker-compose up -d

1. 访问：

http://服务器IP:3000

1. 反向代理（可选但推荐）：配置 Nginx 将域名指向 3000 端口，并开启 HTTPS。

为什么我更推荐 Docker 自托管

如果你想把统计数据、更新节奏和服务稳定性都掌握在自己手里，那 Docker 自托管是最合适的。

它的优点主要有：

• 数据在自己服务器和数据库里

• 更新和备份可控

• 迁移方便

• 长期维护更稳

常见坑

• 如果数据库连接不上，优先检查 DATABASE_URL

• 如果页面打不开，先看容器日志

• 如果域名接入后脚本异常，优先检查 HTTPS 和反代配置

更新 Umami

后续更新时，按你原文的方式执行即可：

docker-compose pull

docker-compose up -d

方式四：源码手动部署

如果你不想用 Docker，也不想依赖平台，那就可以直接拉源码、装依赖、构建，再用 Node 运行。

环境要求

• Node.js 18.18+

• Git

• pnpm

• PostgreSQL

部署步骤

1. 克隆源码：

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

1. 配置环境变量，例如：

DATABASE_URL=postgresql://用户名:密码@localhost:5432/库名
# 或者 MySQL
# DATABASE_URL=mysql://用户名:密码@localhost:3306/库名

1. 配置 APP_SECRET。

2. 安装依赖并构建。

3. 使用 Node / pm2 / systemd 运行应用。

4. 用 Nginx 做反向代理并配置 HTTPS。

适合谁

• 不想用 Docker

• 更习惯 systemd / pm2

• 想完全自己掌控运行环境

注意点

• Node 版本要够新

• 构建和运行环境都要自己维护

• 更新步骤比 Docker 更繁琐

数据库比部署方式更重要

很多人折腾服务时，会把注意力都放在 Docker、Node、Nginx、Vercel 这些表面层，但对 Umami 来说，真正最重要的其实是数据库。

因为 Web 应用坏了，大不了重建；但数据库一旦出问题，统计数据就真的没了。

所以我的建议很简单：

轻量个人用

可以直接：

• Umami + PostgreSQL 同机跑

• 或者 Docker Compose 里一起带上 PostgreSQL

长期稳定用

更建议：

• PostgreSQL 独立出来

• 或者直接用靠谱的托管 PostgreSQL

记得备份

至少把数据库导出养成习惯。

最后怎么选

如果你不想反复纠结，我给一个很直接的建议：

• 想最快跑起来：Zeabur、Vercel、Railway 这类平台型方案更省事

• 想把数据和服务握在自己手里：Docker Compose 自托管最合适

• 想完全掌控整个运行环境：源码手动部署也可以

如果是我自己来落地，大概率还是会这样选：

• 有服务器，优先 Docker Compose 自托管

• 没空管服务器，又想尽快上线，就选 Vercel 或 Zeabur

• 只有在我明确想完全掌控运行环境的时候，才会选源码部署

说到底，统计系统这种东西，真正重要的从来不是“它能不能显示几个数字”，而是：

它是不是长期可用、是不是足够稳定、数据是不是最终掌握在你自己手里。

从这个角度看，Umami 依然是很值得折腾的一种选择。