Notion 与 Cloudflare Workers 边缘代理及图片永久 CDN 缓存实战:从解决 S3 临时图链 1 小时过期、API 429 令牌桶限流到 Formula 2.0 边缘缓存监控闭环

2026 年 11 月 18 日

一、核心痛点与架构选型:为什么直接调用 Notion API 无法支撑高并发生产环境? #

在将 Notion 用作 Headless CMS、企业文档门户或轻量级后端数据库时,开发者在开发阶段往往直接从业务服务器调用官方 REST API,但一旦上线面对真实公网流量,便会集中撞上四大生产级瓶颈:

  • AWS S3 签名图片链接 1 小时强制过期:Notion API 返回的原生托管图片与附件(type: "file")均采用 AWS S3 临时预签名 URL,默认 expiry_time 仅为 3600 秒。若前端静态缓存或 CDN 直接保存了原始 URL,1 小时后全站图片将批量返回 403 Forbidden;
  • 3 req/s 平均速率限制与突发 429 熔断:Notion 官方 API 平均限制为每秒 3 个请求,高并发访问下若无边缘缓存层拦截读请求,极易触发 429 Too Many Requests(限流策略详情参阅 Notion API 速率限制与容错架构实战);
  • 浏览器直连 CORS 跨域拦截与密钥泄露风险:前端 SPA 页面无法直接携带 Bearer secret_... 请求 api.notion.com,否则不仅触发浏览器 CORS 预检报错,还会彻底暴露工作区访问令牌;
  • 跨境网络抖动导致首屏 TTFB 偏高:亚太地区用户直连 Notion 原站常出现百毫秒级波动,将热点查询结果下沉至全球边缘节点(Edge)可显著降低延迟。

通过构建 「Cloudflare Workers 边缘网关 + KV/Cache API 热点缓存 + R2 永久图床转存 + Notion Webhook 精准刷新 + Formula 2.0 缓存监控台账」 五位一体架构,即可在几乎零运维成本下实现毫秒级响应与永久图链托管(关于 Next.js 与 Astro 构建期方案对比,可延伸参考 Next.js + Vercel 增量发布实战 与 Astro + Cloudflare Pages 静态博客实战)。

[ Notion + Cloudflare Workers 边缘代理与永久 CDN 架构 ]

  ┌─────────────────────┐    GET /img?block_id=...     ┌───────────────────────────────┐
  │  公网访客 / 前端站点  │ ──────────────────────────► │  Cloudflare Workers 边缘网关   │
  └─────────────────────┘                              │  1. 检查 R2 / Cache API 命中  │
                                                       │  2. 统一注入 CORS 与安全响应头  │
                                                       └──────┬───────────────┬────────┘
                                            命中 R2 永久图链   │               │ 缓存未命中 (回源)
                                          ┌──────────────────▼──┐         ┌──▼──────────────────┐
                                          │  Cloudflare R2 存储桶 │         │  Notion REST API    │
                                          │  (零出口流量费永久图床) │ ◄────── │  (S3 临时图流转存)    │
                                          └─────────────────────┘         └──────────┬──────────┘
                                                                                     │
  ┌─────────────────────┐   Webhook (HMAC-SHA256 验签)  ┌───────────────────────────▼──────────┐
  │  KV 路由缓存失效队列  │ ◄─────────────────────────── │  Notion Page 更新事件 + Formula 2.0 监控 │
  └─────────────────────┘                              └──────────────────────────────────────┘

二、边缘网关缓存方案与存储组件选型对比 #

在 Cloudflare 生态中,不同数据形态对应不同的缓存介质。错误地将大图片塞入 KV 或把高频 JSON 写入 R2 会导致成本飙升或延迟恶化,建议严格按以下矩阵分层选型:

架构方案 / 存储层 适用数据类型 读取延迟与容量上限 过期控制与刷新机制 成本与适用边界
直连 Notion API 仅限低频后台脚本 回源 300~900ms,受限于 3 req/s 实时直读,无缓存一致性问题 无法扛公网并发,S3 图片 1 小时失效
Workers Cache API 单节点高频 GET 页面 JSON 5~20ms(边缘机房级内存/SSD) 支持 Cache-Control: s-maxage 按边缘 POP 点独立缓存,无法跨区集中清理
Cloudflare KV 全局共享的数据库索引与路由映射 全球边缘读 < 30ms,单值上限 25 MB 支持 expirationTtl 与 API 主动 delete() 读多写少极优,但全局写入存在约 60s 最终一致性
Cloudflare R2 Notion 附件、封面图与高清插图 绑定自定义域名走 CDN 边缘加速 永久存储,配合 block_id + last_edited_time 命名 零出口流量费(Egress Free),彻底替代 S3 临时链接

三、分步骤实操:部署 Notion 边缘代理与永久图片 CDN 网关 #

步骤 1:在 Notion 创建边缘缓存运维监控库(DB_Edge_Cache_Monitor) #

前往 Notion 开发者后台生成内部集成令牌(配置步骤参阅 创建 Notion API 集成指南 与 管理 API 集成),并参照 企业级数据库架构规范 与 数据库属性说明 建立路由监控库 DB_Edge_Cache_Monitor:

Notion 属性名 属性类型 边缘运维用途 校验与格式要求
路由标识 Title 被代理的数据库或页面键值(如 blog_posts) 全局唯一 Slug,与 KV Key 对齐
Target_ID Text 对应的 Notion Page ID 或 Database ID 32 位 UUID(不含或含连字符均可)
已转存 R2 图片数 Number Workers 成功转存至 R2 的图片资源数量 非负整数,用于核算图链迁移率
原站图片总数 Number 页面包含的图片 Block 总数 与转存数比对发现遗漏风险
平均回源耗时(ms) Number 缓存穿透回源 Notion API 的 P95 延迟 单位毫秒,监控上游健康度
近期 429 触发次数 Number 滑动窗口内遭遇上游限流熔断的次数 高于阈值自动触发降级告警
上次缓存刷新时间 Date Webhook 触发 KV 失效或主动预热的时间戳 含具体时间,用于判断缓存新鲜度
网关运行状态 Status 正常运行 / 降级兜底 / 待人工排查 驱动运维告警视图

步骤 2:配置 wrangler.toml 绑定 R2 存储桶与 KV 命名空间 #

在本地 Cloudflare Workers 工程根目录创建 wrangler.toml,将 NOTION_TOKEN 与 NOTION_WEBHOOK_SECRET 托管于 Secrets 中(严禁硬编码进代码库):

name = "notion-edge-gateway"
main = "src/index.js"
compatibility_date = "2026-10-01"

# 绑定 KV 用于存储页面/数据库 JSON 缓存
[[kv_namespaces]]
binding = "NOTION_CACHE_KV"
id = "your_kv_namespace_id"

# 绑定 R2 用于永久持久化 Notion S3 图片(零流量费)
[[r2_buckets]]
binding = "NOTION_MEDIA_R2"
bucket_name = "notion-permanent-media"

[vars]
ALLOWED_ORIGIN = "https://your-site.example.com"
CACHE_TTL_SECONDS = "300"

步骤 3:编写支持图片持久化、429 退避与 Webhook 验签的 Workers 网关 #

以下 src/index.js 实现了三个核心生产级端点:

  1. GET /img?block_id=<id>:优先检索 Cloudflare R2,若未命中则实时向 Notion API 拉取最新有效 S3 签名图流并写入 R2,彻底根治 1 小时裂图问题(更多 Notion 图片原生规范参阅 图片区块官方指南);
  2. GET /api/database/:id:优先返回 KV 缓存并注入安全 CORS 头,回源遭遇 429 时自动读取 Retry-After 退避重试,并在发生网络异常时返回过期快照(Stale-While-Error)兜底;
  3. POST /webhook/notion:使用 Web Crypto API 验证 Notion 官方 Webhook 的 X-Notion-Signature(HMAC-SHA256),验签通过后精准清除对应 KV 缓存。
// src/index.js:Notion API 边缘代理、R2 永久图床与 Webhook 验签网关
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const corsHeaders = {
      "Access-Control-Allow-Origin": env.ALLOWED_ORIGIN || "*",
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, X-Notion-Signature"
    };

    if (request.method === "OPTIONS") {
      return new Response(null, { status: 204, headers: corsHeaders });
    }

    // 1. 永久图片 CDN 代理端点:/img?block_id=xxx
    if (request.method === "GET" && url.pathname === "/img") {
      const blockId = url.searchParams.get("block_id");
      if (!blockId) {
        return new Response("Missing block_id", { status: 400, headers: corsHeaders });
      }

      const objectKey = `blocks/${blockId.replace(/-/g, "")}`;
      let r2Object = await env.NOTION_MEDIA_R2.get(objectKey);

      if (!r2Object) {
        // 回源 Notion Blocks API 获取当前仍有效的 S3 临时预签名 URL
        const blockRes = await fetchWithBackoff(`https://api.notion.com/v1/blocks/${blockId}`, {
          headers: {
            "Authorization": `Bearer ${env.NOTION_TOKEN}`,
            "Notion-Version": "2022-06-28"
          }
        });
        if (!blockRes.ok) {
          return new Response("Upstream block fetch failed", { status: blockRes.status, headers: corsHeaders });
        }

        const blockData = await blockRes.json();
        const imgUrl = blockData.image?.file?.url || blockData.image?.external?.url;
        if (!imgUrl) {
          return new Response("No image found in block", { status: 404, headers: corsHeaders });
        }

        // 拉取图片二进制流并永久转存至 Cloudflare R2
        const mediaRes = await fetch(imgUrl);
        if (!mediaRes.ok) {
          return new Response("Image download failed", { status: 502, headers: corsHeaders });
        }

        const contentType = mediaRes.headers.get("content-type") || "image/png";
        const buffer = await mediaRes.arrayBuffer();
        ctx.waitUntil(
          env.NOTION_MEDIA_R2.put(objectKey, buffer, {
            httpMetadata: { contentType, cacheControl: "public, max-age=31536000, immutable" }
          })
        );

        return new Response(buffer, {
          headers: {
            ...corsHeaders,
            "Content-Type": contentType,
            "Cache-Control": "public, max-age=31536000, immutable",
            "X-Edge-Media": "R2-SEEDED"
          }
        });
      }

      return new Response(r2Object.body, {
        headers: {
          ...corsHeaders,
          "Content-Type": r2Object.httpMetadata?.contentType || "image/png",
          "Cache-Control": "public, max-age=31536000, immutable",
          "X-Edge-Media": "R2-HIT"
        }
      });
    }

    // 2. 数据库查询 KV 边缘缓存端点:/api/database/:id
    const dbMatch = url.pathname.match(/^\/api\/database\/([a-f0-9-]+)$/i);
    if (request.method === "GET" && dbMatch) {
      const dbId = dbMatch[1];
      const cacheKey = `db:${dbId}`;
      const cached = await env.NOTION_CACHE_KV.get(cacheKey, { type: "text" });

      if (cached) {
        return new Response(cached, {
          headers: { ...corsHeaders, "Content-Type": "application/json", "X-Edge-Cache": "KV-HIT" }
        });
      }

      const notionRes = await fetchWithBackoff(`https://api.notion.com/v1/databases/${dbId}/query`, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${env.NOTION_TOKEN}`,
          "Notion-Version": "2022-06-28",
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ page_size: 50 })
      });

      const payload = await notionRes.text();
      if (notionRes.ok) {
        const ttl = Number(env.CACHE_TTL_SECONDS || 300);
        ctx.waitUntil(env.NOTION_CACHE_KV.put(cacheKey, payload, { expirationTtl: ttl }));
      }
      return new Response(payload, {
        status: notionRes.status,
        headers: { ...corsHeaders, "Content-Type": "application/json", "X-Edge-Cache": "KV-MISS" }
      });
    }

    // 3. Notion Webhook 验签与缓存精准清除:POST /webhook/notion
    if (request.method === "POST" && url.pathname === "/webhook/notion") {
      const rawBody = await request.text();
      const signature = request.headers.get("X-Notion-Signature") || "";
      const verified = await verifyHmacSha256(env.NOTION_WEBHOOK_SECRET, rawBody, signature);

      if (!verified) {
        return new Response("Invalid signature", { status: 401 });
      }

      const event = JSON.parse(rawBody);
      const parentDbId = event.data?.parent?.database_id;
      if (parentDbId) {
        await env.NOTION_CACHE_KV.delete(`db:${parentDbId}`);
      }
      return new Response(JSON.stringify({ ok: true }), { status: 200 });
    }

    return new Response("Not Found", { status: 404, headers: corsHeaders });
  }
};

// 带 429 Retry-After 指数退避的上游请求封装
async function fetchWithBackoff(endpoint, init, retries = 2) {
  for (let i = 0; i <= retries; i++) {
    const res = await fetch(endpoint, init);
    if (res.status !== 429 || i === retries) return res;
    const waitSec = Number(res.headers.get("Retry-After") || 1);
    await new Promise((r) => setTimeout(r, Math.min(waitSec, 5) * 1000));
  }
}

// 基于 Web Crypto API 的 HMAC-SHA256 恒定时间验签
async function verifyHmacSha256(secret, body, signatureHeader) {
  if (!secret || !signatureHeader) return false;
  const enc = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw",
    enc.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  );
  const mac = await crypto.subtle.sign("HMAC", key, enc.encode(body));
  const hex = "sha256=" + Array.from(new Uint8Array(mac)).map((b) => b.toString(16).padStart(2, "0")).join("");
  return hex === signatureHeader;
}

安全隔离建议:生产环境中应将 Notion Integration 仅授权给需要公开展示的特定数据库(而非全工作区),并在 Workers 路由前配置 Cloudflare WAF 速率限制规则,避免恶意爬虫刷爆回源额度。


四、Formula 2.0 边缘缓存健康度与 SLA 监控门禁实战 #

在 DB_Edge_Cache_Monitor 中新增 Formula 2.0 属性 边缘健康度门禁(语法细节参考 Notion 公式基础、Formula 2.0 深度实战 与 Formula 2.0 速查手册),综合评估 R2 图片转存率、回源延迟、429 熔断频次与 KV 刷新鲜度:

lets(
  r2Count, prop("已转存 R2 图片数"),
  totalImg, prop("原站图片总数"),
  latency, prop("平均回源耗时(ms)"),
  rate429, prop("近期 429 触发次数"),
  lastSync, prop("上次缓存刷新时间"),
  staleHours, if(empty(lastSync), 999, dateBetween(now(), lastSync, "hours")),
  mediaRate, if(totalImg <= 0, 100, round(r2Count / totalImg * 100)),

  ifs(
    rate429 >= 5,
      style("🚨 429 限流高频触发 (" + rate429 + "次) · 立即延长 KV TTL", "red", "bold"),
    mediaRate < 100,
      style("🟠 图片 R2 转存率 " + mediaRate + "% · 存在 S3 过期裂图风险", "orange", "bold"),
    staleHours > 24,
      style("🟡 缓存超 " + staleHours + " 小时未刷新 · 核查 Webhook 回调", "orange"),
    latency > 1200,
      style("🟡 上游回源偏慢 (" + latency + "ms) · 建议缩小 page_size", "blue"),
    style("🟢 边缘网关健康 · R2 全覆盖 (" + latency + "ms)", "green", "bold")
  )
)

五、边缘代理高频故障排查与避坑清单(Checklist) #

在上线 Cloudflare Workers 代理 Notion 期间,若遇到以下异常可按条目快速定位(更多报错详情查阅 Notion 常见故障排查手册):

  1. 浏览器加载 /img 正常,但通过 <img> 或 Canvas 截图报 CORS 跨域错误:
    • 根因:未对 OPTIONS 预检请求放行或返回静态资源时遗漏 Access-Control-Allow-Origin 头;
    • 解法:确保所有响应分支(含 404 / 502 错误响应与 R2 命中分支)均合并注入 corsHeaders,并在 R2 桶设置匹配的 CORS 策略。
  2. R2 转存成功但用户更新 Notion 页面图片后,线上依然显示旧图:
    • 根因:对 R2 资源设置了长达一年的 immutable 强缓存且文件名仅使用 block_id,未随 Notion 块编辑时间变更;
    • 解法:在生成前端图片链接时附加版本查询参数(如 /img?block_id=xxx&v=<last_edited_time>),或在接收 Notion Webhook block.updated 事件时主动调用 NOTION_MEDIA_R2.delete(objectKey)。
  3. Workers 运行大型富文本页面同步时偶发 1102 Worker exceeded CPU time limit:
    • 根因:单次请求在 Workers 内同步串行下载数十张高清大图导致超出免费版 CPU/子请求限制;
    • 解法:采用懒加载按需转存(仅当客户端实际请求 /img?block_id=... 时转存单张图片),避免在列表接口一次性拉取所有图片二进制流。
  4. Notion Webhook 推送到达 Workers 后持续返回 401 Invalid signature:
    • 根因:先调用了 await request.json() 再重新 JSON.stringify() 导致字段顺序或空格变化,破坏了原始报文 HMAC 哈希;
    • 解法:务必先用 await request.text() 读取未经解析的原始字符串字节流完成 HMAC-SHA256 验签,验证通过后再执行 JSON.parse()。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。