# セルフホスト Umami の PV がずっと 0 件だった原因──リバースプロキシの CORS Preflight と x-umami-* ヘッダの罠
Cookie レスのアクセス解析ツール Umami をセルフホストし、静的サイトへ <script defer src="https://analytics.example.com/script.js" data-website-id="..."> を埋め込んだにもかかわらず、管理画面のページビューがずっと 0 件 のまま動かない現象に遭遇しました。
実ブラウザ(Headless Chromium)のコンソールとネットワークログを追った結果、原因はスクリプトの読み込みではなく **リバースプロキシの CORS Preflight(OPTIONS /api/send)設定** にありました。本記事では、実際に踏んだ現象・原因・Node.js プロキシの修正コード・data-umami-event によるクリック計測の E2E 検証手順をまとめます。
1. 発生していた現象
GET https://analytics.example.com/script.jsは HTTP 200 で正常に配信されている- しかし、別オリジン(例:
https://www.example.com)からページを開いてもumami_dbのwebsite_eventテーブルが 0 行のまま - 静的サイトの CSP(Content-Security-Policy)は
script-src/connect-srcともに許可済み
curl で script.js だけ確認していた段階では異常に気づけず、実ブラウザでネットワークエラーを拾って初めて原因が見えました。
2. 根本原因:Umami v2/v3 が送信するカスタムヘッダ x-umami-*
Umami のトラッキングスクリプトは、イベント送信(POST /api/send)の前にブラウザから CORS Preflight(OPTIONS /api/send)を発生させます。このとき、Umami v2/v3 は以下の独自ヘッダをリクエストに含めます。
x-umami-cachex-umami-hostnamex-umami-website-id
一方、手前のリバースプロキシ側で以下のように Access-Control-Allow-Headers を固定値にしていました。
// NG: x-umami-* ヘッダを許可していないため Preflight がブラウザ側でブロックされる
res.setHeader('Access-Control-Allow-Origin', origin);
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept');
この状態では OPTIONS /api/send 自体は 204 を返しても、レスポンスの Access-Control-Allow-Headers に x-umami-* が含まれないため、ブラウザが直後の POST /api/send を送信せずに破棄してしまいます。
3. 修正コード:許可オリジン限定 + x-umami-* 安全許可リスト
ワイルドカード * を無条件に開けるのではなく、信頼済みオリジンのみ に対して x-umami-* ヘッダを動的に許可する形へ修正しました。
const ALLOWED_ORIGINS = new Set([
'https://www.example.com',
'https://example.com',
]);
const SAFE_UMAMI_HEADER_RE = /^x-umami-[a-z0-9-]+$/i;
function applyAnalyticsCorsHeaders(req, res) {
const origin = String(req.headers.origin || '').trim();
if (!ALLOWED_ORIGINS.has(origin)) return false;
const baseHeaders = [
'Content-Type',
'Accept',
'x-umami-cache',
'x-umami-hostname',
'x-umami-website-id',
];
// Preflight が要求したヘッダのうち安全な x-umami-* のみ追加許可
const reqHeaders = String(req.headers['access-control-request-headers'] || '')
.split(',')
.map((h) => h.trim())
.filter((h) => h && (h.toLowerCase() === 'content-type' || h.toLowerCase() === 'accept' || SAFE_UMAMI_HEADER_RE.test(h)));
const allowHeaders = Array.from(new Set([...baseHeaders, ...reqHeaders])).join(', ');
res.setHeader('Access-Control-Allow-Origin', origin);
res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
res.setHeader('Access-Control-Allow-Headers', allowHeaders);
res.setHeader('Access-Control-Max-Age', '86400');
res.setHeader('Vary', 'Origin');
return true;
}
curl による Preflight 単体確認
curl -sS -i -X OPTIONS "https://analytics.example.com/api/send" \
-H "Origin: https://www.example.com" \
-H "Access-Control-Request-Method: POST" \
-H "Access-Control-Request-Headers: content-type,x-umami-cache,x-umami-hostname"
HTTP/2 204 とともに access-control-allow-headers に x-umami-cache, x-umami-hostname が返れば通過です。
4. ページビューだけでなく CTA クリック(event_type = 2)まで測る
PV だけでは「どの導線が押されたか」が分からないため、HTML 要素へ data-umami-event 属性を付与してカスタムイベントも同時計測します。
<a class="button primary" href="#catalog" data-umami-event="hero-cta-catalog">
実践キットを見る
</a>
JS 側からフォーム送信結果などを送る場合は、window.umami 未ロード時でも UX を壊さないガード付きヘルパーを使います。
function trackEvent(eventName, payload = {}) {
try {
if (window.umami && typeof window.umami.track === 'function') {
window.umami.track(eventName, payload);
}
} catch {
// 計測エラーで画面操作を止めない
}
}
5. 実ブラウザ E2E 検証と DB 確認の落とし穴
Headless Chromium で E2E テストを行う際、デフォルトの User-Agent(HeadlessChrome/...)のままアクセスすると Umami 側のボットフィルタに弾かれて DB へ記録されません。検証時は通常の Chrome User-Agent を指定し、確認後に自分のテストセッションだけ DB から消すと本番計測値を汚さずに済みます。
const ctx = await browser.newContext({
userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
});
const page = await ctx.newPage();
await page.goto('https://www.example.com/', { waitUntil: 'networkidle' });
await page.click('a[data-umami-event="hero-cta-catalog"]');
await page.waitForTimeout(1500);
PostgreSQL(umami_db)側で以下のように event_type = 1(ページビュー)と event_type = 2(カスタムイベント)の両方が記録されていれば完通です。
SELECT event_type,
coalesce(nullif(event_name, ''), '(pageview)') AS event_name,
url_path,
count(*)
FROM website_event
WHERE website_id = '<YOUR_WEBSITE_ID>'
GROUP BY 1, 2, 3
ORDER BY 1, 4 DESC;
実環境でも修正直後から POST /api/send が全件 200・コンソールエラー 0 になり、カスタムイベント hero-cta-catalog の記録と実訪問者のセッション取得を確認できました。
関連リソース
- 本記事のWeb版(無料公開): https://www.akashiczero.com/articles/20261119-umami-zero-pv-cors-preflight-fix.html
- 無料技術シミュレーター(LLM VRAM / Fail-Closed ROI 試算): https://www.akashiczero.com/#tools
- 検証済み本番防御コード全集 v2.0(BOOTH ZIP+PDF版・¥500): https://akashiczero.booth.pm/items/9182761
- 無料技術続報(メール配信・1クリック解除可): https://crm.akashiczero.com/subscription/form
- 検証済み本番防御コード全集 v2.0(統合CLI+6モジュール+テスト7/7 PASS+テンプレート一式・note ¥500): https://note.com/shiroi1229/n/n6a67d472363b