目录

自托管 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 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 必填

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
# /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
关于镜像 tag
Umami 的 release 页面写的是 v3.5.0,但 Docker 镜像 tag 是 3.5.0。写成 v3.5.0 会报 manifest unknown。官方文档用的 registry 是 docker.umami.is,ghcr.io/umami-software/umami 上也有同名镜像;生产环境建议固定版本号,不要用 latest。
关于 PostgreSQL 参数

上面的参数是针对小规模站点(日 PV < 50,000)的保守配置:

  • shared_buffers=64MB:PostgreSQL 用于缓存数据页的共享内存,一般设为可用内存的 25%,这里容器限制 256MB 所以取 64MB
  • effective_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 无法启用。

以下配置假设你已经有了 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;
    }
}
不要重复设置 Cache-Control
expires 1d 本身会生成 Cache-Control: max-age=86400。如果再写一行 add_header Cache-Control "public, immutable",响应里会出现两个 Cache-Control 头。保留一个就好。
实验环境的 9443 与 step-ca

这台虚拟机的 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

Nginx 配置、step-ca 证书与 stats.js 验证
nginx -t、证书信息和 9443 入口的实测结果

  1. 登录 Umami 管理后台 https://analytics.example.com
  2. 在左侧导航进入 Websites,点击 Add website
  3. 填写站点名称(如 blog.plz.ac)和域名
  4. 保存后会生成一个 Website ID(UUID 格式),记录下来

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"

如果你使用的 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

Umami 与 PostgreSQL 容器均处于 healthy 状态
docker compose ps 与心跳检查

# 确认脚本可以正常加载
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。截图里的数据就是这次测试产生的:

Umami 仪表盘中的测试访问
测试页产生的一次访问:1 Visitor / 1 Visit / 1 View

反向代理场景下最容易出问题的是客户端 IP 传递。验证步骤:

# 查看 Nginx 访问日志中记录的客户端 IP
tail -5 /var/log/nginx/analytics.access.log

# 在 Umami 仪表盘查看 Locations 数据
# 如果所有访客都显示为同一个 IP 或同一个地区,说明 IP 传递有问题

如果 IP 不正确,排查方向:

  1. 检查 Nginx 是否设置了 proxy_set_header X-Real-IP $remote_addr
  2. 检查 Umami 的 CLIENT_IP_HEADER 环境变量是否设为 X-Real-IP
  3. 如果前面还有 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
Docker 与 ufw
Docker 会直接修改 iptables,发布到 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
更新前务必备份
每次更新前先执行一次数据库备份。Umami 启动时会自动执行 Prisma 迁移(3.5.0 是第 27 个迁移 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 监控体系,可以通过 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
  1. 阅读 Release Notes,确认是否有破坏性变更
  2. 执行数据库备份:/opt/umami/scripts/backup.sh
  3. 修改 docker-compose.yml 中的镜像 tag
  4. 拉取新镜像:docker compose pull
  5. 重建容器:docker compose up -d --force-recreate
  6. 检查日志:docker compose logs -f umami
  7. 验证健康检查:curl -s http://127.0.0.1:3000/api/heartbeat
  8. 访问仪表盘确认功能正常

从 3.5.0 起,升级还要额外确认两件事:APP_SECRET 已经显式设置;默认管理员密码已经改掉(新版本会强制要求修改)。如果从更早的版本升级并且从未设置过 APP_SECRET,先看前面关于 APP_SECRET 的说明,避免升级后所有人被登出。