网站数据分析工具 Umami 部署

Umami 是目前 Hugo 社区最主流的自建方案之一，它的优势在于：

💡轻量：统计脚本压缩后仅 ~2KB，不影响 Hugo 追求的极致加载速度。
💡隐私：不收集个人数据，不使用 Cookie，不需要像 Google Analytics 那样挂载烦人的隐私声明。
💡兼容：它是 Node.js 应用，官方提供非常成熟的 Docker 镜像。

使用 Docker Compose 部署 Umami

可以直接在现有的docker-compose.yml中添加 Umami 服务，或者单独建立一个。它通常需要配合一个 PostgreSQL 数据库：

# Umami 统计程序
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    restart: always
    container_name: umami-analytics
    environment:
      # 这里的 db 对应下方定义的数据库服务名
      DATABASE_URL: postgresql://username:password@umami-db:5432/umami
      # 建议换成一段随机的长字符串
      APP_SECRET: f44b413524b39e2ab47b
    ports:
      - "3000:3000"
    depends_on:
      - db
    logging:
      driver: "json-file"
      options:
        max-size: "20m" # 单个日志文件最大 10MB
        max-file: "5"   # 最多保留 3 个

# PostgreSQL 数据库
  db:
    image: postgres:15-alpine
    restart: always
    container_name: umami-db
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
      POSTGRES_DB: umami-db
    volumes:
      - ./umami-db-data:/var/lib/postgresql/data # 持久化存储数据
    logging:
      driver: "json-file"
      options:
        max-size: "20m" # 单个日志文件最大 20MB
        max-file: "5"   # 最多保留 5 个

在 Hugo 中集成

部署完成后，在 Umami 管理后台添加网站，获取一段类似这样的 JS 代码。为了符合 Hugo 的规范，建议将其放入layouts/partials/head-custom.html（或主题对应的head部分）：

<script async defer 
  data-website-id="网站ID" 
  src="https://domainname.com/script.js">
</script>

部署与集成步骤

启动服务：在终端执行docker compose up -d。容器启动后，可以通过http://domainname:3000访问 Umami 管理后台。
默认账号：admin
默认密码：umami（登录后请务必立即修改）。
获取统计脚本：登录 Umami 后，点击Settings→Websites→Add Website。填写你的域名（例如 andyio.com ）。点击Edit按钮，找到Tracking Code，你会得到一段类似下面的代码：

<script defer src="http://domainname:3000/script.js" data-website-id="xxxx-xxxx-xxxx"></script>

修改 Hugo 配置：由于使用的是 Hugo，最佳实践是不要直接改主题源码，而是利用 Hugo 的 partials 覆盖机制：在你的 Hugo 项目根目录下，查看是否存在layouts/partials/head.html或类似的头部模板。如果不存在，从主题目录themes/你的主题名/layouts/partials/拷贝一份到根目录对应的位置。将那段Tracking Code粘贴在<head>标签关闭前。

注意事项

反向代理： 如果配置过 Nginx 和 Cloudflare，建议给 Umami 也配一个二级域名（如analytics.domainname.com），并配置 SSL。这样在博客里引用的脚本地址就是加密的 HTTPS 了。

安全性：APP_SECRET和数据库密码建议修改为复杂的私密字符。