自托管 Umami 网站分析:从部署到生产级运维
Umami 3.5 部署实录:Docker Compose、Nginx TLS 与 Hugo 集成
前言
运营技术博客,流量数据是了解读者行为、调整内容方向的重要依据。我一直在用 Google Analytics,但 GA4 的界面越来越重,也不希望每个访客的浏览行为都落到第三方服务器上。
对比 Umami、Plausible、Matomo 之后,我选了 Umami:追踪脚本轻、不使用 Cookie、数据存在自己的 PostgreSQL 里,v3 的 REST API 也足够完整。2026 年 11 月 12 日发布的 3.5.0 补上了浏览器错误追踪和更严格的安全策略,正好可以在 Homelab 里完整部署一遍。
这次不只是把容器拉起来。我实际验证了追踪脚本、/api/collect 采集端点、Nginx TLS、Hugo 集成和备份恢复,截图都来自实验环境。公网部署时把域名、证书和端口替换掉即可。
技术选型
为什么选择 Umami
在决定自托管网站分析之前,我对几个主流开源方案做了横向对比:
| 维度 | Umami | Plausible | Matomo |
|---|---|---|---|
| 语言/框架 | Next.js (Node.js) | Elixir + Phoenix | PHP + MySQL |
| 追踪脚本大小 | 约 4 KB (gzip) | ~1 KB | ~22 KB |
| Cookie | 无 | 无 | 有(可关闭) |
| GDPR 合规 | 默认合规 | 默认合规 | 需配置 |
| 数据库 | PostgreSQL (v3) | PostgreSQL + ClickHouse | MySQL/MariaDB |
| 资源占用 | 低 (~512 MB) | 中 (~1 GB) | 高 (~2 GB) |
| API | 完整 REST API | 有限 | 完整 |
| 部署复杂度 | 低 | 中 | 高 |
| 实时仪表盘 | 有 | 有 | 有 |
| 自定义事件 | 有 | 有 | 有 |
| 开源协议 | MIT | AGPL-3.0 | GPL-3.0 |
最终选择 Umami 的原因:
- 追踪脚本 gzip 后约 4 KB,对页面加载影响很小
- 不使用 Cookie,不需要同意弹窗
- 只需要 Umami + PostgreSQL 两个容器
- v3 提供完整的 REST API,方便后续接入 Grafana 或自己的脚本
- MIT 协议,无商业使用限制
架构设计
访客加载博客页面时,stats.js 向 Umami 的采集端点发一个 POST;Nginx 终结 TLS 后把请求转给本机的 Umami 容器,Umami 通过 Prisma 写入 PostgreSQL。
graph TB
subgraph 访客侧
A[访客浏览器] -->|"加载 stats.js"| B[博客页面]
B -->|"POST /api/collect"| C[Nginx 443]
end
subgraph 服务端
C -->|"proxy_pass 127.0.0.1:3000"| D[Umami 3.5.0]
D -->|"Prisma ORM"| E[(PostgreSQL 15)]
E -->|"数据卷"| F["/var/lib/postgresql/data"]
end
subgraph 运维
G[Cron] -->|"pg_dump"| E
G -->|"zstd 压缩"| H[本地备份]
H -->|"rclone sync"| I[S3 对象存储]
J[healthcheck] -->|"/api/heartbeat"| D
end
style A fill:#e1f5fe
style D fill:#fff3e0
style E fill:#e8f5e9
style I fill:#fce4ec
关键设计决策:
- TLS 终结在 Nginx:统一证书管理,Umami 容器只把端口暴露到 localhost
- PostgreSQL 不暴露端口:数据库仅通过 Docker 内部网络与 Umami 通信
- 备份双写:本地保留一份,远端对象存储再放一份
- 健康检查:容器级 healthcheck 加外部拨测,服务不可用时能及时发现
部署
实验环境
本文的部署和验证在一台 Debian 12 虚拟机上完成:
- Umami 3.5.0(
docker.umami.is/umami-software/umami:3.5.0) - PostgreSQL 15.20(
postgres:15-alpine) - Docker 29.9.3,Docker Compose v5.7.1
- Nginx 1.22.1,证书由内网 step-ca 签发
- 443 端口被 k3s 的 Traefik 占用,Nginx 改听 9443;公网部署换回 443 即可
前置条件
- 一台能运行 Docker 的 Linux 服务器(本文以 Debian 12 为例)
- Docker Engine 和 Docker Compose 插件(本文使用 Compose v5.7.1)
- 一个域名,A 记录指向服务器 IP
- TLS 证书:公网用 Let’s Encrypt,内网可以用 step-ca 或自建 CA
目录结构规划
# 在服务器上创建项目目录
mkdir -p /opt/umami/{backups,scripts}
cd /opt/umami
最终的目录结构如下:
/opt/umami/
├── docker-compose.yml # 容器编排
├── .env # 环境变量(敏感信息)
├── backups/ # 本地备份目录
│ └── umami_20261115_030147.sql.zst
└── scripts/
├── backup.sh # 自动备份脚本
└── restore.sh # 恢复脚本
生成密钥
Umami 需要三个独立的随机值:数据库密码、APP_SECRET 和 TWO_FACTOR_ENCRYPTION_KEY。
# APP_SECRET:签名登录令牌,并参与匿名会话 ID 的派生
openssl rand -hex 32
# TWO_FACTOR_ENCRYPTION_KEY:加密用户的 2FA secret
openssl rand -hex 32
# PostgreSQL 密码。用 hex 而不是 base64,避免 / + = 等字符需要 URL 编码
openssl rand -hex 24
3.5.0 之前,没有设置 APP_SECRET 时 Umami 会退回到用 DATABASE_URL 派生密钥;这个回退在 3.5.0 被移除,空值或占位符 replace-me-with-a-random-string 会被拒绝。
从旧版本升级时,如果之前从未设置过 APP_SECRET,可以临时把它设为 DATABASE_URL 的原值,以保持现有会话;之后再换成独立的随机值。换值会让所有人重新登录。
TWO_FACTOR_ENCRYPTION_KEY 是 64 位十六进制字符串(256 位),用于加密用户的 2FA secret。这个值要长期保存:换了之后,已经启用 2FA 的账户会无法验证。
环境变量文件
将敏感信息写入 .env 文件,与 docker-compose.yml 分离:
cat > /opt/umami/.env << 'EOF'
# PostgreSQL
POSTGRES_DB=umami
POSTGRES_USER=umami
POSTGRES_PASSWORD=<替换为上面生成的密码>
# Umami
DATABASE_URL=postgresql://umami:<同上密码>@db:5432/umami
APP_SECRET=<替换为 64 位 hex>
TWO_FACTOR_ENCRYPTION_KEY=<替换为另一个 64 位 hex>
# 安全加固
DISABLE_TELEMETRY=1
DISABLE_UPDATES=1
# 如果前面还有 Cloudflare 等多层代理,再按实际情况设置
# TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
EOF
# 限制文件权限,仅 root 可读
chmod 600 /opt/umami/.env
Docker Compose 编排
# /opt/umami/docker-compose.yml
---
services:
umami:
# 官方文档使用的 registry;镜像 tag 是 3.5.0,不是发布页上的 v3.5.0
image: docker.umami.is/umami-software/umami:3.5.0
container_name: umami
ports:
- "127.0.0.1:3000:3000"
env_file:
- .env
environment:
# 反向代理场景下,指定客户端真实 IP 的 Header
CLIENT_IP_HEADER: X-Real-IP
# 自定义追踪端点路径,规避广告拦截器
COLLECT_API_ENDPOINT: /api/collect
# 自定义追踪脚本名称,规避广告拦截器
TRACKER_SCRIPT_NAME: stats.js
depends_on:
db:
condition: service_healthy
init: true
restart: always
healthcheck:
test: ["CMD-SHELL", "curl -sf http://localhost:3000/api/heartbeat || exit 1"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
deploy:
resources:
limits:
memory: 512M
cpus: "1.0"
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
db:
image: postgres:15-alpine
container_name: umami-db
env_file:
- .env
volumes:
- umami-db-data:/var/lib/postgresql/data
# 不暴露端口到宿主机,仅 Docker 内部网络可达
expose:
- "5432"
restart: always
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
deploy:
resources:
limits:
memory: 256M
cpus: "0.5"
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
# PostgreSQL 性能调优参数
command:
- "postgres"
- "-c"
- "shared_buffers=64MB"
- "-c"
- "effective_cache_size=128MB"
- "-c"
- "work_mem=4MB"
- "-c"
- "maintenance_work_mem=32MB"
- "-c"
- "random_page_cost=1.1"
- "-c"
- "log_min_duration_statement=1000"
- "-c"
- "timezone=UTC"
volumes:
umami-db-data:
driver: local
ports绑定127.0.0.1:3000:3000而不是0.0.0.0:3000:3000,确保 Umami 只能通过反向代理访问- PostgreSQL 使用
expose而不是ports,端口仅在 Docker 网络内部可达 .env文件权限设为600,不要提交到 Git
v3.5.0,但 Docker 镜像 tag 是 3.5.0。写成 v3.5.0 会报 manifest unknown。官方文档用的 registry 是 docker.umami.is,ghcr.io/umami-software/umami 上也有同名镜像;生产环境建议固定版本号,不要用 latest。上面的参数是针对小规模站点(日 PV < 50,000)的保守配置:
shared_buffers=64MB:PostgreSQL 用于缓存数据页的共享内存,一般设为可用内存的 25%,这里容器限制 256MB 所以取 64MBeffective_cache_size=128MB:告诉查询规划器操作系统可用于缓存的内存总量,影响索引选择策略work_mem=4MB:单个排序/哈希操作的内存上限,Umami 查询复杂度不高,4MB 足够log_min_duration_statement=1000:记录执行超过 1 秒的慢查询,便于性能排查timezone=UTC:Umami 官方推荐 PostgreSQL 使用 UTC 时区
启动服务
cd /opt/umami
# 拉取镜像并启动
docker compose up -d
# 查看容器状态
docker compose ps
# 查看 Umami 启动日志,确认无报错
docker compose logs -f umami
第一次启动时,Umami 会检查数据库连接并执行 Prisma 迁移。实际日志里能看到:
umami | ✓ DATABASE_URL is defined.
umami | ✓ Database connection successful.
umami | ✓ Database version check successful.
umami | 27 migrations found in prisma/migrations
等两个容器都变成 healthy 后,直接访问 Umami 的 3000 端口确认服务已经起来:
curl -s http://127.0.0.1:3000/api/heartbeat
# {"ok":true}
初始登录与密码修改
Umami 首次启动会自动创建默认管理员账户:
- 用户名:
admin - 密码:
umami
3.5.0 起,用默认密码登录后会强制要求修改密码才能继续。密码修改入口在 Settings -> Security,旧版本在 Profile 页面。
登录后顺便启用 2FA。前提是 .env 里已经设置了 TWO_FACTOR_ENCRYPTION_KEY,否则 2FA 无法启用。
Nginx 反向代理配置
以下配置假设你已经有了 TLS 证书(通过 Certbot 或其他方式获取):
# /etc/nginx/sites-available/analytics.example.com
server {
listen 80;
listen [::]:80;
server_name analytics.example.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name analytics.example.com;
# TLS 证书
ssl_certificate /etc/letsencrypt/live/analytics.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/analytics.example.com/privkey.pem;
# TLS 安全参数
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;
# HSTS。确认所有子域都走 HTTPS 后再加 preload
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
# 安全响应头
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
# 访问日志
access_log /var/log/nginx/analytics.access.log;
error_log /var/log/nginx/analytics.error.log;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
# 传递客户端真实 IP
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_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
}
# 追踪脚本缓存:脚本内容不常变化,客户端可以缓存
location = /stats.js {
proxy_pass http://127.0.0.1:3000/stats.js;
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;
# 缓存 1 天
expires 1d;
}
}
expires 1d 本身会生成 Cache-Control: max-age=86400。如果再写一行 add_header Cache-Control "public, immutable",响应里会出现两个 Cache-Control 头。保留一个就好。这台虚拟机的 443 已经被 k3s 的 Traefik 占用,8443 是 step-ca,所以 Nginx 监听 9443,证书由 step-ca 签发。验证时用 --resolve 把域名指到本机,并加 -k 跳过客户端对私有 CA 的信任检查;浏览器里需要先把 Homelab Root CA 装进信任链。公网部署换成 443 和公网证书即可,代理配置不变。
内网证书的签发和续期见之前的 Homelab 证书管理实战。
启用配置并验证:
# 创建软链接启用站点
ln -s /etc/nginx/sites-available/analytics.example.com /etc/nginx/sites-enabled/
# 验证配置语法
nginx -t
# 重载 Nginx
systemctl reload nginx
# 测试 HTTPS 访问
curl -s -o /dev/null -w "%{http_code}\n" https://analytics.example.com/api/heartbeat
# 200

添加站点与集成 Hugo
在 Umami 中添加站点
- 登录 Umami 管理后台
https://analytics.example.com - 在左侧导航进入 Websites,点击 Add website
- 填写站点名称(如
blog.plz.ac)和域名 - 保存后会生成一个 Website ID(UUID 格式),记录下来
Hugo DoIt 主题集成
DoIt 主题 的 themes/DoIt/layouts/_partials/plugin/analytics.html 已经内置 Umami 分支,在 config.toml 中配置即可:
[params.analytics]
enable = true
[params.analytics.umami]
data_website_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # 替换为你的 Website ID
src = "https://analytics.example.com/stats.js" # 追踪脚本地址
data_host_url = "https://analytics.example.com" # Umami 实例地址
data_domains = "blog.plz.ac" # 限定域名,防止开发环境误报数据
注意 src 中使用的是 stats.js 而不是默认的 script.js。这与 docker-compose.yml 中设置的 TRACKER_SCRIPT_NAME: stats.js 对应。
自定义脚本名称和端点路径是规避广告拦截器的有效手段。大多数拦截规则针对的是 script.js 和 /api/send 这类默认路径,改名后可以显著提高数据采集的完整性。
如果你想同时保留 Google Analytics 作为对照,两者可以共存:
[params.analytics]
enable = true
[params.analytics.google]
id = "G-XXXXXXXXXX"
anonymizeIP = true
[params.analytics.umami]
data_website_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
src = "https://analytics.example.com/stats.js"
data_host_url = "https://analytics.example.com"
data_domains = "blog.plz.ac"
手动集成(非 DoIt 主题)
如果你使用的 Hugo 主题不原生支持 Umami,可以在模板的 <head> 中手动添加:
<!-- Umami Analytics -->
<script
defer
src="https://analytics.example.com/stats.js"
data-website-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
data-host-url="https://analytics.example.com"
data-domains="blog.plz.ac"
></script>
关键属性说明:
| 属性 | 作用 |
|---|---|
defer |
异步加载,不阻塞页面渲染 |
data-website-id |
站点唯一标识,从 Umami 后台获取 |
data-host-url |
Umami 实例地址,跨域部署时必填 |
data-domains |
限定追踪域名,避免本地开发环境污染数据 |
data-do-not-track |
设为 "true" 则尊重浏览器的 DNT 设置 |
data-auto-track |
设为 "false" 可关闭自动追踪,改用 JS API 手动上报 |
验证
容器与心跳
# 容器健康状态
docker compose ps
# API 心跳检测
curl -s http://127.0.0.1:3000/api/heartbeat
# {"ok":true}
# 经 Nginx 访问心跳
curl -s -o /dev/null -w "%{http_code}\n" https://analytics.example.com/api/heartbeat
# 200

追踪脚本与采集端点
# 确认脚本可以正常加载
curl -sI https://analytics.example.com/stats.js | head -5
# HTTP/2 200
# content-length: 9300
实测 stats.js 未压缩时是 9300 字节,gzip 后约 4 KB。
再验证一次采集端点。COLLECT_API_ENDPOINT 设为 /api/collect 后,追踪脚本会把数据 POST 到这个路径:
curl -s -o /dev/null -w "%{http_code}\n" \
-X POST https://analytics.example.com/api/collect \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 ... Chrome/140.0 Safari/537.36" \
-d '{
"type": "event",
"payload": {
"website": "<website-id>",
"hostname": "blog.plz.ac",
"url": "/nginx-collect-test",
"referrer": "",
"title": "Nginx collect test",
"language": "zh-CN",
"screen": "1440x900"
}
}'
# 200
返回体里带 sessionId 和 visitId。我在实验环境里对比了写入前后的 website_event 行数,从 1 变成 2,说明请求确实经过 Nginx 落到了数据库。
浏览器端上报
最后用一个最小页面验证浏览器端的 stats.js:
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>Umami tracking test</title>
<script defer
src="https://analytics.example.com/stats.js"
data-website-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
data-host-url="https://analytics.example.com"></script>
</head>
<body>
<h1>Umami tracking test</h1>
<p>This page is used to verify the tracker and collect endpoint.</p>
</body>
</html>
打开页面后,Umami 仪表盘里出现了 1 个访客、1 次访问、1 次浏览,路径为 /,浏览器识别为 Chrome。截图里的数据就是这次测试产生的:

客户端 IP 验证
反向代理场景下最容易出问题的是客户端 IP 传递。验证步骤:
# 查看 Nginx 访问日志中记录的客户端 IP
tail -5 /var/log/nginx/analytics.access.log
# 在 Umami 仪表盘查看 Locations 数据
# 如果所有访客都显示为同一个 IP 或同一个地区,说明 IP 传递有问题
如果 IP 不正确,排查方向:
- 检查 Nginx 是否设置了
proxy_set_header X-Real-IP $remote_addr - 检查 Umami 的
CLIENT_IP_HEADER环境变量是否设为X-Real-IP - 如果前面还有 CDN(如 Cloudflare),需要改用
CF-Connecting-IP,并按 3.5.0 的TRUSTED_PROXIES配置多层代理地址
数据排除验证
确认自己的 IP 不会被统计(可选):
# 在 .env 中添加排除 IP
echo 'IGNORE_IP=你的公网IP/32' >> /opt/umami/.env
# 环境变量在创建容器时读取,修改 .env 后需要重建容器
docker compose up -d --force-recreate umami
安全加固
网络层面
graph LR
A[公网] -->|"443/tcp"| B[Nginx]
B -->|"127.0.0.1:3000"| C[Umami]
C -->|"Docker 内部网络"| D[(PostgreSQL)]
style A fill:#ffcdd2
style B fill:#c8e6c9
style C fill:#fff3e0
style D fill:#e8f5e9
防火墙规则(仅开放必要端口):
# 使用 ufw 的场景
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp comment 'SSH'
ufw allow 80/tcp comment 'HTTP redirect'
ufw allow 443/tcp comment 'HTTPS'
ufw enable
# 确认 3000 端口没有暴露到公网
ss -tlnp | grep 3000
# 应该只看到 127.0.0.1:3000
0.0.0.0 的容器端口不一定受 ufw 约束。本文把 Umami 绑定在 127.0.0.1,PostgreSQL 只用 expose,所以这两个端口不依赖 ufw 拦截。应用层面
关键环境变量的安全含义:
| 变量 | 值 | 说明 |
|---|---|---|
APP_SECRET |
64 位 hex | 3.5.0 起必填,签名登录令牌并参与匿名会话 ID 派生 |
TWO_FACTOR_ENCRYPTION_KEY |
64 位 hex | 加密 2FA secret,启用 2FA 前必须设置并长期保存 |
DISABLE_TELEMETRY |
1 |
禁止向 Umami 官方发送匿名遥测数据 |
DISABLE_UPDATES |
1 |
禁止后台检查更新(减少外部网络调用) |
IGNORE_IP |
管理员 IP | 排除自身 IP,避免统计数据失真 |
CLIENT_IP_HEADER |
X-Real-IP |
确保通过反向代理获取真实客户端 IP |
TRUSTED_PROXIES |
代理网段 | 多层代理时使用,避免伪造的 X-Forwarded-For 被信任 |
TRACKER_SCRIPT_NAME |
stats.js |
规避广告拦截器的默认规则 |
COLLECT_API_ENDPOINT |
/api/collect |
同上,自定义采集端点路径 |
容器层面
docker-compose.yml 中已经做了以下加固:
- 资源限制:
deploy.resources.limits防止容器异常消耗资源 - 日志轮转:
logging.options限制单文件 10MB、最多 3 个文件,防止磁盘被日志撑满 - 端口隔离:PostgreSQL 不暴露到宿主机,Umami 仅绑定
127.0.0.1 - init 进程:
init: true确保容器内僵尸进程被正确回收
定期更新
Umami 基于 Next.js 构建,Next.js 的安全漏洞会直接影响 Umami。建议关注 Umami 的 GitHub Releases 页面,及时更新:
cd /opt/umami
# 修改 docker-compose.yml 里的镜像 tag 后拉取
docker compose pull
# 滚动更新(先停旧容器再启新容器)
docker compose up -d --force-recreate
# 确认更新后服务正常
docker compose ps
curl -s http://127.0.0.1:3000/api/heartbeat
27_add_error_tracking),备份可以在迁移出问题时留一条退路。备份与恢复
备份策略
graph TB
A[(PostgreSQL)] -->|"pg_dump -Fc"| B[压缩备份文件]
B -->|"zstd 压缩"| C[本地备份目录]
C -->|"rclone sync"| D[S3 对象存储]
C -->|"保留 30 天"| E[自动清理旧备份]
F[Cron 定时任务] -->|"每天 03:00"| A
F -->|"每天 03:30"| C
style A fill:#e8f5e9
style D fill:#fce4ec
备份规格:
| 指标 | 值 |
|---|---|
| 备份频率 | 每天凌晨 3:00 |
| 本地保留 | 30 天 |
| 远端备份 | S3 兼容对象存储 |
| 压缩格式 | pg_dump custom format + zstd |
| RPO | 24 小时 |
| RTO | < 30 分钟 |
自动备份脚本
脚本依赖宿主机的 zstd。Debian 12 上如果还没装,先执行 apt install zstd;远端同步还需要安装并配置 rclone。
#!/usr/bin/env bash
# /opt/umami/scripts/backup.sh
# Umami PostgreSQL 自动备份脚本
set -euo pipefail
# ---- 配置 ----
BACKUP_DIR="/opt/umami/backups"
CONTAINER_NAME="umami-db"
DB_USER="umami"
DB_NAME="umami"
RETENTION_DAYS=30
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/umami_${DATE}.sql.zst"
# 远端备份配置 (可选,需要安装 rclone)
RCLONE_REMOTE="s3:umami-backups"
ENABLE_REMOTE_BACKUP=false
# ---- 日志函数 ----
log() {
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"
}
# ---- 前置检查 ----
if ! docker inspect -f '{{.State.Running}}' "${CONTAINER_NAME}" 2>/dev/null | grep -q true; then
log "ERROR: 容器 ${CONTAINER_NAME} 不存在或未运行"
exit 1
fi
mkdir -p "${BACKUP_DIR}"
# ---- 执行备份 ----
log "开始备份 Umami 数据库..."
docker exec "${CONTAINER_NAME}" \
pg_dump -U "${DB_USER}" -d "${DB_NAME}" -Fc --clean --if-exists \
| zstd -T0 -9 > "${BACKUP_FILE}"
BACKUP_SIZE=$(du -h "${BACKUP_FILE}" | cut -f1)
log "备份完成:${BACKUP_FILE} (${BACKUP_SIZE})"
# ---- 验证备份完整性 ----
if ! zstd -t "${BACKUP_FILE}" 2>/dev/null; then
log "ERROR: 备份文件完整性校验失败"
rm -f "${BACKUP_FILE}"
exit 1
fi
log "备份完整性校验通过"
# ---- 远端同步 ----
if [[ "${ENABLE_REMOTE_BACKUP}" == "true" ]] && command -v rclone &>/dev/null; then
log "同步备份到远端存储..."
rclone copy "${BACKUP_FILE}" "${RCLONE_REMOTE}/" --progress
log "远端同步完成"
fi
# ---- 清理旧备份 ----
DELETED=$(find "${BACKUP_DIR}" -name "umami_*.sql.zst" -type f -mtime "+${RETENTION_DAYS}" -print -delete | wc -l)
if [[ "${DELETED}" -gt 0 ]]; then
log "已清理 ${DELETED} 个超过 ${RETENTION_DAYS} 天的旧备份"
fi
log "备份任务完成"
设置权限和定时任务:
chmod 700 /opt/umami/scripts/backup.sh
# 添加 Cron 定时任务,每天凌晨 3:00 执行
cat > /etc/cron.d/umami-backup << 'EOF'
# Umami 数据库每日备份
0 3 * * * root /opt/umami/scripts/backup.sh >> /var/log/umami-backup.log 2>&1
EOF
# 手动执行一次验证
/opt/umami/scripts/backup.sh
我在实验环境执行了这套备份命令,生成的 umami_20261115_030147.sql.zst 为 12 KB,zstd -t 校验通过。
随后把备份恢复到一个临时库 umami_restore_test:website 和 website_event 的行数与源库一致(1 个站点、2 条事件)。恢复脚本没有直接覆盖正在使用的库。
恢复脚本
#!/usr/bin/env bash
# /opt/umami/scripts/restore.sh
# Umami PostgreSQL 恢复脚本
set -euo pipefail
CONTAINER_NAME="umami-db"
DB_USER="umami"
DB_NAME="umami"
BACKUP_DIR="/opt/umami/backups"
log() {
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*"
}
# ---- 参数检查 ----
if [[ $# -lt 1 ]]; then
echo "用法: $0 <备份文件路径>"
echo ""
echo "可用备份:"
ls -lht "${BACKUP_DIR}"/umami_*.sql.zst 2>/dev/null | head -10
exit 1
fi
BACKUP_FILE="$1"
if [[ ! -f "${BACKUP_FILE}" ]]; then
log "ERROR: 备份文件不存在: ${BACKUP_FILE}"
exit 1
fi
# ---- 完整性校验 ----
log "校验备份文件完整性..."
if ! zstd -t "${BACKUP_FILE}" 2>/dev/null; then
log "ERROR: 备份文件损坏"
exit 1
fi
# ---- 确认操作 ----
log "即将恢复数据库,当前数据将被覆盖!"
read -rp "确认继续?(输入 yes): " CONFIRM
if [[ "${CONFIRM}" != "yes" ]]; then
log "操作已取消"
exit 0
fi
# ---- 停止 Umami ----
log "停止 Umami 服务..."
cd /opt/umami
docker compose stop umami
# ---- 恢复数据库 ----
log "开始恢复数据库..."
zstd -d "${BACKUP_FILE}" --stdout \
| docker exec -i "${CONTAINER_NAME}" \
pg_restore -U "${DB_USER}" -d "${DB_NAME}" --clean --if-exists --no-owner --no-privileges
# ---- 重启服务 ----
log "重启 Umami 服务..."
docker compose start umami
# ---- 验证 ----
sleep 10
if curl -sf http://127.0.0.1:3000/api/heartbeat > /dev/null; then
log "恢复完成,服务运行正常"
else
log "WARNING: 服务可能未正常启动,请检查日志: docker compose logs umami"
fi
chmod 700 /opt/umami/scripts/restore.sh
恢复演练
定期进行恢复演练是验证备份有效性的唯一可靠手段:
# 列出可用备份
ls -lht /opt/umami/backups/
# 恢复最近的备份
/opt/umami/scripts/restore.sh /opt/umami/backups/umami_20261115_030147.sql.zst
监控与告警
容器健康检查
docker-compose.yml 中已配置了容器级健康检查。查看状态:
# 查看所有容器健康状态
docker compose ps
# 输出示例:
# NAME IMAGE STATUS PORTS
# umami docker.umami.is/umami-software/umami:3.5.0 Up 2 hours (healthy) 127.0.0.1:3000->3000/tcp
# umami-db postgres:15-alpine Up 2 hours (healthy) 5432/tcp
外部拨测脚本
如果你有 Prometheus + Alertmanager 或其他监控系统,可以通过 blackbox exporter 拨测 /api/heartbeat 端点。以下是一个简单的独立监控脚本:
#!/usr/bin/env bash
# /opt/umami/scripts/check_health.sh
# 简易健康检查脚本,配合 Cron 使用
UMAMI_URL="https://analytics.example.com/api/heartbeat"
ALERT_EMAIL="[email protected]"
RESPONSE=$(curl -sf -o /dev/null -w "%{http_code}" --max-time 10 "${UMAMI_URL}")
if [[ "${RESPONSE}" != "200" ]]; then
echo "Umami 健康检查失败 (HTTP ${RESPONSE})" \
| mail -s "[ALERT] Umami Service Down" "${ALERT_EMAIL}"
fi
# 每 5 分钟检查一次
cat >> /etc/cron.d/umami-backup << 'EOF'
# Umami 健康检查
*/5 * * * * root /opt/umami/scripts/check_health.sh 2>/dev/null
EOF
Prometheus 集成(可选)
如果已有 Prometheus 监控体系,可以通过 blackbox exporter 进行 HTTP 探测:
# blackbox.yml 中添加
modules:
umami_heartbeat:
prober: http
timeout: 10s
http:
valid_http_versions: ["HTTP/1.1", "HTTP/2.0"]
valid_status_codes: [200]
method: GET
preferred_ip_protocol: "ip4"
# prometheus.yml 中添加 scrape 配置
scrape_configs:
- job_name: 'umami'
metrics_path: /probe
params:
module: [umami_heartbeat]
target: ['https://analytics.example.com/api/heartbeat']
static_configs:
- targets: ['blackbox-exporter:9115']
relabel_configs:
- source_labels: [__address__]
target_label: __param_target
- source_labels: [__param_target]
target_label: instance
- target_label: __address__
replacement: blackbox-exporter:9115
故障排查
常见问题与解决方案
1. 镜像拉不下来,或者 tag 不存在
发布页写的是 v3.5.0,镜像 tag 是 3.5.0;写成 v3.5.0 会报 manifest unknown。官方 registry 是 docker.umami.is,如果服务器访问不了 Docker Hub 或官方 registry,可以在能联网的机器上 docker pull,然后用 docker save、scp、docker load 把镜像搬到目标机器。实验环境里的 PostgreSQL 镜像就是这样导入的。
2. 443 端口被其他服务占用
ss -tlnp | grep ':443'
# 看占用者是谁
如果机器上已经有 Traefik、Nginx 或别的反向代理,不要硬抢 443。可以让现有代理转发到 Umami,或者像实验环境一样让 Nginx 监听 9443。配置完用 curl -k 直接访问端口确认,再处理 DNS 和证书。
3. 追踪脚本被广告拦截器屏蔽
现象:浏览器 Network 中看不到 stats.js 的请求,或请求被标记为 blocked。
解决:确认 TRACKER_SCRIPT_NAME 和 COLLECT_API_ENDPOINT 已自定义为非默认值。如果仍被拦截,可以通过自己的域名路径代理脚本:
# 在博客站点的 Nginx 配置中添加
location = /js/s.js {
proxy_pass https://analytics.example.com/stats.js;
proxy_set_header Host analytics.example.com;
proxy_ssl_server_name on;
}
然后将 Hugo 配置中的 src 改为 /js/s.js。
4. 地理位置数据全部为 Unknown
现象:仪表盘的 Locations 区域显示所有访客位置为 Unknown。
解决:Umami v3 默认依赖 IP 地理定位。先确认客户端 IP 已经正确传到 Umami(见上一节的 CLIENT_IP_HEADER),再检查 GeoIP 数据库:
# 3.5.0 镜像自带 GeoLite2-City.mmdb,正常情况这里应该有文件
docker exec umami ls -lh /app/geo/
# 如果为空,可以手动指定 GeoIP 数据库 URL
# 在 .env 中添加:
# GEO_DATABASE_URL=https://your-geoip-db-url/GeoLite2-City.mmdb
实验环境里这个文件约 48 MB,随镜像一起提供。也可以换成自己下载的 MaxMind GeoLite2 数据库(需要注册获取 License Key)。
5. PostgreSQL 连接被拒绝
# 检查数据库容器是否健康
docker compose ps db
# 查看数据库日志
docker compose logs db | tail -20
# 检查连接数
docker exec umami-db psql -U umami -d umami -c "SELECT count(*) FROM pg_stat_activity;"
6. Umami 容器持续重启
# 查看退出原因
docker inspect umami --format='{{.State.ExitCode}}'
# 查看最近的日志
docker compose logs --tail=50 umami
# 常见原因:
# - APP_SECRET 为空或还是占位符(3.5.0 起必填)
# - DATABASE_URL 格式错误或密码不匹配
# - PostgreSQL 尚未准备好(healthcheck 可以解决)
# - 端口 3000 被其他进程占用
7. 数据量增长与清理
长时间运行后,数据库体积可能增长较快。查看当前大小:
docker exec umami-db psql -U umami -d umami -c \
"SELECT pg_size_pretty(pg_database_size('umami'));"
Umami 后台 Settings -> Websites -> Edit 中可以设置数据保留期限,或手动清理旧数据。
运维备忘
日常命令速查
# 查看服务状态
docker compose -f /opt/umami/docker-compose.yml ps
# 查看实时日志
docker compose -f /opt/umami/docker-compose.yml logs -f
# 重启服务
docker compose -f /opt/umami/docker-compose.yml restart
# 更新到固定版本
cd /opt/umami && docker compose pull && docker compose up -d --force-recreate
# 手动备份
/opt/umami/scripts/backup.sh
# 查看数据库大小
docker exec umami-db psql -U umami -d umami -c "SELECT pg_size_pretty(pg_database_size('umami'));"
# 进入数据库终端
docker exec -it umami-db psql -U umami -d umami
版本升级检查清单
- 阅读 Release Notes,确认是否有破坏性变更
- 执行数据库备份:
/opt/umami/scripts/backup.sh - 修改
docker-compose.yml中的镜像 tag - 拉取新镜像:
docker compose pull - 重建容器:
docker compose up -d --force-recreate - 检查日志:
docker compose logs -f umami - 验证健康检查:
curl -s http://127.0.0.1:3000/api/heartbeat - 访问仪表盘确认功能正常
从 3.5.0 起,升级还要额外确认两件事:APP_SECRET 已经显式设置;默认管理员密码已经改掉(新版本会强制要求修改)。如果从更早的版本升级并且从未设置过 APP_SECRET,先看前面关于 APP_SECRET 的说明,避免升级后所有人被登出。
参考资料
如果你觉得这篇文章对你有所帮助,欢迎赞赏~
赞赏