📊 功能简介

Demius 主题从 v2.4.0 版本开始集成了 Umami 访问统计功能，提供了强大的数据分析能力。本文将展示如何配置和使用这一功能。

✨ 主要特性

1. 隐私保护

Umami 是一款注重隐私的统计工具：

  • 🔒 不使用 Cookie：无需 Cookie 同意横幅
  • 🚫 不追踪个人信息：符合 GDPR、CCPA 等隐私法规
  • 🌍 自托管：数据完全掌握在自己手中
  • 📊 聚合数据：只统计匿名的访问数据

2. 实时统计

数据页面提供实时的访问统计信息：

  • 👥 今日访客（UV）：今天的独立访客数
  • 👁 今日浏览（PV）：今天的页面浏览量
  • 📅 昨日数据：昨天的访客和浏览量
  • 📆 长期趋势：本月和本年的累计数据

3. 精美设计

数据展示采用现代化设计：

  • 🎨 渐变色图标，每个指标独特配色
  • 💫 数字递增动画，视觉效果流畅
  • 📈 千分位格式化，大数字更易读
  • 🌓 完美适配暗色模式
  • 📱 响应式布局，手机端友好

🚀 快速开始

步骤 1：部署 Umami 服务

首先需要部署一个 Umami 统计服务。推荐使用 Docker 部署：

# 使用 Docker Compose
version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://username:password@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: your-secret-key
    depends_on:
      - db
    restart: always
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
    volumes:
      - ./umami-db-data:/var/lib/postgresql/data
    restart: always

步骤 2：配置主题

在 hugo.toml 中添加配置：

# ===== Umami统计配置 =====
[params.analytics]
  [params.analytics.umami]
    enable = true                          # 启用Umami统计
    scriptUrl = "https://umami.example.com/script.js"  # 统计脚本地址
    websiteId = "your-website-id"          # 网站ID
    showInDataPage = true                  # 在数据页面显示统计
    apiUrl = "https://api.example.com/"    # API地址

步骤 3：添加数据页面菜单

[[menu.main]]
  name = "数据"
  url = "/data/"
  weight = 7
  [menu.main.params]
    icon = "/img/icons/data.svg"

📈 数据页面展示

访问 /data/ 页面可以查看完整的统计数据。页面包含：

网站统计概览

展示网站的基础数据：

  • 📝 文章总数
  • 🏷️ 标签数量
  • 📂 分类数量
  • 📅 运行天数

Umami 访问统计

实时展示访问数据，每个数据卡片包含：

  • 🎨 彩色图标：使用渐变色，视觉效果出色
  • 📊 大数字显示：清晰展示统计数值
  • 💫 动画效果：数字从 0 递增到实际值
  • 📈 千分位分隔：大数字自动添加逗号

🎯 配置选项详解

基础配置

[params.analytics.umami]
  enable = true  # 总开关，控制是否启用统计跟踪
  • enable = false：完全禁用统计功能
  • enable = true：启用统计跟踪脚本

跟踪脚本配置

scriptUrl = "https://umami.example.com/script.js"
websiteId = "30e2c640-c868-4e89-a138-3c541c2049d5"
  • scriptUrl：你的 Umami 服务器地址 + /script.js
  • websiteId：在 Umami 后台创建网站后获得的 ID

数据页面配置

showInDataPage = true
apiUrl = "https://api.example.com/"
  • showInDataPage：是否在数据页面显示统计信息
  • apiUrl：提供统计数据的 API 地址

🔧 API 配置

如果要使用数据页面功能，需要创建一个 API 来提供统计数据。

API 返回格式

{
  "today_uv": 123,
  "today_pv": 456,
  "yesterday_uv": 89,
  "yesterday_pv": 234,
  "month_pv": 5678,
  "year_pv": 12345
}

CORS 配置

如果 API 和网站在不同域名，需要配置 CORS：

<?php
// PHP中添加CORS头
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type, Authorization');

// 处理OPTIONS预检请求
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204);
    exit();
}
?>

💡 使用技巧

1. 简单请求避免预检

主题使用"简单请求"方式调用 API，不会触发 OPTIONS 预检：

// 不添加自定义headers，避免预检请求
const response = await fetch(apiUrl);

这样可以简化 CORS 配置，提高加载速度。

2. 启用缓存优化性能

建议在 API 端启用缓存（如 10 分钟），减少对 Umami 服务器的请求：

// PHP缓存示例
$cache_file = 'umami_cache.json';
$cache_time = 600; // 10分钟

if (file_exists($cache_file) && (time() - filemtime($cache_file)) < $cache_time) {
    echo file_get_contents($cache_file);
    exit;
}

3. 骨架屏加载体验

数据页面使用骨架屏，在数据加载时提供更好的用户体验：

.loading-skeleton {
  width: 100%;
  height: 2rem;
  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
  animation: skeleton-loading 1.5s infinite;
}

4. 错误处理

当 API 请求失败时，页面会显示友好的错误提示：

  • 📡 网络错误：提示检查网络连接
  • 🔒 CORS 错误：提示配置跨域访问
  • ⚠️ API 错误：显示具体的错误信息

🎨 样式自定义

如果想自定义数据卡片的颜色，可以修改 CSS：

/* 今日访客卡片 */
.analytics-icon.today-uv {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

/* 今日浏览卡片 */
.analytics-icon.today-pv {
  background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
}

/* 昨日访客卡片 */
.analytics-icon.yesterday-uv {
  background: linear-gradient(135deg, #4facfe 0%, #00f2fe 100%);
}

/* 昨日浏览卡片 */
.analytics-icon.yesterday-pv {
  background: linear-gradient(135deg, #43e97b 0%, #38f9d7 100%);
}

/* 本月浏览卡片 */
.analytics-icon.month-pv {
  background: linear-gradient(135deg, #fa709a 0%, #fee140 100%);
}

/* 本年浏览卡片 */
.analytics-icon.year-pv {
  background: linear-gradient(135deg, #30cfd0 0%, #330867 100%);
}

🐛 常见问题

1. 统计脚本不生效？

检查清单：

  • ✅ enable 是否为 true
  • ✅ scriptUrl 是否正确
  • ✅ websiteId 是否正确
  • ✅ Umami 服务器是否正常运行
  • ✅ 浏览器控制台是否有错误

2. 数据页面显示"加载失败"？

可能原因：

  • 🔗 API 地址不可访问
  • 🔒 CORS 配置不正确
  • 📊 API 返回数据格式错误
  • ⏱️ API 响应超时

解决方法：

  1. 在浏览器中直接访问 API 地址，检查是否返回数据
  2. 查看浏览器控制台的具体错误信息
  3. 检查 API 服务器的错误日志
  4. 确保 API 正确处理 OPTIONS 请求

3. 所有数据都显示为 0？

检查步骤：

  1. 确认 Umami 后台有数据记录
  2. 检查 API 的时间戳计算是否正确
  3. 验证 API 返回的数据格式
  4. 查看 API 服务器日志

📚 相关文档

🎯 实际效果

访问本站的 数据页面 查看实际运行效果！

你会看到：

  • 🎨 精美的数据卡片布局
  • 💫 流畅的数字递增动画
  • 📊 实时更新的访问统计
  • 🌓 完美适配的暗色模式
  • 📱 友好的移动端显示

🎉 总结

Umami 统计功能为 Demius 主题带来了：

  1. ✅ 隐私保护：符合隐私法规，无需 Cookie
  2. ✅ 实时监控：掌握网站访问情况
  3. ✅ 精美设计：现代化的数据可视化
  4. ✅ 易于配置：简单的配置即可启用
  5. ✅ 完全免费：开源自托管，永久免费

开始使用 Umami 统计，让数据为你的内容创作提供指导！📈

提示：更多配置细节请参考主题使用文档