Foundit架构解析

基于项目源代码的结架构拆解——Foundit为什么比传统博客/CMS 更聪明、更安全、更"被看见"。

如果你曾经搭过个人网站、技术博客，或者公司内容站，大概率踩过这些坑：文章发出去搜索引擎半年没收录；后台登录形同虚设，改个 URL 就能绕过；服务器月月烧钱；换台手机排版就崩了。

Foundit 这个项目，正是针对这些"老毛病"给出的一个近乎教科书式的答案。它不是一个臃肿的系统，而是一套用现代工具链拼起来的、克制而精密的内容站。下面我们用拆解一台精密仪器的眼光，看看它的内部构造。

一、它到底是什么？

用一句话概括：

Foundit 是一个基于 Nuxt（SSR）、Supabase（数据库+存储）和 Srces Auth（统一登录）的科技内容知识站。

它把内容分成四种形态——文章、产品、想法、专题，对外提供公开阅读（首页、列表、详情、搜索、RSS、Sitemap），对内提供一个由管理员权限保护的内容后台。

它的技术栈可以用"五个方面军"来理解：

这张图里藏着 Foundit 的第一个聪明之处：浏览器永远不直接碰数据库钥匙。所有写入都要经过 Nuxt 服务端这一道"门房"，而"门房"只认经过密码学签名的令牌。

如果把镜头再拉近一点，按"分层"的视角看，各个组件的上下游关系会更清晰——公开读取和管理员写入走的是两条泾渭分明的通道，最终都汇聚到 Supabase，但沿途经过的"安检"完全不同：

注意左右两侧的对称：左边"公开访问者"只能通过 RLS 过滤后的只读通道拿到已发布内容；右边"管理员"必须先过 Srces Auth 的 JWT 验签、再由服务端持 Service Role Key 才能写入，并且每一次写入都会留下审计记录。安全，不是某一处的设防，而是整条链路的默认姿态。

二、目录结构：像图书馆一样井井有条

一个项目好不好维护，先看它的"房间怎么分"。Foundit 的目录非常符合直觉：

最值得称道的一点：公共接口（/api/content）与后台接口（/api/admin/*）严格分离。前者的数据访问层叫 content-repository，后者叫 admin-repository。这种"按职责分层"的写法，让代码在半年后被人接手时，依然能一眼看懂谁在干什么。

三、六大优点与特性

1. 生来就被搜索引擎"看得懂"——SSR + SEO + GEO

很多现代网站为了酷炫，正文靠 JavaScript 在浏览器里现拉现渲染。结果就是：关掉 JS，页面一片空白；搜索引擎爬虫看不懂；AI 问答工具也抓不到。

Foundit 反其道而行。它用 SSR（服务端渲染），用户或爬虫拿到的就是一份完整的 HTML 正文。项目里还专门做了三件事：

• 结构化数据（JSON-LD）：每篇文章/产品页都输出机器可读的 Article / SoftwareApplication 标签，相当于给内容贴了"身份证"，方便 Google、Bing 以及各类 AI 准确理解。
• Sitemap + RSS + robots.txt：全部由服务端动态生成，内容一发布就自动更新"目录"。
• GEO（生成式引擎优化）：专门为"被 AI 引用"做了设计——首屏直出核心结论、事实与观点分开、标注作者与来源时间、提供参考资料链接。

那么一次"打开文章"的请求，在幕后到底经历了什么？下面这张时序图，把从浏览器发起请求，到边缘缓存、服务端拉数据、Markdown 渲染、注入 JSON-LD，最后吐出完整 HTML 的全过程摊开了看：

关键在于：真正决定"正文长什么样"的那一步（渲染 + 注入结构化数据）发生在服务端，而不是浏览器。所以无论是搜索引擎爬虫、AI 抓取器，还是关掉了 JS 的读者，拿到的都是同一份完整、可读、带"身份证"的 HTML。

优越性看点：验收标准里白纸黑字写着"关闭 JavaScript 后仍可阅读完整正文"“Lighthouse SEO 评分不低于 95”。这不是口号，而是可被测试验证的工程目标。

2. 多层安全防线——"隐藏菜单"骗不了人

很多 CMS 的"权限"只是前端把按钮藏起来。Foundit 的态度是：前端隐藏只是体验，真正的安全必须发生在服务端。

它的防线是这样的：

1. 统一身份（OIDC + PKCE）：登录走标准的授权码 + PKCE 流程，不存客户端密钥。
2. 密码学令牌（RS256 JWT）：服务端用 jose 库 + 远程 JWKS 公钥，逐条校验签名算法、签发者（issuer）、接收方（audience）、过期时间，并确认角色含 admin。
3. 服务端兜底：每个 /api/admin/* 都调用同一个 requireAdmin，前端无论怎么改都绕不过去。
4. 数据库层面的 RLS：即使有人拿到数据库，公开角色也只能 SELECT 已发布的内容，草稿和归档天然不可见。
5. 密钥隔离：高权限的 Service Role Key 只存在于服务器环境变量，绝不进前端产物。

具体到"登录"这件事，Foundit 用了一套巧妙的双令牌机制：管理员先从 Srces Auth 拿到一枚有效期仅 10 分钟的 RS256 令牌（用于向服务端证明身份），服务端验签通过后，再签发一枚 8 小时的 HttpOnly 会话 Cookie（免去每次都携带外部令牌）。整个握手过程如下：

这里有两个容易被忽略的细节：其一，本地会话 Cookie 的 path 被限定为 /api/admin，意味着它只在后台请求时才会被发送，不会泄漏到普通页面；其二，无论前端如何伪造，服务端 requireAdmin 都会重新验签并检查 admin 角色——前端隐藏菜单，永远绕不过这道服务端的门。

一句话总结它的安全哲学：“永远不要相信浏览器送来的任何东西。”

3. 一套设计语言，前后台"长得很像"

Foundit 附带了一份极其详尽的 UI 设计规范（40 多节）。它的核心只有几个字：克制、安静、留白、内容优先。

• 色彩只有黑、白、浅灰三色体系；
• 视觉层级靠字体和间距建立，而不是靠色块和阴影；
• 前后台共用同一套字体、按钮、表单风格，后台不再是"花花绿绿的 SaaS 仪表盘"；
• 连动效都限制时长（150–220ms），禁止"为了高级感而高级感"。

这种设计的好处是长期可读、跨设备一致、维护成本低。它像一本排版考究的书，而不是一面喧闹的广告墙。

4. 智能缓存：既快又不会"显示旧文章"

Nuxt 的 routeRules 把缓存策略写得很细：

SWR（Stale-While-Revalidate）是个聪明机制：先立刻把缓存的老页面给用户（快），同时后台悄悄刷新（新）。而涉及认证和敏感数据的页面，则坚决不缓存，避免把别人的后台响应留在边缘节点上。

5. 边缘部署：把服务器"搬到"用户身边

传统做法要租一台云服务器 24 小时待命。Foundit 部署在 Cloudflare Workers 上——代码运行在全球边缘节点，离用户更近，按请求计费，闲时几乎零成本。配合 wrangler.toml 一行配置，构建产物直接发布，无需管理服务器。

这对个人创作者尤其友好：运维成本趋近于零， scalability 却近乎无限。

6. 数据模型：为"生长"而设计

数据库 schema 不是拍脑袋写的。它用枚举约束内容类型与状态（draft/published/archived），用 jsonb 存产品截图与链接，用 GIN 索引支持全文搜索，还预留了 revisions（修订记录）、audit_logs（审计日志）、auth_users（用户映射）等"未来扩展位"。

把这些表之间的关系画出来，就能看到这套"地基"的全貌——内容表居于核心，分类/标签/专题围绕它展开，而修订、审计、用户映射则像预埋的钢筋，静静等待未来的功能生长上去：

这意味着：今天它是个博客，明天它想加评论、加多作者、加付费墙，地基已经留好了。

四、它"优越"在哪？——和传统方案对比

用一个比喻：传统方案像"自己盖房子，水电自己接，锁自己装"；Foundit 像"采用现代装配式建筑——结构、安防、节能标准都是出厂即合规的"。

五、写在最后：它也有"待打磨"的地方

科普要客观。探索中也发现两点值得后续留意：

• Markdown 渲染开了 html: true：正文允许原生 HTML，目前只有管理员能写，风险可控；但未来若开放投稿，需加一层消毒（sanitize）防存储型 XSS。
• 限流是进程内存计数：在 Cloudflare 多实例边缘部署下，单 IP 限流可能不具全局性，可改用 KV / Durable Objects。

但这些都属于"优等生的小瑕疵"——它的主干设计（分层、鉴权、SSR、部署）已经相当成熟。

结语

Foundit 给我们的最大启发是：好的工程不是堆功能，而是把"正确的事"变成默认。 内容该被看见，所以默认 SSR；权限该被守住，所以默认服务端校验；成本该被压低，所以默认边缘部署。

它像一台调校得当的相机——没有花哨的灯，但每一次按下快门，都能稳定地、清晰地把"内容"拍下来，递到读者和机器面前。

“页面不主动争夺注意力，而是让内容自然地被看见。” —— 这正是 Foundit 设计系统里最动人的一句话，也是它整个架构的底层逻辑。