cfw-autumn/docs/cloudflare-analytics-hot-cold-runbook.md

Cloudflare Analytics 热冷分层 Runbook

架构

• 热查询：Cloudflare Analytics Engine，数据集 autumn_events_hot，只用于近 90 天 dashboard/API analytics。
• 历史归档：Cloudflare Pipelines 写入 R2 Data Catalog/Iceberg 表，保留所有事件明细。
• 主业务：积分余额、扣减、订阅和幂等仍以 Postgres/Drizzle 为准。
• 实时热读：Cloudflare Analytics Engine。未支持的历史或复杂查询返回明确错误，不回退 Tinybird。

Cloudflare 资源

Production:

cd server
bunx wrangler pipelines streams create autumn_events_archive

将输出中的 stream ID 写入 server/wrangler.jsonc 的 top-level pipelines[].stream。 当前 production stream ID: b197b38da53e4ecea3d095c5f54ea820。

Staging:

cd server
bunx wrangler pipelines streams create autumn_events_archive_staging

将输出中的 stream ID 写入 server/wrangler.jsonc 的 env.staging.pipelines[].stream。 当前 staging stream ID: 6af7319fb01742cfaf042318a7ea91ce。

Analytics Engine dataset 由 wrangler.jsonc 的 analytics_engine_datasets binding 负责绑定。

上线开关顺序

1. CLOUDFLARE_ANALYTICS_WRITE_ENABLED=false
2. CLOUDFLARE_ANALYTICS_ARCHIVE_ENABLED=false
3. CLOUDFLARE_ANALYTICS_HOT_READ_ENABLED=false
4. 部署含 bindings 的 Worker。
5. 在 staging 打开 CLOUDFLARE_ANALYTICS_WRITE_ENABLED=true。
6. 在 staging 打开 CLOUDFLARE_ANALYTICS_ARCHIVE_ENABLED=true。
7. 对账 staging 的 Analytics Engine row count、R2 archive row count 和 Postgres 事件插入量。
8. production 先打开写入和归档，保持热读关闭。
9. production 对账 7 天后，打开 CLOUDFLARE_ANALYTICS_HOT_READ_ENABLED=true。

回滚

读路径回滚：

cd server
bunx wrangler secret put CLOUDFLARE_ANALYTICS_HOT_READ_ENABLED

输入：

false

写路径回滚：

cd server
bunx wrangler secret put CLOUDFLARE_ANALYTICS_WRITE_ENABLED
bunx wrangler secret put CLOUDFLARE_ANALYTICS_ARCHIVE_ENABLED

两个值都输入：

false

对账 SQL

Analytics Engine 近 24 小时事件数：

SELECT count() AS events
FROM autumn_events_hot
WHERE index1 = 'org_...'

R2 SQL 历史归档事件数按天验证：

SELECT date_trunc('day', timestamp) AS day, count(*) AS events
FROM autumn_events_archive
GROUP BY day
ORDER BY day DESC
LIMIT 14

后续覆盖门槛

• Cloudflare 双写连续 30 天无系统性失败。
• /query/event_names/list 和 /query/raw 在 production 的 Cloudflare 热读结果与 Postgres 事件插入量对账差异低于 1%。
• R2 归档至少覆盖 90 天以上历史，并能通过 R2 SQL 查回指定 org/env/customer/event_name。
• revenue analytics 有独立替代方案，或明确继续保留 Tinybird 只服务非事件分析路径。