feat(analytics): integrate Cloudflare Analytics Engine dashboard (CF-only)

README.md

@@ -49,6 +49,7 @@
 - **边缘原生** — Hono + Cloudflare Workers，无冷启动，全球 < 50ms
 - **存储适配** — 数据库 D1 / Turso / PostgreSQL，对象存储 R2 / S3 兼容
 - **零运维成本** — 单脚本一键部署，前后端走同一条流水线
+- **访客分析** — 内置 D1 `visits` 表轻量统计；**Cloudflare 部署专属**额外解锁 Analytics Engine 增强仪表板（UV/停留时长/浏览器/操作系统/分辨率/语言），其他后端 (Turso / PostgreSQL) 仅基础统计可用
 
 ### 🛡️ 安全合规
 - **认证与防护** — JWT + 限流，CSP/HSTS 全套头，SSRF 拦截

client/public/tracker.js

@@ -0,0 +1,103 @@
+/*!
+ * Monolith Analytics Tracker (CF Analytics Engine)
+ * Adapted from HanAnalytics (MIT) — https://github.com/uxiaohan/HanAnalytics
+ *
+ * 用法：在第三方站点的 </body> 前插入：
+ *   <script defer src="https://your-site.pages.dev/tracker.js"
+ *           data-website-id="my-blog"
+ *           data-endpoint="https://your-worker.workers.dev/api/track"></script>
+ *
+ * 自有站点已通过 React Router 集成，无需手动加载本脚本。
+ */
+(function () {
+  "use strict";
+  var script = document.currentScript || (function () {
+    var s = document.getElementsByTagName("script");
+    return s[s.length - 1];
+  })();
+  if (!script) return;
+
+  var website = script.getAttribute("data-website-id") || "default";
+  var endpoint = script.getAttribute("data-endpoint") || "/api/track";
+  var VID_KEY = "monolith_vid";
+  var VID_TTL = 30 * 24 * 60 * 60 * 1000;
+  var enterAt = 0;
+  var lastPath = "";
+
+  function hash(s) {
+    var h = 0x811c9dc5;
+    for (var i = 0; i < s.length; i++) {
+      h ^= s.charCodeAt(i);
+      h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(36);
+  }
+
+  function vid() {
+    try {
+      var raw = localStorage.getItem(VID_KEY);
+      if (raw) {
+        var p = JSON.parse(raw);
+        if (Date.now() - p.ts < VID_TTL && p.id) return p.id;
+      }
+    } catch (_) { /* ignore */ }
+    var id = hash(Date.now() + "|" + Math.random() + "|" + navigator.userAgent + "|" + screen.width + "x" + screen.height);
+    try { localStorage.setItem(VID_KEY, JSON.stringify({ id: id, ts: Date.now() })); } catch (_) { /* ignore */ }
+    return id;
+  }
+
+  function send(body, beacon) {
+    var json = JSON.stringify(body);
+    if (beacon && navigator.sendBeacon) {
+      navigator.sendBeacon(endpoint, new Blob([json], { type: "application/json" }));
+      return;
+    }
+    try {
+      fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: json,
+        keepalive: true,
+        credentials: "omit",
+      }).catch(function () { /* silent */ });
+    } catch (_) { /* ignore */ }
+  }
+
+  function payload(path, duration) {
+    return {
+      website: website,
+      path: path,
+      referer: document.referrer || "",
+      screen: screen.width + "x" + screen.height,
+      language: navigator.language || "",
+      visitorId: vid(),
+      duration: duration || 0,
+    };
+  }
+
+  function track() {
+    var path = location.pathname + location.search;
+    if (path === lastPath) return;
+    if (lastPath && enterAt > 0) send(payload(lastPath, Date.now() - enterAt), false);
+    lastPath = path;
+    enterAt = Date.now();
+    send(payload(path, 0), false);
+  }
+
+  function flush() {
+    if (!lastPath || enterAt <= 0) return;
+    send(payload(lastPath, Date.now() - enterAt), true);
+  }
+
+  // 初始 + History API hook
+  track();
+  var origPush = history.pushState;
+  var origReplace = history.replaceState;
+  history.pushState = function () { origPush.apply(this, arguments); track(); };
+  history.replaceState = function () { origReplace.apply(this, arguments); track(); };
+  window.addEventListener("popstate", track);
+  window.addEventListener("pagehide", flush);
+  document.addEventListener("visibilitychange", function () {
+    if (document.visibilityState === "hidden") flush();
+  });
+})();

client/src/app.tsx

@@ -7,6 +7,7 @@ import { SearchOverlay } from "@/components/search";
 import { ProtectedRoute } from "@/components/protected-route";
 import { AdminLayout } from "@/components/admin-layout";
 import { CookieConsent, getCookieConsent } from "@/components/cookie-consent";
+import { trackPageview, bindUnloadTracker } from "@/lib/analytics";
 
 // 代码分割 (Code Splitting)
 const HomePage = lazy(() => import("@/pages/home").then((m) => ({ default: m.HomePage })));
@@ -58,6 +59,12 @@ function matchesPathPrefix(pathname: string, prefix: string) {
 export function App() {
   const [location] = useLocation();
 
+  // 访客埋点：路由变化触发 pageview，页面卸载触发 duration 上报
+  useEffect(() => {
+    bindUnloadTracker();
+    trackPageview(location);
+  }, [location]);
+
   // 路由判断逻辑
   const isAdminRoot = matchesPathPrefix(location, "/admin");
   const isEditorPage = matchesPathPrefix(location, "/admin/editor");

client/src/lib/analytics.ts

@@ -0,0 +1,145 @@
+/**
+ * 客户端访客埋点工具（CF Analytics Engine 增强版）
+ * 灵感来源: HanAnalytics (MIT) — https://github.com/uxiaohan/HanAnalytics
+ *
+ * 工作原理：
+ *   1. 首次加载生成稳定的访客 ID（localStorage 缓存 30 天，不含 PII）
+ *   2. 路由变化 / 首屏渲染 时调用 trackPageview
+ *   3. 页面 unload / pagehide 时上报本次停留时长（duration）
+ *   4. 后端 AE 不可用 → 接口直接 204，前端无感
+ */
+
+const API_BASE = import.meta.env.VITE_API_URL || "";
+const TRACK_ENDPOINT = `${API_BASE}/api/track`;
+const VID_KEY = "monolith_vid";
+const VID_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 天
+
+let pageEnterAt = 0;
+let lastTrackedPath = "";
+
+/** 32-bit FNV-1a 哈希，输出 base36 字符串（不含 PII） */
+function hash(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(36);
+}
+
+/** 获取或生成稳定的访客 ID（仅写本地，不入 cookie） */
+function getVisitorId(): string {
+  try {
+    const raw = localStorage.getItem(VID_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw) as { id: string; ts: number };
+      if (Date.now() - parsed.ts < VID_TTL_MS && parsed.id) return parsed.id;
+    }
+  } catch { /* ignore */ }
+
+  const seed = `${Date.now()}|${Math.random()}|${navigator.userAgent}|${screen.width}x${screen.height}`;
+  const id = hash(seed);
+  try {
+    localStorage.setItem(VID_KEY, JSON.stringify({ id, ts: Date.now() }));
+  } catch { /* localStorage 满或被禁，忽略 */ }
+  return id;
+}
+
+type TrackBody = {
+  website: string;
+  path: string;
+  referer: string;
+  screen: string;
+  language: string;
+  visitorId: string;
+  duration: number;
+};
+
+function send(body: TrackBody, useBeacon: boolean): void {
+  const json = JSON.stringify(body);
+  if (useBeacon && navigator.sendBeacon) {
+    // sendBeacon 在 unload 时最可靠
+    const blob = new Blob([json], { type: "application/json" });
+    navigator.sendBeacon(TRACK_ENDPOINT, blob);
+    return;
+  }
+  // keepalive 让请求在页面切换时也能完成
+  fetch(TRACK_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: json,
+    keepalive: true,
+    credentials: "omit",
+  }).catch(() => { /* 静默失败，埋点永远不影响业务 */ });
+}
+
+/** 上报一次 pageview（路由变化时调用） */
+export function trackPageview(path: string, website = "default"): void {
+  if (!path || path === lastTrackedPath) return;
+  // 后台路径不上报，保护管理员隐私 + 减少噪音
+  if (path.startsWith("/admin")) {
+    lastTrackedPath = path;
+    pageEnterAt = Date.now();
+    return;
+  }
+
+  // 上报上一页停留时长
+  if (lastTrackedPath && pageEnterAt > 0) {
+    send(
+      {
+        website,
+        path: lastTrackedPath,
+        referer: document.referrer || "",
+        screen: `${screen.width}x${screen.height}`,
+        language: navigator.language || "",
+        visitorId: getVisitorId(),
+        duration: Date.now() - pageEnterAt,
+      },
+      false,
+    );
+  }
+
+  // 上报新页面 pageview
+  lastTrackedPath = path;
+  pageEnterAt = Date.now();
+  send(
+    {
+      website,
+      path,
+      referer: document.referrer || "",
+      screen: `${screen.width}x${screen.height}`,
+      language: navigator.language || "",
+      visitorId: getVisitorId(),
+      duration: 0,
+    },
+    false,
+  );
+}
+
+let unloadBound = false;
+/** 绑定 pagehide 事件，确保最后一次停留时长能上报（仅绑定一次） */
+export function bindUnloadTracker(website = "default"): void {
+  if (unloadBound) return;
+  unloadBound = true;
+  const flush = () => {
+    if (!lastTrackedPath || pageEnterAt <= 0) return;
+    if (lastTrackedPath.startsWith("/admin")) return;
+    send(
+      {
+        website,
+        path: lastTrackedPath,
+        referer: document.referrer || "",
+        screen: `${screen.width}x${screen.height}`,
+        language: navigator.language || "",
+        visitorId: getVisitorId(),
+        duration: Date.now() - pageEnterAt,
+      },
+      true,
+    );
+  };
+  // pagehide 比 unload 更可靠（兼容 BFCache）
+  window.addEventListener("pagehide", flush);
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flush();
+  });
+}

client/src/lib/api.ts

@@ -303,6 +303,52 @@ export async function fetchAnalytics(days = 7): Promise<AnalyticsData> {
   return res.json();
 }
 
+/* ── AE 增强分析（CF 专属，仅在 D1 后端可用） ────────── */
+export type AEAnalyticsData = {
+  visitsByDay: { date: string; count: number; uv: number }[];
+  topCountries: { country: string; count: number }[];
+  topReferers: { referer: string; count: number }[];
+  deviceBreakdown: { device: string; count: number }[];
+  browserBreakdown: { browser: string; count: number }[];
+  osBreakdown: { os: string; count: number }[];
+  topPages: { path: string; count: number }[];
+  topScreens: { screen: string; count: number }[];
+  topLanguages: { language: string; count: number }[];
+  totalVisits: number;
+  uniqueVisitors: number;
+  avgDuration: number;
+  hourlyHeatmap: { dow: number; hour: number; count: number }[];
+  durationBuckets: { bucket: string; count: number }[];
+  entryPages: { path: string; count: number }[];
+  exitPages: { path: string; count: number }[];
+  visitorTypes: { type: "new" | "returning"; count: number }[];
+  bounceRate: number;
+  pagesPerVisitor: number;
+  topReferersFull: { referer: string; count: number }[];
+};
+
+export type AEAnalyticsError = {
+  /** 501 = 非 CF 部署；503 = 缺 token；502 = AE SQL 失败 */
+  status: number;
+  message: string;
+};
+
+export async function fetchAEAnalytics(days = 7): Promise<AEAnalyticsData> {
+  const res = await fetch(`${API_BASE}/api/admin/analytics/ae?days=${days}`, {
+    headers: authHeaders(),
+  });
+  if (!res.ok) {
+    let message = `AE 分析数据加载失败 (${res.status})`;
+    try {
+      const body = await res.json() as { error?: string };
+      if (body.error) message = body.error;
+    } catch { /* ignore */ }
+    const err: AEAnalyticsError = { status: res.status, message };
+    throw err;
+  }
+  return res.json();
+}
+
 /* ── 评论 ──────────────────────────────────── */
 export type CommentData = {
   id: number;