宝塔面板 Docker 搭建 Umami 网站访问统计——从踩坑到跑通的完整教程-Baili Blog

告别百度统计的 spam 广告，把数据攥在自己手里。本文记录了在腾讯云轻量服务器 + 宝塔面板上用 Docker 部署 Umami 的全过程，包含每一个踩过的坑和解决方案。

前言：为什么要自建网站统计？

用过百度统计的人多半遇到过这种事：打开后台，发现”Top 10 搜索词”里全是莫名其妙的东西——

T G y i n l i u c a i s h e n - 搜^索广. 告
T G: y i n l i u c a i s h e n | 精^准_获^客
独/家/霸/屏-TG: y i n l i u c a i s h e n

这些不是真实用户在搜的，是有人用机器人伪造来源（Referrer Spam），把广告词刷进你的统计后台。每条只有 1 PV、占 0.8%，但看着烦。

更根本的问题是：你的访客数据存在百度那里，你没法完全掌控。

于是我决定自建。对比了几个开源方案后，选了Umami：

Umami 是开源（MIT 协议）、轻量、隐私优先的网站分析工具，所有数据存在你自己服务器的 PostgreSQL 数据库里，不经过任何第三方。

一、环境说明

核心思路：Umami 跑在 Docker 容器里（内部端口 3000），用宝塔的 Nginx 反向代理，把 bailir.top 指向它。博客页面里嵌入一段 Umami 追踪代码，访客数据就上报到你自己的服务器。

访客打开 www.bailir.top（博客）
 ↓ 页面里有一段 Umami 追踪代码
访客浏览器 → https://bailir.top/script.js 上报数据
 ↓ 宝塔 Nginx 反代到本地
Umami 容器（Docker，端口 3000）收到并记录
你 → 打开 https://bailir.top 登录后台看统计

二、准备工作

1. 确认 Docker 已安装

宝塔左侧 →软件商店，搜索 “Docker”，安装。已有则跳过。

2. 确认域名解析

你的统计域名（本例 bailir.top）的 DNS A 记录要指向你的服务器 IP。在终端验证：

ping bailir.top

能 ping 通你的服务器 IP 就行。

3. 放行端口

宝塔 → 安全，确认80和443端口已放行（SSL 申请需要 80 可达）。3000 端口不需要对外放行——我们用反代，外部只走 443。

三、安装 Umami（Docker Compose 方式）

⚠️ 为什么不用宝塔应用商店一键装？

宝塔应用商店里有 Umami 一键安装模板，但截至 2026 年 7 月，它指向的镜像仓库 docker.umami.dev已经失效（DNS 解析不到），无论怎么填配置都会报：

Get ”https://docker.umami.dev/v2/”: dial tcp: lookup docker.umami.dev: no such host

所以直接放弃一键装，用 Docker Compose 手动装，反而更可控。

第 1 步：创建目录和配置文件

1. 宝塔 → **文件**，进入 `/www/wwwroot/`，新建文件夹 `umami`。
2. 进入 `umami` 文件夹，新建文件 `docker-compose.yml`。

第 2 步：写入 docker-compose.yml

把下面这段完整复制进去：

version: ”3”
services:
 umami:
 image: ghcr.m.daocloud.io/umami-software/umami:postgresql-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
 restart: always
 init: true
 healthcheck:
 test: [”CMD-SHELL”, ”curl http://localhost:3000/api/heartbeat”]
 interval: 5s
 timeout: 5s
 retries: 5
 db:
 image: docker.m.daocloud.io/library/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:

关于镜像源：国内服务器直连 ghcr.io（GitHub 镜像仓库）和 Docker Hub 经常超时。这里用的是 DaoCloud 镜像代理（ghcr.m.daocloud.io 和 docker.m.daocloud.io），实测可用。如果 DaoCloud 也超时（偶尔限流），可尝试其他国内镜像源。

第 3 步：生成 APP_SECRET 并替换

在宝塔终端执行：

openssl rand -hex 32

把输出的 64 位字符串，替换掉 docker-compose.yml 里的 replace-me-with-a-random-string。

⚠️ 务必替换！ APP_SECRET 是保护你认证 Token 的密钥，每个实例都不同，上线后不要随意更换。

第 4 步：用命令行拉起容器

这一步踩过坑：宝塔 Docker 界面里”添加 Compose 项目”有时会假成功——日志显示”完成”，但容器列表是空的。命令行最稳。

宝塔 →终端，执行：

cd /www/wwwroot/umami
docker compose up -d

等 1–3 分钟（首次拉镜像），看到两个容器都启动后验证：

docker ps

应该能看到 umami 和 db 两个容器，状态都是 Up。

为什么是两个容器？这是标准架构：umami 容器是统计程序本身（收数据、显示报表），db 容器是 PostgreSQL 数据库（存数据）。两者通过 Docker 内部网络连接。千万别删 db，删了数据就没了。

四、配置反向代理 + SSL

Umami 跑起来了，但现在只能用 http://服务器IP:3000 访问。我们要让它通过 https://你的域名访问——这一步必须做，否则博客里的统计脚本会因为混合内容（HTTP 脚本嵌入 HTTPS 页面）被浏览器拦截，导致一条数据都收不到。

第 1 步：建站点

宝塔 →网站 → 添加站点：

域名：填你的统计域名（如 bailir.top）
PHP 版本：选”纯静态”（Umami 不需要 PHP）
点提交

第 2 步：配置反向代理

站点设置 →反向代理 → 添加反向代理：

代理名称：随便，如 umami
目标 URL：http://127.0.0.1:3000
发送域名：$host
提交

第 3 步：申请 SSL（关键！）

站点设置 →SSL → Let’s Encrypt→ 勾选域名 → 申请 → 成功后开启强制 HTTPS。

⚠️ 实测发现：在部分宝塔环境里，不配 SSL 时，访问统计域名会被跳转到你的其他站点（比如博客）。原因是：未配 SSL 时，统计域名的 Nginx server 块不完整，请求落到了 default_server（通常是博客），博客发现域名不匹配就 301 跳转。配完 SSL 后，宝塔会生成完整的 server 块（含正确的 server_name 和 443 监听），请求即精确归位，不再跳转。所以——SSL 不只是”加密”，在你的环境里它还是让站点真正生效的关键一步。

第 4 步：验证

浏览器打开 https://你的统计域名，应该看到 Umami 的登录页面。

五、登录 Umami 并初始化

1. 登录并改密码

打开你的统计域名，用默认账号登录：

用户名：admin
密码：umami

登录后第一件事：改密码！右上角头像 → Profile → 修改密码。这是你数据的总闸，务必设强密码。

2. 添加被统计的网站

左侧菜单 →Settings → Websites → Add website：

Name：你的网站名（如我的博客）
Domain：你的博客地址（如 https://www.bailir.top）
保存

3. 获取追踪代码

保存后，会生成一段追踪代码：

```html
<script
  async
  src="https://你的统计域名/script.js"
  data-website-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx">
</script>
```

复制这段代码。

六、把追踪代码嵌入博客

两种方式，选一个就行，别两个都加（会重复统计）：

方式一：主题自带代码位（推荐）

如果你的 WordPress 主题有”自定义代码 / 统计代码 / 头部代码（Header）”之类的设置项（Zibll 主题一般在”高级设置”或”SEO/统计”里），直接把代码粘进去保存。

方式二：用插件

WP 后台 → 插件 → 安装WP Code→ 启用 → Code Snippets → Header & Footer → 粘到 Header 框 → 保存。

七、验证统计是否生效

如果没出来：清浏览器缓存再访问一次；或 F12 → Network，看 script.js 请求是不是 200。

看到自己的访问 →部署完成！🎉

八、常见问题与排错

Q1：宝塔添加 Compose 报”模板名已存在”

原因：之前失败的安装留下了隐形记录，即使模板库显示空白也会拦。

解决：不要走”模板”功能，直接”添加 Compose 项目”并手动填一个新项目名（如 my-umami）。如果还报已存在，去 Compose 项目列表删掉残留项目，目录改名后重试。最终建议直接用命令行docker compose up -d，绕开所有 UI 问题。

Q2：镜像拉取超时

原因：国内服务器连 ghcr.io / Docker Hub 被墙或慢。

解决：用 DaoCloud 镜像代理（本文配置已用）。如果 DaoCloud 也超时，可尝试：

docker.1ms.run/ghcr.io/umami-software/umami:postgresql-latest
docker.xuanyuan.me/ghcr.io/umami-software/umami:postgresql-latest

或者给 Docker 配置镜像加速器（宝塔 → Docker → 设置 → 镜像加速）。

Q3：访问统计域名跳转到博客

原因：统计域名的 Nginx server 块不完整，请求落到了博客的 default_server。

解决：给统计域名配置 SSL（见第四步第 3 步）。配完 SSL 宝塔会生成完整的 server 块，请求即精确归位。配置前也可先用 nginx -s reload + 无痕窗口排除浏览器对旧 301 的缓存。

Q4：统计后台没有数据

原因：可能是混合内容被拦（统计端不是 HTTPS）、或追踪代码的 data-website-id 不对。

解决：确认统计域名已强制 HTTPS；确认代码里 src 是 https://你的统计域名/script.js；F12 → Network 看脚本是否 200。

九、进阶配置

1. 屏蔽统计后台被搜索引擎收录（推荐）

统计后台是私有的，不该被 Google/百度收录。但因为统计域名是全反代站点，在根目录放 robots.txt不会被访问到（请求都转发给 Umami 了）。正确做法是在 Nginx 里拦截：

1. 宝塔 → 文件 → 统计域名根目录 → 新建 `robots.txt`，内容：

   User-agent: *
   Disallow: /

2. 宝塔 → 网站 → 统计域名 → 设置 → **伪静态**，粘贴：

   location = /robots.txt {
       root /www/wwwroot/你的统计域名目录;
   }

3. 保存并重载 Nginx。

4. 访问 `https://你的统计域名/robots.txt` 验证能看到那两行内容。

Disallow: / 只影响统计域名，不影响你的博客。

2. 了解：Umami 自动过滤爬虫

Umami 内置了机器人识别（基于 isbot 库），在数据上报前就过滤掉已知爬虫：

✅ Googlebot（谷歌爬虫）—— 被过滤
✅ Baiduspider（百度爬虫）—— 被过滤
✅ Bingbot、YandexBot、Bytespider 等 —— 全部被过滤

所以你看到的访客都是真人浏览器，数据天然比日志类工具干净。

想看爬虫有没有来过你的站？查 Nginx 日志：

grep -iE "googlebot|baiduspider|bingbot" /www/wwwlogs/你的博客域名.log | tail -50

或注册 [Google Search Console](https://search.google.com/search-console)和 [百度搜索资源平台](https://ziyuan.baidu.com) 查看。

3. 可选：开启回放与热力图

Umami v3 新增了两个进阶功能（默认关闭）：

– **回放（Replays）**：录下访客的操作（鼠标、点击、滚动），像看监控回放。

– **热力图（Heatmaps）**：在页面上叠加彩色图，显示哪里被点得多、访客滚到多深。

界面上你可能看到一个叫 LABEL.HEATMAPS 的东西——别慌，那不是新功能，是 Umami 中文翻译文件的小 bug，”热力图”这个词没被翻成中文，直接显示了内部翻译键名。不影响任何功能。

开启方法：Settings → Websites → Edit → Replays & Heatmaps 区，开开关。关键设置：

– **采样率**：默认 0.15（录 15% 的会话），个人博客可设 1 全看。

– **脱敏级别**：建议 `moderate`（输入框打码），保护访客隐私。

个人内容博客通常不需要这两个功能，基础统计已经够用。等想优化页面布局时再开热力图即可。

4. 修改站点名称

在 Umami 后台：Settings → Websites → 点网站右边的 Edit → 改 Name → Save。

注意：开源版 Umami 不能自定义程序本身的 Logo 和左上角”Umami”品牌名（那是 Umami Cloud 付费版的功能）。能改的只是你添加的”被统计网站”的名称。

十、日常使用

部署完成后，日常只需要：

1. 打开 `https://你的统计域名`，登录看 Dashboard。

2. 关注的数据：

– **访问量 / 访客数**：总览

– **来源（Referrers）**：访客从哪来（搜索引擎、直接访问、外链）

– **页面（Pages）**：哪些文章被看得最多

– **设备 / 浏览器**：移动端还是 PC、什么浏览器

– **国家 / 地区**：访客分布

– **实时访客**：当前有人在看你的博客

3. 定期备份：宝塔 → 计划任务，给 Umami 的 Postgres 数据卷做定时备份（数据卷名一般叫 `umami_umami-db-data`，在 Docker 数据目录下）。

总结

| 做了什么 | 效果 |

|———|——|

| 用 Docker Compose 装了 Umami + PostgreSQL | 统计程序跑在自己服务器上 |

| 用宝塔建站点 + 反代 + SSL | 通过 HTTPS 域名访问统计后台 |

| 把追踪代码嵌入博客 | 开始收真实访客数据 |

| 配 robots.txt 拦截 | 统计后台不被搜索引擎收录 |

| Umami 默认过滤爬虫 | 数据干净，只有真人访问 |

整个过程踩了不少坑（镜像源失效、宝塔 UI 假成功、SSL 配置前域名跳转），但最终跑通后体验很好——数据完全在自己手里，不再被 spam 广告骚扰，追踪脚本只有 2KB 不拖慢页面，后台界面也干净漂亮。

如果你也在用百度统计并被 spam 困扰，或者只是想把数据攥在自己手里，Umami 是个人博客自建统计的最佳选择之一。

本文基于实际部署过程整理，环境为腾讯云轻量服务器 + 宝塔面板 + WordPress/Zibll。不同环境可能略有差异，遇到问题欢迎交流。

本站收集的资源仅供内部学习研究软件设计思想和原理使用，学习研究后请自觉删除，请勿传播，因未及时删除所造成的任何后果责任自负。

如果用于其他用途，请购买正版支持作者，谢谢！若您认为「Baili Blog」发布的内容若侵犯到您的权益，请联系站长邮箱：b71239135@gmail.com 进行删除处理。
本站资源大多存储在云盘，如发现链接失效，请联系我们，我们会第一时间更新。

THE END