前言

如果你跟我一样，既想清楚知道自己的网站有多少人看、从哪来，又不想把用户数据拱手交给第三方，更受不了那些动辄弹出 “同意追踪” 的繁琐流程 —— 你大概率会喜欢 Umami 。
它不的界面并不花里胡哨，只把访问量、来源渠道、设备类型这些核心数据摆得明明白白，一个页面全看清。关键是能私有化部署，将数据握在手里，同时开源免费。
如果你想直观感受它的界面，可以访问官方 Demo，核心数据看板如下：

实时行为监控更是精准到秒，能清晰看到访客的浏览行为：

官方提供了多种部署方式,因为一些原因 (Docker部署默认账号密码无法登录) 我用源代码部署一遍

什么是Umami?

Umami 是一款开源网站统计工具。它尊重隐私：无 Cookie、无跨站追踪、无个人数据收集，并原生支持 GDPR 合规。

为什么选择Umami?

  • 隐私至上 —— 无 Cookie，无浏览器指纹，不收集个人数据。让访问者保持完全匿名。

  • 掌握数据 —— 支持私有化部署。分析数据永远不会离开自己的服务器。

  • 极致轻量 —— 追踪脚本体积小于 2KB。完全不会拖慢网站的加载速度。

  • 部署简单 —— 支持多种方法部署。无需任何复杂的配置过程。

准备工作

在开始部署前，先确认你的服务器满足以下条件：

  • 有公网 IP（或本地服务器用于测试）

  • 开放目标端口（默认 3000，可自定义）

首先进入准备部署umami的目录

1
cd /opt

创建umami用户(分割权限)

1
useradd -M umami

然后,将umami的源码保存到本地(git clone或下载release里的压缩包),我选择clone

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

授权

1
sudo chown -R umami:umami /opt/umami

进入umami目录

1
cd umami

环境部署

部署Umami需要:

  • Node.js (版本高于 18.18)

  • PostgreSQL (版本不小于 v12.14)

1.部署Node.js (推荐参考官方文档)

我使用官方的Linux + fnm + npm组合 (这里会带来一个小问题,将在后面提及)

1
2
3
4
5
6
7
8
9
10
11
12
# Download and install fnm:
curl -o- https://fnm.vercel.app/install | bash

# Download and install Node.js:
fnm install 24

# Verify the Node.js version:
node -v # Should print "v24.13.1".

# Verify npm version:
npm -v # Should print "11.8.0".

上述内容复制于官方网站

1.2固化Node.js目录

上面我们使用fnm安装Node.js,这会导致我们的Node.js没有被安装在默认目录
输入which npm以查找当前session下npm所在目录

1
2
root@server:/opt# which npm  
/run/user/0/fnm_multishells/3827447_1771299998397/bin/npm

由于 /run/user/0/... 是一个临时会话路径,为了后续配置service方便,保证稳定性，我们采取最稳妥的方案：迁移 fnm 生成的二进制文件

由于fnm默认将不同版本的 Node 安装在用户的家目录下，我们运行以下命令来精准定位：
find /root/.local/share/fnm -name "node" -type f -executable | grep "v24.13.1"

此处v24.13.1为上方fnm安装的Node.js版本

我的执行结果如下:

1
2
root@server:/opt# find /root/.local/share/fnm -name "node" -type f -executable | grep "v24.13.1"
/root/.local/share/fnm/node-versions/v24.13.1/installation/bin/node

这个路径就是 Node 的“真身”

我们可以将这个版本的 Node 复制到 /opt/node-v24，这样就能直接访问，且不受 root目录的权限限制。

1
2
3
4
5
6
7
8
# 创建目标目录
sudo mkdir -p /opt/node-v24

# 将 fnm 下载的 node 运行环境整体复制过去
sudo cp -r /root/.local/share/fnm/node-versions/v24.13.1/installation/* /opt/node-v24/

# 确保 /opt/node-v24 可读可执行
sudo chmod -R 755 /opt/node-v24

这样,我们就完成了Node.js目录的固化

2.安装PostgreSQL (推荐参考官方文档)

1
2
3
4
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
#自动化配置apt仓库
sudo apt install postgresql-18  #安装postgresql-18

3.安装pnpm

1
npm install -g pnpm

4.安装依赖包

1
pnpm install

配置数据库

首先，你需要以超级用户（通常是 postgres）身份登录到数据库: psql -U postgres

执行以下命令创建用户：

1
2
3
4
5
6
7
8
9
10
11
-- 创建一个带密码的用户(建议将'password'替换为自己的密码)
CREATE USER umami WITH PASSWORD 'password';

-- 创建数据库'umami
CREATE DATABASE umami;

-- 将该数据库的所有权移交给umami
ALTER DATABASE umami OWNER TO umami;

-- 退出psql
\q

在pg_hba.conf中添加（或修改）以下一行：

1
2
# TYPE    DATABASE        USER            ADDRESS                 METHOD
host      umami           umami_user      127.0.0.1/32            scram-sha-256

执行sudo systemctl reload postgresql,使配置更改生效

配置Umami安装文件

创建.env文件,填入:

1
DATABASE_URL=postgresql://umami:password@localhost:5432/umami

Umami设置

构建Umami

执行: pnpm build
当看到终端如下图时,则说明构建完成

启动Umami

执行: pnpm start
当看到终端如下图时,说明成功启动

默认情况下，这Umami会在 http://localhost:3000 上提供服务。你可以配置Nginx反向代理转发请求，或直接更改服务端口。

配置Umami后台运行

官方建议使用PM2进行进程管理,但是我习惯使用Debian12自带的systemctl管理器进行管理,我的配置如下(/etc/systemd/system/umami.service):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[Unit]
Description=Umami Analytics
After=network.target docker.service

[Service]
Type=simple
# 运行 Umami 的用户
User=umami
# Umami 项目的具体路径
WorkingDirectory=/opt/umami
# 环境变量配置
Environment="PATH=/opt/node-v24/bin:/usr/local/bin:/usr/bin:/bin"
Environment=NODE_ENV=production

# 启动命令（确保路径指向 npm ）
ExecStart=/opt/node-v24/bin/npm start

Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

写入后执行

1
2
3
4
sudo systemctl daemon-reload #重载service文件
sudo systemctl enable umami  #设置服务开机自启
sudo systemctl start umami   #启动服务
sudo systemctl status umami  #查看服务状态

访问 ip:3000,若能看到

则说明umami.service配置无误

配置反向代理

直接通过 IP:端口访问不够美观，且缺乏 HTTPS 安全层。我们可以用 Nginx（或 Caddy、Apache）做反向代理，绑定域名并配置 SSL。

1. 解析域名

先在域名解析平台（如阿里云、Cloudflare）将域名（如 umami.example.com）解析到服务器 IP。

2. Nginx 反向代理配置

在 Nginx 配置文件中添加以下内容。反代配置如下图所示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
server
{
    listen 80;
    listen 443 ssl http2;
    server_name umami.example.com;
    root /www/wwwroot/umami.example.com;
    if ($server_port !~ 443){
        rewrite ^(/.*)$ https://$host$1 permanent;
    }

    ####################
    # 其他配置
    ####################

    # 反代配置
    location ^~ /   {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header REMOTE-HOST $remote_addr;
    add_header X-Cache $upstream_cache_status;
    # 缓存
    add_header Cache-Control no-cache;
    expires 12h;
  }
}

如果用宝塔面板或1Panel等，操作更简单：在 “网站” 中添加站点，绑定域名后，在 “反向代理” 中设置目标 URL 为 http://127.0.0.1:3000 即可：

3. 首次登录：初始化设置

访问你的域名（如 https://umami.example.com），使用默认账号登录：

  • 用户名：admin

  • 密码：umami

重要！
登录后第一件事：修改默认密码！进入 “Settings”→“Profile”，更新密码为强密码，避免被他人登录。

食用方法

0. 创建看板账号(可选但推荐)

1. 创建只读的账号

点击 “Admin”→“Users”→“Create user”,Username/Password可随意设置,Role 选择View only并保存,这样我们就获得了一个只读的账号,可以很好的避免权限泄露

2. 创建Team

进入 “Settings”→“Teams”,点击“Create team”,Name可随意设置.

保存后,点击右侧的 “编辑”(三个点),复制Access code

3. 加入团队

登出当前管理员账号,重新登录刚才创建的只读账号;
点击 “Settings”→“Teams”→“Join team”,粘贴Access code,点击Join

1. 添加网站

登录管理员账号,切换为Team,点击 “Add website”,填入信息

2. 获取跟踪代码

添加网站后，点击网站右侧的 “编辑”,下滑找到Tracking code,复制：

3. 安装跟踪代码到网站

将跟踪代码添加到需要统计的网站中，具体位置因平台而异：

  • WordPress：在 “外观”→“主题文件编辑器”→“header.php”，粘贴到 <head> 标签内

  • Hexo：在主题的_config.yml 中找到 “自定义脚本” 配置项进行配置即可

  • 静态 HTML：直接粘贴到 <head> 标签内

以 装有Betterfly主题的Hexo 为例，添加位置如下：

为什么放 <head> 里？
因为 <head> 是网页加载时优先解析的部分，能确保跟踪代码尽早执行，避免遗漏短时间访问（如用户刚打开页面就关闭）。

4. 进阶(可选)

若你跟我一样,使用的是装有Betterfly主题的Hexo.便可以使用Umami API,代替 不蒜子 提供的 访问人数统计(UV/PV).

1. 获取token

使用以下数据POST向 yourumamisite/api/auth/login 发送请求：

1
2
3
4
{
  "username": "username",
  "password": "password"
}

如果成功，应该会收到类似如下的回复：

1
2
3
4
5
6
7
8
9
10
{
  "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A",
  "user": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "username": "admin",
    "role": "admin",
    "createdAt": "2000-00-00T00:00:00.000Z",
    "isAdmin": true
  }
}

复制并保存其中的token参数

在主题的_config.yml 中找到umami_analytics字段,将token填入UV_PV内的token处

1
2
3
4
5
6
UV_PV:
    site_uv: true
    site_pv: true
    page_pv: true
    # Umami Cloud (API key) / self-hosted Umami (token)
    token: {此处填入}

小结

Umami 作为一款轻量、隐私友好的自建统计工具，完美平衡了功能与简洁性。通过本文的部署教程，你可以在 30 分钟内搭建一套属于自己的网站分析系统，摆脱对第三方工具的依赖。

参考文献

Umami Docs
umami-software/umami