umami-setup — Add analytics to a new website
Overview
Self-hosted Umami analytics with a same-domain proxy to bypass adblockers. The script is served from the same domain as your site, so blockers see it as first-party.
Prerequisites
- - A running Umami instance (self-hosted, e.g.
analytics.casys.ai) - Admin credentials for Umami
- Access to the website's codebase for proxy configuration
Step 1: Create the website in Umami
CODEBLOCK0
Save the id from the response — that's your data-website-id.
Step 2: Set up the proxy
The proxy serves the Umami script and send endpoint from your own domain. Adblockers can't distinguish it from your own assets.
Pick the method matching your stack:
Next.js (rewrites in next.config.ts)
CODEBLOCK1
Then add to your layout:
CODEBLOCK2
Astro + Vercel (rewrites in vercel.json)
CODEBLOCK3
Then add before </head> in your layout(s):
CODEBLOCK4
Caddy (reverse proxy)
CODEBLOCK5
Nginx
CODEBLOCK6
Step 3: Verify
- 1. Deploy the proxy config
- Visit your site in a browser
- Check Umami dashboard — you should see a pageview within seconds
- Test with adblocker enabled — visit again with uBlock Origin on; the pageview should still appear
- Verify the proxy works:
curl -sI https://<YOUR_DOMAIN>/u/script.js should return 200
Proxy path convention
Use /u/ as the proxy prefix. It's short, non-obvious to blockers, and consistent across projects:
| Project | Proxy path | Umami host |
|---|
| thenocodeguy.com | INLINECODE6 | analytics.casys.ai |
| casys.ai |
/u/script.js | analytics.casys.ai |
Umami API — quick reference
CODEBLOCK7
Notes
- - The Umami instance should be behind a reverse proxy with HTTPS (e.g. Cloudflare → Caddy → localhost:3002)
- Docker bind on
127.0.0.1 only — never expose Umami directly to the internet - The
/u/ prefix can be anything — /stats/, /t/, etc. — as long as it doesn't conflict with existing routes
umami-setup — 为新网站添加分析功能
概述
自托管Umami分析服务，通过同域代理绕过广告拦截器。脚本与您的网站来自同一域名，因此广告拦截器会将其视为第一方资源。
前置条件
- - 运行中的Umami实例（自托管，例如 analytics.casys.ai）
- Umami的管理员凭据
- 可访问网站代码库以配置代理
步骤1：在Umami中创建网站
bash
登录
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脚本和发送端点。广告拦截器无法将其与您自己的资源区分开来。
根据您的技术栈选择相应方法：
Next.js（在next.config.ts中重写）
typescript
// 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,
},
];
},
};
然后添加到布局中：
html
Astro + Vercel（在vercel.json中重写）
json
{
rewrites: [
{
source: /u/script.js,
destination: https:///script.js
},
{
source: /u/api/send,
destination: https:///api/send
}
]
}
然后在布局的 之前添加：
html
Caddy（反向代理）
caddyfile
example.com {
handle /u/script.js {
rewrite * /script.js
reverseproxy https://HOST> {
headerup Host HOST>
}
}
handle /u/api/send {
rewrite * /api/send
reverseproxy https://HOST> {
headerup Host HOST>
}
}
}
Nginx
nginx
location /u/script.js {
proxypass https://HOST>/script.js;
proxysetheader Host ;
}
location /u/api/send {
proxypass https://HOST>/api/send;
proxysetheader Host ;
}
步骤3：验证
- 1. 部署代理配置
- 在浏览器中访问您的网站
- 检查Umami仪表盘 —— 您应该会在几秒内看到页面浏览量
- 启用广告拦截器测试 —— 开启uBlock Origin后再次访问；页面浏览量仍应显示
- 验证代理是否正常工作：curl -sI https:///u/script.js 应返回200
代理路径约定
使用 /u/ 作为代理前缀。它简短、对拦截器不明显，且跨项目保持一致：
| 项目 | 代理路径 | Umami主机 |
|---|
| thenocodeguy.com | /umami/script.js | analytics.casys.ai |
| casys.ai |
/u/script.js | analytics.casys.ai |
Umami API — 快速参考
bash
获取所有网站
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://HOST>/api/websites/ID>/stats?startAt=$START&endAt=$END
获取页面浏览量
curl -s -H Authorization: Bearer $TOKEN \
https://HOST>/api/websites/ID>/pageviews?startAt=$START&endAt=$END&unit=day
注意事项
- - Umami实例应位于带有HTTPS的反向代理之后（例如 Cloudflare → Caddy → localhost:3002）
- Docker仅绑定 127.0.0.1 —— 切勿将Umami直接暴露在互联网上
- /u/ 前缀可以是任何内容 —— /stats/、/t/ 等 —— 只要不与现有路由冲突即可
