渐知笔记搭建记录：从想法到自动发布

为什么最后还是想自己搭一个站

我一直有记东西的需求，但过去很多记录都比较零散：有些在聊天里，有些在文档里，有些只是临时查完就过去了。真正缺的不是一个“博客模板”，而是一个能长期留下思考路径的地方。

所以“渐知笔记”一开始就不是为了做成传统博客。我更想保存的是一个过程：从不知道，到查资料、试方法、改判断，再到某个阶段形成相对稳定的认识。

这也是最后留下来的那句话：

记录所学、整理所思，渐有所知。

站点只是外壳，真正要长期维护的是这些记录之间的关系。

先把内容结构想清楚，再开始做页面

最开始容易犯的错误，是先想首页长什么样、卡片怎么排、要不要封面图。但真正做下去后发现，比视觉更重要的是先回答三个问题：一篇笔记属于什么、在讨论什么、现在成熟到什么程度。

最后把内容拆成了三个互相独立的维度：

Area：实践、求知、日常，回答“这是什么类型的记录”；
Topic：桥梁、Web、AI、历史、档案等，回答“它在讨论什么”；
Cognitive State：所学、所思、所知、持续更新，回答“如果这篇内容存在认知演进，现在大概处在什么状态”。

这里后来还踩了一个语义上的坑。最初把 Stage 理解成“认知阶段”，很容易让人产生一种错觉：实践、求知、日常都应该经历“所学 → 所思 → 所知”。但实际并不是这样。

求知类内容确实经常会有这个过程，实践类有时也有，而很多日常记录根本没有必要强行套一个阶段。最后把它改成了可选的认知状态：有就标，没有就留空。结构应该服务内容，而不是逼内容服从结构。

技术上尽量选择可以长期维护的东西

站点最后采用的是一套相对克制的结构：

Markdown 笔记
    ↓
私有 GitHub 仓库
    ↓
Astro 静态生成 + Pagefind 搜索
    ↓
GitHub Actions 云端构建
    ↓
构建产物 Artifact
    ↓
腾讯云 VPS Self-hosted Runner
    ↓
Caddy 提供源站静态文件
    ↓
EdgeOne 对外提供 HTTPS / CDN

这样做有几个好处。

第一，正文始终是 Markdown，不依赖数据库。以后哪怕整套前端都换掉，文章本身还在。

第二，公开站是纯静态的，没有访客注册、评论、投稿这些东西，既减少维护成本，也更符合当前个人站的边界。

第三，构建和部署是分开的。真正吃 CPU 和内存的 Astro、Pagefind 构建继续放在 GitHub Hosted Runner 上，只有最后已经生成好的静态文件交给 VPS 部署。对于一台 2C2G 的小服务器，这比让服务器自己每次重新安装依赖、重新构建要轻得多。

写作入口必须和公开站分开

另一个很早就确定的原则，是公开阅读和站长写作不要混在一起。

公开站是 bijiy.com，写作工作台单独放在 write.bijiy.com。后台使用 Decap CMS 连接私有 GitHub 仓库，通过 GitHub 身份完成写入。公开站上的 /admin/ 则直接在源站返回 404，写作子域名同时设置 noindex / nofollow / noarchive。

后台做了几件对实际写作很有用的事情：

frontmatter 表单化，不需要每次手写字段；
Markdown 左侧编辑、右侧实时预览；
正文可以直接粘贴图片，上传到自己的图床后自动插入 Markdown；
新笔记不再要求“封面图”，避免为了发一条记录还要先找图；
更新时间不手工填写，而是直接从 Git 历史读取。

这套方式的目标不是把后台做得多复杂，而是尽量降低“我现在想记一点东西”的阻力。

第一个比较大的坑：自动部署不该一直 SSH 进服务器

最初的部署方案很常见：GitHub Actions 构建完成后，通过 SSH 和 SCP 登录 VPS，把文件上传到 release 目录，再切换 current 软链接。

功能上完全没问题，但腾讯云很快开始不断发送“高风险登录”提醒。原因也很直接：GitHub Hosted Runner 每次可能来自不同的公网 IP，在云厂商看来，就是一批不断变化的外部地址持续 SSH 登录服务器。

继续加白名单并不是一个漂亮的解决办法，于是部署方向反过来了。

现在是 VPS 上运行一个专门的 GitHub Self-hosted Runner，由服务器主动通过 HTTPS 出站连接 GitHub。流程变成：

GitHub Hosted Runner 负责构建
        ↓
上传短期 Artifact
        ↓
VPS Runner 主动领取 deploy 任务
        ↓
下载 Artifact
        ↓
本机原子切换 release

Runner 使用独立的 bijiydeploy 普通用户运行，并注册成 systemd 服务，开机自动启动，不需要 root 常驻，也不新增对外端口。

第一次新链路跑通以后，旧的 VPS SSH 部署 Secrets 和对应的 authorized_keys 公钥都删掉了。到这里，GitHub 已经不再需要主动 SSH 进入服务器。

这个改动看起来只是换了一种部署方式，实际上把安全边界也顺手理清楚了：服务器管理 SSH 只留给人，自动部署走 GitHub Runner 自己的任务通道。

一些真正上线后才会发现的小坑

搜索结果明明只有一条，下面却还有一堆文章

Pagefind 本身其实已经正确返回了 1 条结果，问题出在 CSS。

备用结果列表虽然被加上了 hidden，但后面的 .list { display: grid; } 又把它显示了出来。于是视觉上看起来像“搜索没有隔离干净”。

这个问题提醒我，hidden 这种状态不能只依赖浏览器默认样式，布局规则一旦覆盖 display 就可能失效。最后把搜索正式结果和 fallback 的显示逻辑彻底分开，确保任意时刻只出现一套结果。

卡片右下角画了箭头，但箭头居然不能点

最初首页卡片只有标题是真正的链接，右下角虽然有一个明显的进入箭头，却只是装饰。视觉在暗示“这里可以点”，交互却不是这样。

后来改成整张卡片都可以进入正文，同时让 Area、认知状态和 Topic 保持自己的独立链接。实现时还要避免嵌套 <a>，所以采用主链接扩展点击区域、元数据链接提高层级的方式处理。

现在逻辑比较清楚：

点卡片空白区域：进入文章；
点 Area：进入实践 / 求知 / 日常；
点认知状态：进入对应状态索引；
点 Topic：进入该主题的全部文章。

“全部笔记”的筛选选中了，文字却消失了

这是一个很典型的样式覆盖问题。

通用 .filter.active 本来是深色背景 + 白字，但 Archive 页面后来又给筛选按钮加了 background: transparent，优先级把选中态背景覆盖掉了，于是最终变成“白字 + 浅色背景”，看起来就像按钮文字不见了。

最后不是简单改一个颜色，而是把规则定死：选中态必须明确拥有深色背景、白色文字和对应边框，页面级样式不能再把它覆盖掉。

“归档”这个词本身也不太对

最初 /archive/ 只是传统意义上的年份、月份归档。但渐知笔记真正需要的不是“2026 年 9 月写了什么”，而是“我现在有哪些实践、哪些求知、哪些主题，以及它们分别处在什么状态”。

所以后来页面直接改成了“全部笔记”，并放进顶部主导航。它现在更像整个站的总知识索引：可以组合筛选 Area、认知状态和 Topic，也可以按最近更新或首次发布排序。

URL 仍然保留 /archive/，但它承担的角色已经完全不同。

手机端不是把桌面端缩小就结束了

文章阅读页最明显的例子是目录。

桌面端右侧常驻目录很好用，但手机没有这个空间。最开始如果只在文章顶部放一个“目录”按钮，读到中间以后想跳章节还要重新滚回去。

后来改成了两层入口：文章头部保留一次目录入口，进入正文后右下角出现一个只有三条横线的小圆形按钮；到“继续探索”和“相关主题”附近再自动隐藏。点击后不是居中弹窗，而是打开一个底部抽屉，并同步当前正在阅读的章节。

这类细节单看都不大，但它们决定了这个站以后自己会不会真的愿意用。

这次搭建过程中形成的几个原则

回头看，真正有价值的并不是某个框架或者某段 CSS，而是逐渐确认了几条规则：

先保证内容可以长期保存，再考虑展示。 Markdown 和 Git 比复杂数据库更适合这个站。
分类维度要彼此独立。 Area、Topic、认知状态分别回答不同问题，不强行制造流程。
写作阻力越低越好。 不强制封面，不手填更新时间，不为了形式补字段。
公开阅读和作者写作分开。 公共站保持纯静态，写作权限留在独立工作台和 GitHub 身份里。
构建和部署分开。 云端负责重活，小 VPS 只接收产物并切换版本。
真实使用比设计稿更容易发现问题。 很多 bug 都是在真正搜索、点击、手机阅读以后才暴露出来。
每确认一个规则就写进仓库文档。 否则改到后面，很容易把前面已经想清楚的东西重新推翻。

现在的发布方式

现在新增一篇笔记，可以自己在 write.bijiy.com 写，也可以直接通过对话把一个想法讲出来，再由助手帮我归纳、整理成 Markdown，提交到私有 GitHub 仓库。

提交之后，Quality 检查、静态构建、搜索索引、Artifact、VPS 部署和源站检查都会自动完成。正常情况下，我不需要再手工登录服务器。

有意思的是，这篇《渐知笔记搭建记录》本身也是用同样的流程完成的：先在对话里回顾这次搭建过程，再整理成笔记，和代码修改一起提交，然后由刚刚搭好的自动发布链路把它送到站上。