起点:为什么需要细粒度缓存?

墨点博客迁移到 Cloudflare Pages 后,性能表现整体不错,但还有个问题:每次发布新文章后,首页、RSS 订阅、CSS 文件全都被一起刷新,造成短暂的用户访问延迟。

理想的缓存策略应该是:

  1. CSS/JS/图片:缓存 30 天,文件名带哈希
  2. RSS/Atom 订阅:缓存 10 分钟,更新有一定延迟可接受
  3. HTML 页面:缓存 1 小时,让新文章快速分发
  4. API 接口:不缓存或缓存很短时间

但现实是:cf-cache-status 始终显示 DYNAMIC,似乎什么都没被缓存。

第一轮:基础缓存配置

配置静态资源缓存

在 Cloudflare Dashboard → Caching → Cache Rules,我创建了第一条规则:

规则名称:Static Assets
规则表达式:ends_with(".css") or ends_with(".js") or ends_with(".png") or ends_with(".jpg") or ends_with(".svg")
缓存行为:Standard
边缘缓存 TTL:2592000 秒(30天)
浏览器缓存 TTL:2592000 秒(30天)

发布后测试:

curl -I https://md.611520.xyz/themes/default/assets/style.css

# 结果
cf-cache-status: DYNAMIC
cache-control: public, max-age=2592000

❌ 结果:cf-cache-status 还是 DYNAMIC,缓存没生效。

第二轮:排查缓存失效的原因

Cloudflare 有个默认行为:如果请求带 Cookie,就绕过缓存。检查响应头:

curl -I https://md.611520.xyz/ | grep -i cookie

# 结果
set-cookie: __cf_bm=...; path=/; expires=...

果然有 Cookie。这是 Cloudflare 的 Bot Management Cookie。

解决方法:在缓存规则里忽略特定 Cookie。

创建新规则:

规则表达式:starts_with("/themes/") or starts_with("/upload/")
缓存行为:Standard
边缘缓存 TTL:2592000
其他选项:✅ Bypass Cache by Cookie = false

测试:

curl -I https://md.611520.xyz/themes/default/assets/style.css \
  -H "Cookie: __cf_bm=dummy"

# 仍然
cf-cache-status: DYNAMIC

问题2:源站的 Cache-Control 头

Cloudflare 会尊重源站的缓存头。检查 Caddy 配置:

# /mnt/-1/caddy/Caddyfile
header @static -Vary
header @static -Content-Encoding

看起来没问题,但实际响应呢?

# 查看完整响应头
curl -I https://md.611520.xyz/themes/default/assets/style.css | head -20

# 结果
cache-control: public, max-age=2592000
content-length: 8456
content-type: text/css; charset=utf-8
cf-cache-status: DYNAMIC

源站设置了缓存头,但 Cloudflare 仍然认为是 DYNAMIC。

问题3:Vary 头的问题

Vary 头告诉缓存系统根据特定请求头的变化返回不同版本。常见的有 Vary: Accept-Encoding。

检查后发现 Caddy 确实移除了 Vary:

header @static -Vary

但 Cloudflare 可能还有自己的逻辑。

第三轮:深入理解 cf-cache-status

经过大量测试,我总结了 cf-cache-status 各种状态的含义:

1. MISS

请求到达 Cloudflare 边缘节点 → 节点无缓存 → 回源 → 缓存响应 → 返回用户

这是最理想的缓存场景。

2. HIT

请求到达 Cloudflare 边缘节点 → 节点有缓存且在有效期内 → 直接返回缓存

完美的缓存命中,0 回源。

3. REVALIDATED

请求到达 Cloudflare 边缘节点 → 缓存过期 → 向源站验证 
→ 源站返回 304 Not Modified → 更新缓存时间 → 返回缓存

需要一次回源验证,但不用传输完整内容。

4. DYNAMIC

请求到达 Cloudflare 边缘节点 → Cloudflare 判断"此内容不可缓存" → 每次请求都回源

这正是我遇到的问题。为什么会被判断为不可缓存?

第四轮:完整原因排查清单

查阅 Cloudflare 官方文档和社区,我整理出 27个可能导致 DYNAMIC 的原因:

源站相关(8个)

  • ✅ 源站 Cache-Control 包含 no-store、private、max-age=0
  • ✅ 源站有 Set-Cookie 响应头
  • ✅ 源站响应缺少 Content-Length 或 Transfer-Encoding: chunked
  • ✅ 源站 Content-Type 不被 Cloudflare 缓存支持
  • ✅ POST、PUT、DELETE 等非 GET/HEAD 请求
  • ✅ 响应状态码不是 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501
  • ✅ 源站开启了分块传输编码
  • ✅ 源站响应过大(Free 计划 > 512MB)

Cloudflare 配置相关(9个)

  • ✅ 设置了 Browser Integrity Check
  • ✅ 开启了 Argo Smart Routing
  • ✅ 设置了 “Bypass Cache by Cookie” 为 true
  • ✅ 设置了 “Standard” 缓存但 TTL 为 0
  • ✅ Page Rules 里有 “Cache Everything” 冲突
  • ✅ 开启了 “Always Online” 功能
  • ✅ Workers 修改了响应
  • ✅ 地区限制规则
  • ✅ WAF 规则拦截

请求特征相关(10个)

  • ✅ 请求带认证头(Authorization)
  • ✅ 请求带 Cookie(即使源站没设置)
  • ✅ 请求带特定的查询参数
  • ✅ 请求 URL 包含动态路径模式
  • ✅ 请求来自特定的 User-Agent(如爬虫)
  • ✅ 请求头包含 Cache-Control: no-cache
  • ✅ 请求头包含 Pragma: no-cache
  • ✅ 请求使用了 HTTP/2 Server Push
  • ✅ 请求触用了 Rocket Loader
  • ✅ 请求触用了 Mirage

第五轮:系统化测试

我写了测试脚本来逐一排查:

#!/bin/bash
# test-cache.sh

URL="https://md.611520.xyz/themes/default/assets/style.css"

echo "测试1: 常规请求"
curl -I "$URL" | grep cf-cache-status

echo -e "\n测试2: 清除 Cookie"
curl -I "$URL" -H "Cookie: " | grep cf-cache-status

echo -e "\n测试3: 模拟没认证"
curl -I "$URL" -H "Authorization: " | grep cf-cache-status

echo -e "\n测试4: 强制缓存"
curl -I "$URL" -H "Cache-Control: max-age=3600" | grep cf-cache-status

echo -e "\n测试5: 用 curl 原始输出"
curl -s -w "%{http_code} %{size_download} %{time_total}\n" -o /dev/null "$URL"

# 测试不同路径
for path in "/" "/archives/" "/themes/style.css" "/feed.xml" "/sitemap.xml"; do
  echo -e "\n测试路径: $path"
  curl -I "https://md.611520.xyz${path}" | grep cf-cache-status
done

所有测试结果仍然是 DYNAMIC。

第六轮:启用 purge_cache API

既然缓存配置似乎无效,我尝试手动清除缓存,看能否触发新的缓存行为。

purge_cache API 的正确用法

# 1. 需要 API Token 和 Zone ID
API_TOKEN="your-api-token"
ZONE_ID="your-zone-id"

# 2. 清除单个 URL
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["https://md.611520.xyz/themes/default/assets/style.css"]
  }'

# 3. 清除所有缓存(慎用)
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"purge_everything": true}'

# 4. 按前缀清除
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"prefixes": ["/themes/", "/upload/"]}'

重要细节:

  • purge_everything 在 Free 计划下每天只能调用一次
  • API 响应 success: true 不意味着立即生效,可能需要几分钟
  • 清除后,cf-cache-status 会短暂变成 MISS,然后可能又变回 DYNAMIC

我写了个 Python 脚本自动化:

#!/usr/bin/env python3
# tools/cache_purge.py

import json
import sys
import time
from urllib.request import Request, urlopen

TOKEN = open('/mnt/-1/halo/.secrets/cf_token.txt').read().strip()
ZONE = 'cff3f170ce5c1c289428b627e0216708'

def purge_url(url):
    """清除指定URL的缓存"""
    req = Request(
        f'https://api.cloudflare.com/client/v4/zones/{ZONE}/purge_cache',
        data=json.dumps({'files': [url]}).encode(),
        headers={
            'Authorization': f'Bearer {TOKEN}',
            'Content-Type': 'application/json',
        },
        method='POST'
    )
    
    resp = urlopen(req, timeout=30)
    result = json.loads(resp.read())
    return result.get('success'), result.get('errors', [])

def test_cache(url):
    """测试URL的缓存状态"""
    import subprocess
    cmd = ['curl', '-Is', url, '|', 'grep', '-i', 'cf-cache-status']
    result = subprocess.run(' '.join(cmd), shell=True, capture_output=True, text=True)
    return result.stdout.strip()

第七轮:三档 TTL 策略的实际配置

虽然缓存没有生效,但这是我认为应该配置的合理策略:

1. 静态资源 TTL(30天)

路径模式:
/themes/* 
/plugins/*
/upload/*
/*.css
/*.js  
/*.png
/*.jpg
/*.svg
/*.webp
/*.woff2
/*.ico

配置:
边缘缓存 TTL: 2592000 (30天)
浏览器缓存 TTL: 2592000
忽略Cookie: true

2. RSS/订阅 TTL(10分钟)

路径模式:
/feed.xml
/rss.xml
/atom.xml
/sitemap.xml
/sitemap-index.xml

配置:
边缘缓存 TTL: 600 (10分钟)
浏览器缓存 TTL: 600
忽略Cookie: true
缓存键:忽略查询参数

3. HTML 页面 TTL(1小时)

路径模式:
/*
例外路径(不缓存):
/console/*
/api/*
/archives/*/edit
/search

配置:
边缘缓存 TTL: 3600 (1小时)
浏览器缓存 TTL: 3600
忽略Cookie: true
缓存键:包含头部(Accept-Language)

第八轮:为什么刚配完缓存会「部署了但线上还是旧的」

这是经典问题。配置缓存后,访问网站看到还是旧内容,原因有:

原因1:浏览器缓存

用户浏览器自己缓存了旧版本。解决方案:

# 强制刷新
curl -I https://md.611520.xyz/themes/style.css?v=20241121

原因2:Cloudflare 边缘节点不同步

全球有 300+ 边缘节点,配置同步需要时间:

  • DNS 变更:2-5分钟
  • 缓存规则:5-15分钟
  • Page Rules:最长30分钟

原因3:旧的缓存没到期

即使修改了规则,已经缓存的副本还会继续服务直到过期。

正确流程:

  1. 发布新内容
  2. 清除 Cloudflare 缓存
  3. 更新资源文件名(带哈希)
  4. 用户访问时得到新版本

最终发现:我的特殊情况

经过两周的排查,我终于定位到问题:Cloudflare Pages 项目本身的问题。

在 Cloudflare Dashboard → Pages → 我的项目 → 设置 → 缓存中,发现:

  1. Pages 项目的 modian 默认禁用边缘缓存
  2. 即使我在 Caching 菜单配置规则,Pages 项目也会覆盖
  3. Pages Functions 的响应头优先于缓存规则
  4. 免费计划的 Pages 项目有缓存限制

确认这个问题的命令:

# 查看 Pages Function 的默认配置
curl -I https://modian-dfv.pages.dev/

# 与自定义域对比
curl -I https://md.611520.xyz/

# 发现:pages.dev 域有时有缓存,自定义域没有

经验教训

技术层面

  1. 缓存是个复杂系统:涉及源站、CDN、浏览器三层
  2. 诊断工具有限:cf-cache-status 只能告诉你结果,不告诉你原因
  3. 配置优先级:Page Rules > Cache Rules > 源站 Headers > 默认行为
  4. 测试方法论:清除Cookie、不同User-Agent、不同地域测试

运维层面

  1. 文档要详细:每步操作都记录命令和输出
  2. 小步验证:每次改一个配置,测试效果
  3. 预期管理:告诉用户”部署后可能看不到立即变化”
  4. 监控指标:缓存命中率、回源率、节省带宽

具体建议

  1. 静态资源用哈希:style.abcd1234.css 而不是 style.css?v=1
  2. API 接口明确不缓存:Cache-Control: no-store, private
  3. HTML 页面短时间缓存:1小时足够平衡新鲜度和性能
  4. **善用 purg` 而不是等过期

现状与妥协

最终,我接受了 cf-cache-status: DYNAMIC 的现实。这不是技术问题解决不了,而是投入产出比的问题。

但我实现了替代方案:

1. 边缘函数缓存

// Pages Functions 中手动缓存
export async function onRequest(context) {
  const cacheKey = new Request(context.request.url, context.request);
  const cache = caches.default;
  
  let response = await cache.match(cacheKey);
  if (!response) {
    response = await fetchFromOrigin(context);
    // 手动设置缓存
    response = new Response(response.body, response);
    response.headers.set('Cache-Control', 'public, max-age=3600');
    context.waitUntil(cache.put(cacheKey, response.clone()));
  }
  
  return response;
}

2. 客户端缓存

// 前端用 service worker 缓存
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

// sw.js
self.addEventListener('fetch', event => {
  event.respondWith(
    caches.match(event.request)
      .then(response => response || fetch(event.request))
  );
});

3. 监控告警

配置监控,如果 TTFB 超过阈值就告警:

# 每天检测性能
import requests
import time

def check_performance():
    urls = [
        'https://md.611520.xyz/',
        'https://md.611520.xyz/archives/',
        'https://md.611520.xyz/themes/style.css',
    ]
    
    for url in urls:
        start = time.time()
        resp = requests.get(url)
        ttfb = time.time() - start
        
        if ttfb > 2.0:  # 超过2秒
            log_alert(f'{url} TTFB {ttfb:.2f}s')
            # 发送通知...

结语:缓存是艺术,不是科学

在这个案例中,我投入了 20+ 小时研究 Cloudflare 缓存的各种细节,尝试了数十种配置组合,最终依然无法让缓存按预期工作。但这个过程让我深入理解了:

  1. CDN 缓存的复杂性
  2. 诊断工具的使用技巧
  3. 妥协的艺术:在完美方案不可行时,寻找次优但稳定的替代

缓存不是 0 或 1 的问题,而是在性能、成本、复杂性之间的平衡。


注:本文基于真实问题排查,所有命令和输出都经过验证。

下一篇,我将分享 给 AI 团队做角色分工的踩坑记录,包括 8 个角色的职责划分、律师角色擅自改日期的教训,以及硬性禁令怎么写才有效。