InsightFlare (Backend Only)

InsightFlare 是运行在 Cloudflare 上的开源访问分析后端服务。

功能

• 动态 GET /script.js（按 request.cf.isEUCountry 切换 EU 模式）
• 客户端事件采集：POST /collect
• Durable Object 并行写入：内存缓冲、Analytics Engine、WebSocket、Alarm
• Alarm 批量落盘 D1
• 每小时归档：热归档（D1 小时聚合）+ 冷归档（可选 R2 Parquet）
• 查询与管理接口（私有/公开 API）
• Parquet 文件查询支持 HTTP Range Requests

架构

• 单应用：根目录 Next.js Route Handlers + OpenNext + Cloudflare Worker
• 单配置：根目录 wrangler.toml
• 入口接口：
  • /script.js
  • /collect
  • /api/private/*
  • /api/public/*
  • /api/admin/*
  • /api/auth/*
  • /api/archive/*
  • /healthz
• workers/cf-worker.js 负责：
  • 导出 Durable Object 类
  • 透传 /admin/ws
  • 执行定时归档任务

快速开始

1. 安装依赖

npm ci

2. 创建 D1（首次）

npm run cf:d1:create

3. 修改根目录 wrangler.toml

• 填入 [[d1_databases]] 的 database_id
• 在 [vars] 下添加 ANALYTICS_ACCOUNT_ID（Cloudflare Account ID）
• 按需开启 [[r2_buckets]]
• INSIGHTFLARE_EDGE_URL 可配置为当前后端服务地址

4. 设置 Secret（至少一个）

npm run cf:secret:daily-salt

可选：

npm run cf:secret:bootstrap-admin-password
npm run cf:secret:session-secret
npm run cf:secret:analytics-sql-token

5. 本地构建验证

npm run cf:build

6. 部署

npm run cf:deploy

Cloudflare Git 集成

如果在 Cloudflare 控制台使用 Git 自动部署，请设置：

• Build command: npm run ci:build
• Deploy command: npm run ci:deploy

不要跳过 prebuild 直接部署，否则 D1 迁移不会自动执行。

常用命令

• 本地开发：npm run dev
• 预部署 dry-run：npm run cf:deploy:dry-run
• CI dry-run：npm run ci:deploy:dry-run
• 查看线上日志：npm run cf:tail

关键配置

• SESSION_WINDOW_MINUTES：会话窗口（默认 30）
• SCRIPT_CACHE_TTL_SECONDS：/script.js 缓存秒数
• PARQUET_WASM_URL：Parquet wasm 下载地址
• ANALYTICS_ACCOUNT_ID：Analytics Engine SQL 查询使用的 Cloudflare 账号 ID
• ANALYTICS_SQL_API_TOKEN（Secret）：用于 0-90 天 Analytics Engine 查询
• DISABLE_ANALYTICS_ENGINE：设为 true/1 可关闭 Analytics Engine 读写，查询回退到 D1/归档

注意事项

• 生产建议使用 Linux/WSL/CI 构建（OpenNext 官方建议）