零服务器渲染 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 |
| 文章 / RSS | 3600s |
| 列表 / 归档 / 留言簿 | 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
两个关键点:
- 必须先 sanitize 再高亮。反过来的话,Shiki 生成的
class/style会被白名单清掉,代码块直接退化成纯文本。 - 留言簿用更严格的 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,也欢迎直接拿去做自己的主页。