流量统计神器 Umami 部署全记录：从 Vercel 翻车到群晖 NAS 完美落地

最近尝试搭建 Umami 统计系统，经历了一场从“云端全家桶（Supabase + Vercel）”到“群晖本地化”的极限拉扯。以下是详细的实战笔记。

第一阶段：云端部署（Supabase + Vercel）—— 惜败

原本计划利用 Supabase (数据库) + Vercel (应用服务) 实现零成本白嫖。

1. 配置流程

   • 数据库：在 Supabase 创建实例，节点选在孟买（Mumbai）。
   • 应用端：将 Umami 源码 Fork 到 GitHub，在 Vercel 中导入并配置环境变量 DATABASE\_URL。
   • 数据库模式：由于 Supabase 的免费额度限制，使用了 Transaction (连接池模式)，并在连接字符串末尾尝试添加 ?pgbouncer=true。

2. 遇坑与失败分析

   • 症状 1：构建无限期假死 Vercel 日志卡在 Database version check successful 后长达 15 分钟无响应。

     • 失败原因：跨国网络延迟导致的 Next.js 静态页面生成 (SSG) 阻塞。Vercel 构建服务器与 Supabase 印度节点之间的数据握手在高频请求下出现丢包，导致构建进程陷入死锁。

   • 症状 2：登录请求 405 (Method Not Allowed) 即便勉强访问到临时域名，点击登录也会报错。

     • 失败原因：Vercel 的 Serverless Functions 尚未完全就绪，或者因构建未完成导致后端 API 路由未被激活。 总结： 云端白嫖虽然诱人，但对于国内环境，复杂的跨国网络握手是最大的敌人。

第二阶段：群晖 NAS 本地化部署 —— 完胜

在云端构建失败后，果断转向内网环境，在群晖 NAS 上使用 Docker 部署。

1. 环境准备

   • 设备：群晖 NAS
   • 工具：Container Manager (Docker)
2. Docker Compose 配置 在 docker/umami 目录下创建 docker-compose.yml：

version: '3'
services:
  db:
    image: postgres:15-alpine
    container_name: umami-db
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: your_strong_password
    volumes:
      - ./postgresql:/var/lib/postgresql/data
    restart: always

  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: umami-app
    ports:
      - "your_pub_port:3000"
    environment:
      DATABASE_URL: postgresql://umami:your_strong_password@db:5432/umami
      APP_SECRET: your_random_secret_string
      DATABASE_TYPE: postgresql
    depends_on:
      - db
    restart: always

3. 本地部署遇到的坑：网络冲突 

   • 报错：failed to create network umami\_default: Pool overlaps with other one…
   • 排查：发现以前部署过同名项目，残留了名为 umami\_default 的 Docker 网络。
   • 解决方法：执行 docker network prune 清理所有不使用的虚拟网络，或手动删除重名的网络。

第三阶段：上线与进阶功能

1. 验证统计是否生效

   • 前端：在博客 加入脚本后，按 F12 查看 Network 请求，找 send 或 collect 接口。
   • 后端：Umami 控制面板 Realtime 出现数据，验证成功。

2. 功能解析

   • 网站 (Websites)：标准 JS 统计，数据最详尽。
   • 链接 (Links)：点击追踪，适用于无法挂脚本的外部链接（如 GitHub Readme）。
   • 像素 (Pixels)：1x1 像素图统计，主要用于邮件追踪。

终极避坑心得

1. 能本地不云端：群晖部署的响应速度比云端快了不止一个量级。
2. 默认信息及时改：部署成功后，第一时间修改默认账号 admin/umami。
3. HTTPS 是必须的：配合反代服务器（如 Nginx Proxy Manager）使用 HTTPS，否则统计脚本可能会被浏览器拦截。

进阶玩法：如何追踪特定“动作”？

如果你想知道用户除了看文章，还点过哪些按钮（比如：下载、赞赏、友链跳转），可以利用 Umami 的 事件追踪 (Event Tracking) 功能。

• 添加方法： 

  • 只需在你想要监测的 HTML 标签（如 <a> 或 <button>）中加入 data-umami-event 属性即可。
  • 代码示例：

<a href="/resume.pdf" data-umami-event="download-resume">下载我的简历</a>
<a href="https://example.com" data-umami-event="friend-link-click" data-umami-event-target="example">访问某某的小站</a>

在后台哪里看？ 进入 Umami 后台，点击对应的网站，切换到 Events (事件) 选项卡，你就能看到这些自定义动作的点击统计了。

总结

从 Vercel 的 15 分钟假死到群晖的 1 分钟丝滑启动，这次折腾让我明白：最适合自己的才是最好的。虽然云端免费资源很香，但在群晖里拥有的掌控感和稳定性，才是折腾党最终的归宿。