umami-setup — 为新网站添加分析功能

概述

自托管 Umami 分析服务，并通过同域代理绕过广告屏蔽器。该脚本从你的网站同域名下提供服务，因此屏蔽器将其识别为第一方资源。

前提条件

• 一个正在运行的 Umami 实例（自托管，例如 analytics.casys.ai）
• Umami 的管理员凭据
• 对网站代码库的访问权限，用于配置代理

步骤 1：在 Umami 中创建网站

# 登录
TOKEN=$(curl -s -X POST "https:///api/auth/login" 
  -H "Content-Type: application/json" 
  -d '{"username":"admin","password":""}' 
  | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")

# 创建网站
curl -s -X POST "https:///api/websites" 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"name":"","domain":""}' | python3 -m json.tool

保存响应中的 id 字段值 —— 这就是你的 data-website-id。

步骤 2：配置代理

代理将 Umami 的脚本文件和发送端点（/api/send）从你自己的域名下提供服务。广告屏蔽器无法将其与你自身的静态资源区分开来。

请根据你的技术栈选择对应方案：

Next.js（在 next.config.ts 中配置重写规则）

// next.config.ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: "/u/script.js",
        destination: "https:///script.js",
      },
      {
        source: "/u/api/send",
        destination: "https:///api/send",
      },
    ];
  },
};

然后在布局文件中加入以下代码：

Astro + Vercel（在 vercel.json 中配置重写规则）

{
  "rewrites": [
    {
      "source": "/u/script.js",
      "destination": "https:///script.js"
    },
    {
      "source": "/u/api/send",
      "destination": "https:///api/send"
    }
  ]
}

然后在布局文件（一个或多个）的 标签前添加以下代码：

Caddy（反向代理配置）

example.com {
    handle /u/script.js {
        rewrite * /script.js
        reverse_proxy https:// {
            header_up Host 
        }
    }
    handle /u/api/send {
        rewrite * /api/send
        reverse_proxy https:// {
            header_up Host 
        }
    }
}

Nginx

location /u/script.js {
    proxy_pass https:///script.js;
    proxy_set_header Host ;
}
location /u/api/send {
    proxy_pass https:///api/send;
    proxy_set_header Host ;
}

步骤 3：验证配置

1. 部署代理配置
2. 在浏览器中访问你的网站
3. 检查 Umami 后台仪表板 —— 几秒内应能看到页面浏览记录
4. 启用广告屏蔽器测试 —— 再次访问网站（使用 uBlock Origin），页面浏览记录仍应正常上报
5. 验证代理是否生效：运行 curl -sI https:///u/script.js，应返回 HTTP 状态码 200

代理路径命名规范

建议统一使用 /u/ 作为代理路径前缀。它简短、对广告屏蔽器不明显，且在各项目中保持一致：

Umami API — 快速参考

# 获取所有网站列表
curl -s -H "Authorization: Bearer $TOKEN" "https:///api/websites"

# 获取某网站最近 24 小时统计数据
START=$(($(date +%s) * 1000 - 86400000))
END=$(($(date +%s) * 1000))
curl -s -H "Authorization: Bearer $TOKEN" 
  "https:///api/websites//stats?startAt=$START&endAt=$END"

# 获取页面浏览数据（按天聚合）
curl -s -H "Authorization: Bearer $TOKEN" 
  "https:///api/websites//pageviews?startAt=$START&endAt=$END&unit=day"

注意事项

• Umami 实例应部署在支持 HTTPS 的反向代理之后（例如：Cloudflare → Caddy → localhost:3002）
• Docker 应仅绑定到 127.0.0.1，切勿将 Umami 直接暴露于公网
• /u/ 前缀可任意自定义（如 /stats/、/t/ 等），只要不与现有路由冲突即可