1. 引言：系统需求分析

建立个人网站的主要动机是验证一种假设：能否以零成本、低维护开销的方式，将 Obsidian 中的部分笔记公开至互联网。这并非生产环境下的刚性需求，而是一次关于内容管理工作流的工程实验。

初始约束条件：

  • 内容源：Obsidian Vault 中积累的 Markdown 笔记，需要标准化 HTML 输出而不破坏原有本地工作流
  • 技术债规避：拒绝 WordPress 的 MySQL 依赖（增加部署与备份复杂度），拒绝 Notion 的数据锁定与不可控 URL 结构
  • 运维边界：接受静态站点的功能限制（无实时数据库、无用户系统），换取近乎为零的持续维护成本与全球 CDN 可达性

技术路线评估： 经过简单的 ROI 计算，选择 Hugo（Go 语言静态站点生成器）配合 Cloudflare Pages 的边缘部署。核心逻辑在于：利用 Git 作为单一数据源，实现"本地写作 → 版本控制 → 全球发布"的闭环，同时将构建与托管的边际成本压缩至零。

2. 系统演进时间轴（Roadmap）

Phase I：环境搭建与架构验证

  • 本地部署 Hugo Extended 引擎，规避 Node.js 依赖膨胀
  • 主题迁移：从 Blowfish 切换至 PaperMod，降低认知负荷
  • 建立 Obsidian 双 Vault 隔离机制，配置 .gitignore 黑名单排除编译产物

Phase II：内容架构与全球部署

  • 确立 Posts / Projects / About / Archives 四大板块路由
  • 部署 static/version.json OTA 中枢，通过 _headers 实施 Cache-Control 击穿
  • 打通 GitHub → Cloudflare Pages CI/CD 流水线，环境变量锁定 HUGO_VERSION=0.157.0
  • 域名系统：Spaceship 购入 .com 域名，DNS 解析权移交 Cloudflare

Phase III：动态化重构与数据链路

  • 引入 Hugo range 循环替换硬编码 HTML，实现内容目录与首页实时解耦
  • 建立三轨制字体栈（Header 衬线 / 正文无衬线 / UI 等宽）
  • 重构推荐算法，引入 series 维度权重实现专栏文章精准关联

Phase IV：容错修复与标准化

  • 系统性故障处理：模板越权导致首页布局崩溃、字体变量污染引发中文宋体退化、夜间模式硬编码颜色失效
  • 建立防御性编程规范：内联样式优先策略、CSS 特异性管理、缓存穿透机制

Phase V：搜索与导航系统

  • 集成 Fuse.js 实现毫秒级全文检索，JSON 索引由 Hugo 预生成
  • 修复搜索卡片层叠塌陷（position: absolute 导致的物理尺寸丢失）
  • 部署双形态 TOC 系统：桌面端悬浮侧边栏 + 移动端 Modal 抽屉，集成 ScrollSpy 滚动监听

Phase VI：媒体渲染与交互封装

  • 排版引擎：Flexbox 图片防拉伸布局、学术三线表（斑马纹）、KaTeX 公式渲染穿透配置
  • 媒体库：数据驱动架构（data/cyber_bookshelf.yml），实现多态网格渲染
  • 评论系统：Giscus 替代 Waline/MongoDB，基于 GitHub Discussions 实现纯静态托管下的用户互动

3. 部署方案简述

当前系统采用边缘优先策略。本地 Obsidian 完成 Markdown 编辑后，通过 Git 推送触发 Cloudflare Pages 自动化构建。构建环境注入特定版本号锁定编译行为，输出目录直接对接全球 CDN 节点，无需传统服务器中转。域名通过 NS 记录托管于 Cloudflare，实现 DNS 解析与 SSL 证书的自动化管理。整个流程不涉及数据库连接池或后端运行时，消除了传统动态站点的单点故障风险。

构建指令：

hugo --gc --minify

环境变量：

HUGO_VERSION=0.157.0

4. 已实现功能清单

内容管理

  • Markdown 原生写作流，YAML Front Matter 元数据标记
  • 专栏（Series）聚合与自动关联推荐
  • 文章字数统计与阅读时间估算

导航系统

  • 全局搜索（Fuse.js 驱动）
  • 双形态目录（PC 悬浮 / 移动端抽屉）
  • 面包屑层级导航

视觉系统

  • 昼夜模式自适应（CSS 变量驱动）
  • 三轨制字体栈（衬线标题 / 无衬线正文 / 等宽 UI）
  • 学术排版支持（KaTeX 公式、三线表、图片网格）

交互功能

  • Giscus 评论系统（GitHub 后端）
  • 不蒜子（Busuanzi）轻量流量统计
  • 媒体库拟物交互（3D 变换、触摸延迟处理）
  • 阅读进度可视化（顶部进度条）

运维基建

  • OTA 更新中枢（MathPipe 版本检测）
  • 缓存穿透控制（Headers 文件配置）
  • 云端图像 WebP 实时转码（腾讯云 COS 处理参数）

5. 工程债务与复盘

兼容性冲突（Phase 9.0） 追加自定义模板时未评估 Hugo 模板查找顺序，导致 list.html 覆盖主题默认首页。后续建立文件命名规范与作用域隔离机制，关键样式采用内联 style 属性确保特异性。

状态管理缺陷 早期使用硬编码 CSS 颜色值，导致夜间模式同步失效。已全面迁移至 CSS 变量（var(--entry) 等），实现主题状态单一数据源。

缓存策略失误 Hugo 本地缓存与 Cloudflare CDN 曾导致 OTA 更新延迟。通过 --gc 垃圾回收参数与 _headers 显式缓存控制建立穿透机制。

6. 当前系统状态与未来工作

目前网站已进入维护期，架构冻结，不再进行结构性调整。内容生产回归 Markdown 写作本身。

未来可能的工作包括：项目日志的实时数据可视化（Streamlit 联动）、专栏公式排版优化、金属黄主题修复。

系统版本：v1.0 Stable
构建时间：2026-03-12 文档版本：Revision 1