在知识花园里,一篇文章可以有几种读法。你可以沿着目录顺序读完,也可以停在某一段旁边讨论;遇到交互实验,还可以修改参数,观察结果怎样变化。如果想知道作者还有哪些相关作品,可以展开 AI 分身,带着问题继续探索。
这些入口连接着同一批内容。知识花园的设计,就是让写作、阅读、实验和对话能够围绕内容自然衔接:作者持续整理自己的知识,读者可以选择适合自己的理解方式。
这篇文章介绍站点怎样组织内容、为什么采用现在的阅读界面,以及 Next.js、Rust、PostgreSQL 和 AI 如何共同支撑这些体验。
一、站点的中心,是可以持续生长的内容
知识花园是一座个人知识网站。长文章承载需要展开的解释和作品,瞬间记录较短的观察与想法,关于页帮助读者认识作者。它们适合不同的表达节奏:有些内容值得反复修订,有些只需要及时留下。
文章按知识库和目录组织。例如,这篇文章位于“应用 → Web 开发”,读者可以顺着目录理解一个主题,也可以通过搜索和文内引用跳到另一篇文章。目录负责给出顺序,链接负责建立联系;一篇较早写下的内容,仍然可以成为今天理解新问题的入口。
在文字之外,文章还能够容纳公式、流程图、手绘图、代码和交互实验。像站内的“找到你的 π 日”、数据处理模拟与股债配比实验,都是把解释和操作放在一起的尝试。读者读到一个结论后,可以进一步看看条件改变时会发生什么。
因此,站点组织的基本单位是一份可持续维护的内容。文章、讨论、实验和 AI 都围绕它展开。这个选择也决定了后面的技术设计:内容需要结构,需要版本,还需要让不同入口能够引用同一个来源。
二、界面围绕阅读展开,需要时再打开工具
进入文章页,最主要的空间留给正文。顶栏负责内容、瞬间和关于等站点入口;目录帮助读者确定当前的位置,评论和 AI 则处理阅读过程中产生的问题。它们按需展开,避免每打开一种辅助功能,就让正文重新挤成更窄的一列。
段落评论把讨论带到具体语境中。读者对一句解释有疑问,可以在那一段旁边展开讨论,评论里保留对应的引用。这样,后来的读者更容易知道大家讨论的是哪一处,而不必在全文和留言之间来回寻找。
看板娘:从旧博客延续下来的一个想法
之前做 GitHub Blog 时,我就想把看板娘这项功能继续做起来。回看更早的 2019 年 Flask 博客模板,里面已经接入 Live2D,并留下了空闲提示、触碰回应等预设脚本。后来的 GitHub Blog 使用 Hexo 与 Fluid;从旧博客到今天的知识花园,看板娘也成了一条值得保留的个人网站线索。
如今,看板娘与阅读有了更直接的联系:Live2D 负责角色的动作和表现,AI 分身负责围绕公开作品回答问题,两者通过推荐问题和聊天浮窗连接起来。角色给对话提供一个可见的入口,资料检索与回答则由后面的 AI 系统完成。
平时,她收在页面角落的小圆入口里,点击才展开角色和问题气泡。读者可以用鼠标或触摸把她拖到合适的位置;桌面上,角色的视线会跟随鼠标,轻触还能触发小动作。头顶的问题随阅读场景变化,帮助读者找到提问的起点;暂时不需要时可以收起,动画也随之暂停。
点击头顶的推荐问题,就会打开 AI 分身浮窗并填入问题;读者可以修改,确认发送后才开始回答。在文章页,当前作品可以作为对话背景。收起浮窗后,页面仍是刚才阅读的位置,已有对话也可以继续。目录、评论和聊天采用相近的开关与拖动方式,电脑和手机则根据可用空间调整呈现。
视觉上,站点沿用深蓝与天蓝、白色正文面板、封面图和留白。封面建立文章的第一印象,正文提供稳定的阅读节奏;复杂功能隐藏在需要它的地方。这些设计也提出了一个技术要求:先让内容出现,再按需补上交互能力。
三、前端负责体验,后端负责内容与规则
从整体结构看,知识花园有一套 Web 前端、一套 Rust 业务后端,以及保存数据的 PostgreSQL。生产环境由 Nginx 接收 HTTPS 请求,把页面交给 Next.js,把业务 API 请求交给 Rust;图片等媒体文件使用本地存储或 S3。
公开阅读页与创作台,有不同的加载重点
公开文章使用服务端渲染(SSR)。当读者直接打开链接,Next.js 先取得公开内容,把正文组织进 HTML,再返回浏览器。React 随后接管评论、浮窗和实验等交互。这样,文章正文可以先被阅读,搜索引擎也能取得页面内容。
作者创作台则以客户端交互为主。编辑、拖动目录、预览和管理设置都在浏览器中进行,登录后再读取作者的数据。两种体验共享组件与主题,但编辑器等较重的能力只在需要时加载,普通读者不必下载整套创作工具。
前端使用 TypeScript 管理类型,React 组合界面,MUI 提供基础组件;TanStack Query 管理服务端数据的读取与更新。它们承担通用工作,本站代码主要负责内容组织和具体交互。
Rust 是统一的业务入口
文章发布、账号登录、评论、AI 检索与备份都由 Rust 后端处理。axum 负责 HTTP 路由和请求处理,SQLx 连接 PostgreSQL。前端调用接口取得结果,服务端决定当前身份能读什么、能修改什么,以及操作是否符合内容规则。
这种结构可以称为“模块化单体”:业务按模块划分,运行时仍是一套后端。对个人站点而言,它让部署和排障保持集中,也方便文章、版本和评论在同一个数据库事务里协作。模块共享资源,因此模型调用、文件处理等较重任务仍需要限制并发和执行时间。
技术 | 在这个站点中的作用 |
|---|---|
Next.js / React / TypeScript | 组织公开页面与创作台,完成首屏渲染和后续交互 |
Tiptap | 把文字、媒体、图表与实验组织成可编辑的正文 |
Rust / axum / SQLx | 处理业务请求,统一权限与内容规则 |
PostgreSQL | 持久保存内容、版本、账号、讨论和 AI 相关状态 |
Docker Compose / GitHub Actions | 把程序构建、检查和部署到运行环境 |
四、结构化文章,让评论、实验和 AI 找到同一个位置
表面上,作者编辑的是一篇文章;系统保存的却是一棵结构化内容树。Tiptap 把标题、段落、图片、公式等保存为不同类型的 JSON 节点,本站再扩展图表、PDF 和实验等内容块。
这就像把文章拆成有身份的积木。同一段文字在编辑器里可以修改,在阅读器里可以排版,在评论里可以被引用,在 AI 回答中也可以作为来源定位。每个块都有独立标识,因此前面插入一段文字时,后面的评论不必仅靠“第几段”重新猜测位置。
实验块保存实验类型与初始参数,运行逻辑来自前端对应的组件。普通图表则保存可编辑源码和生成后的图片快照:作者可以继续改图,读者直接看图。只有需要实际操作的实验,才加载相应的交互代码。内容的表达能力因此可以扩展,而每篇文章都携带的基础开销仍有机会保持较小。
作者持续写作,读者读取已发布版本
一篇文章常常不是一次写完的。作者需要自动保存和修改历史,读者则需要完整、稳定的版本。因此,保存草稿与发布被分为两个动作:编辑器持续保存工作中的内容,作者发布时才生成一份新的阅读快照。
例如,作者正在重写某个解释,读者仍然可以阅读上次发布的完整文章。新稿确认后,再替换当前公开版本。AI 也只从允许公开的版本中取材,不会因为作者刚写下一个未经整理的想法,就把它当成公开观点。
同样的原则贯穿整个系统:网页、站内检索和 AI 资料工具共用服务端的公开判断。权限与发布状态发生变化时,后续读取需要重新确认。对读者来说,这意味着不同入口应该讲述同一份当前可见的内容。
五、AI 分身怎样从站点内容中回答问题?
当读者问“这篇文章为什么这样解释”时,AI 可以读取对应原文;当问题变成“作者最近关注哪些主题”时,它需要把多篇作品联系起来。知识花园为这两类问题准备了原文检索和 Wiki 两种资料入口。
这里的 Wiki 是从公开作品整理出的知识材料:先梳理每个来源,再组织主题、作品和观点之间的联系,并保留它们来自哪些文章。可以把它理解为一份附有出处的主题导读,帮助 AI 先找到方向,再回到具体原文确认细节。
假设读者正在阅读一篇数据处理文章,并问它与另一篇作品有什么关联。AI 可以先确定两篇文章各自讨论的内容,再借助 Wiki 的主题整理找到交集,最后用原文说明联系。这里举的是工作方式:实际回答仍取决于能否检索到足够依据,不应把系统的归纳直接说成作者本人已经表达过的观点。
Wiki 也需要跟着内容更新。系统记录页面依赖的来源,重新生成时尽量复用未变化的结果;来源发生变化或不再公开,相关旧页面就不能继续被当作有效资料。没有可用 Wiki 时,AI 仍可以检索并阅读公开原文。
长对话则通过另一种摘要维持连续性:近期问答保留原文,更早的讨论逐步压缩为单会话记忆,记住读者的目标、限制和已确认事项。Wiki 组织站点知识,会话记忆记录这一次交流,两者用途不同;关于作者的事实仍要以公开来源为依据。
模型服务目前支持 DeepSeek 与 OpenAI。后台内容生成和前台聊天分别配置模型策略,模型凭证保留在服务端;前端接收流式答案和来源。于是读者看到的是渐渐展开的回答,而服务端负责检索、访问控制、额度和取消等工作。
AI 分身为阅读增加了一条对话路径,也带来了需要认真对待的限制:检索可能漏掉资料,摘要可能损失细节,模型也可能理解错误。可点击的出处让读者能够继续核对,原文始终是理解作者的落脚点。
六、让这套网站能够长期维护
站点的可持续维护,既体现在作者每天怎样写作,也体现在程序怎样升级、数据怎样恢复。创作台集中管理正文、附件、外观与 AI 设置;通过 MCP,作者还可以授权外部助手使用这些后台能力,例如建立这篇文章的草稿。MCP 调用复用现有业务接口,保存和发布仍有各自的权限与步骤。
前后端接口也尽量保持同一个来源:Rust 定义请求与响应,生成 OpenAPI 描述,再据此生成前端类型和 MCP 工具参数。接口变化能够在检查阶段暴露出来,减少“前端以为有这个字段,后端却返回另一个结构”的问题。
部署时,GitHub Actions 负责工程检查和容器镜像构建,服务器使用 Docker Compose 运行 Web、API 与数据库。程序镜像与持久数据分开管理,更新应用时保留文章、上传文件和私有配置;上线还要经过备份、健康检查和页面验收。
性能上的取舍也沿着阅读需求展开。图表和编辑器按需加载,文章图片提供适合展示的版本,静态资源可以长期缓存。公开页面则优先反映当前发布状态,后续若要增加更多缓存,需要同时保证撤回与权限变化能够及时生效。
当前部署仍以单机为基础,它让运行结构较直接,也意味着宿主机故障会影响整站。数据库与附件备份、可验证的恢复方式,比堆叠更多服务更贴近现阶段的需要。AI 检索与 Wiki 也还有质量和耗时上的改进空间,应该由实际阅读问题和运行数据来驱动优化。
回到读者看到的那篇文章
现在再看知识花园的一篇文章,界面与架构之间的联系就更清楚了:目录来自内容组织,段落评论依赖块的身份,实验依赖可扩展的正文结构,AI 依赖可追溯的公开资料,而稳定的阅读体验依赖版本、加载策略与持久存储。
这些设计共同服务于一个朴素的目标:让作者能够持续写下、整理和修订自己的知识,也让读者能够阅读、追问、验证,并找到下一篇值得继续读的内容。
想沿着技术细节继续探索,可以阅读站内的 《Life of a Request:一次请求的一生》,了解页面如何抵达浏览器;也可以从 《Rust 初体验》 进一步理解后端所使用的语言。本文描述的是 2026 年 11 月的站点实现,后续会随架构演进更新。
全文评论
0正在加载评论…