AKASHIC ZERO

セルフホスト Umami の PV がずっと 0 件だった原因──リバースプロキシの CORS Preflight と `x-umami-*` ヘッダの罠

Cookie レスのアクセス解析ツール **Umami** をセルフホストし、静的サイトへ `<script defer src="https://analytics.example.com/script.js" data-website-id="...">` を埋め込んだにもかかわらず、管理画面の

一次検証Fail-ClosedSQLite実測ログ無料公開

# セルフホスト 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-cache
  • x-umami-hostname
  • x-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
FREE TECHNICAL BRIEFING

実測ポストモーテム・修正パッチの続報を受け取る

一次検証データ・Fail-Closed 境界実装・新規無料記事の公開時にのみ配信します(広告なし・いつでも1クリック解除可能)。プライバシーポリシーに同意のうえご登録ください。

購読管理フォームを別タブで開く ↗