零服务器渲染 GitHub:Astro SSR + Cloudflare Workers 的缓存与主题隔离实践

0 阅读2分钟

零服务器渲染 GitHub:Astro SSR + Cloudflare Workers 的缓存与主题隔离实践

想做一个「个人主页」很容易变成又一次烂尾:选生成器、配 CI、买域名、写构建脚本。但内容其实已经在 GitHub 上了——profile README、公开仓库、公开 Gist。ClassyGit 做的是把这些公开数据直接渲染成主页 + 博客,不复制内容、不构建站点。

运行时只有两个依赖:GitHub 提供内容和身份,Cloudflare 提供计算、缓存和计数。没有内容数据库。

整体架构

GitHub(README / repos / Gists / comments)
        │  REST API(服务端 token)
        ▼
Astro SSR on Cloudflare Workers
        ├─ Cache API:HTML / badge / OG 图
        ├─ KV:webring / discover 索引
        └─ Durable Object:访客计数
        ▼
classygit.pages.dev/<username>

请求进 middleware 后先解析主题和语言,再计算缓存键;命中直接返回,未命中才渲染。

坑一:Cache API 不会自己过期

caches.default.match() 不会因为响应里的 max-age 过期就返回 undefined——它会一直给你旧条目,直到被淘汰。只依赖 cache-control 的话,「缓存 5 分钟」会变成「缓存到天荒地老」。线上真实踩过:改了配置一小时不生效。

所以写入时自己打时间戳,读取时自己判断:

const CACHED_AT = 'x-classy-cached-at';

const cacheGet = async (key: Request, ttl: number) => {
  const hit = await caches.default.match(key);
  if (!hit) return undefined;

  const cachedAt = Number(hit.headers.get(CACHED_AT) ?? 0);
  if (!cachedAt || Date.now() - cachedAt > ttl * 1000) return undefined;

  return hit;
};

TTL 按路由分级:

路由TTL
用户主页300s
文章 / RSS3600s
列表 / 归档 / 留言簿300s
徽章 / OG 图86400s
首页3600s

坑二:缓存键少一个维度就串页

主题、语言、分页、标签筛选都必须进键:

const key = new Request(
  `${url.origin}${url.pathname}?theme=${theme}&lang=${locale}&v=${CACHE_VERSION}` +
    `${page ? `&page=${page}` : ''}${tag ? `&tag=${tag}` : ''}`,
  { method: 'GET' }
);

否则 NES 的页面会被发给 mac 访客,第 2 页会拿到第 1 页的内容。

还有个容易忽略的点:Set-Cookie 不能进缓存。写缓存前先摘掉,再把原响应里的 Set-Cookie 补回去,不然「某个人选的主题」会发给所有人。

首页和 /webring 没有站主配置,lang=auto 要按 Accept-Language 分片;用户页的 auto 由站主配置决定,不能按访客浏览器语言分片。

主题隔离:每套 CSS 独立打包

四套主题共用同一份数据,主题只决定外壳。主题契约只有 5 个组件:Layout、ProfileCard、RepoCard、GistCard、Markdown。

每套 Layout 自己 import CSS:

---
import themeCss from './theme.css?url';
---
<link rel="stylesheet" href={themeCss} />

Vite 会把每个 ?url 产出成独立资源,SSR 只输出当前主题的 <link>。看 mac 的访客不会下载 NES 那 279KB。

Markdown 管线:顺序不能改

README 和 Gist 都是任意外部输入,管线是:

remark-parse → remark-gfm → remark-rehype(allowDangerousHtml)
→ rehype-raw → rehype-sanitize → rehype-shiki → rehype-stringify

两个关键点:

  1. 必须先 sanitize 再高亮。反过来的话,Shiki 生成的 class / style 会被白名单清掉,代码块直接退化成纯文本。
  2. 留言簿用更严格的 schema:删掉 img / picture / source,避免评论里的追踪像素;评论也不跑 Shiki,避免一页几十条评论把 CPU 打满。

Shiki 的体积也踩过坑:默认入口会把约 200 种语法打进 Worker,实测 27MB。换成 createHighlighterCore + 显式 import 21 种常用语言,再用纯 JS 的 regex engine 避免 oniguruma wasm,体积降一个数量级。

const highlighter = createHighlighterCore({
  themes: [githubLight, githubDark],
  langs: [bash, css, docker, go, html, java, javascript, json /* ... */],
  engine: createJavaScriptRegexEngine(),
});

配置:逐段降级,永远不打挂站点

classy.config.json 是用户输入,不能信任。做法是每段一个全 optional 的 zod schema,解析失败只回退那一段:

  • 坏链接只丢一条,不让整份配置作废
  • href 只放行 http(s)
  • 未知字段直接丢弃
  • 主题名写错回退 mac

owner 还有个作用:fork 会继承作者的配置,读到 owner 与当前用户不一致时整份配置按模板忽略,避免所有人的页面都变成作者的主页。

计数:为什么用 Durable Object

访问计数是 read-modify-write。KV 的 get + put 在并发下会丢数,所以每个用户一个 Durable Object:

const current = (await this.ctx.storage.get<number>('count')) ?? 0;
await this.ctx.storage.put('count', current + 1);

DO 的 input gate 保证同一对象的请求串行执行。bot 和预取请求只读不计数,所以数字本来就是近似的。

成本与取舍

  • 公共实例用 Workers Paid($5/月),主要给 Shiki 留 CPU 余量;轻度使用可以试免费计划
  • 没有内容数据库:KV / DO 全丢了,内容还在 GitHub,重新访问一次就能重建
  • 用户页默认 noindex:无限生成的薄内容不该进搜索索引,想收录自己开 seo.index
  • 只读公开数据,不做私有内容

项目是 MIT,欢迎 issue / PR,也欢迎直接拿去做自己的主页。