第一部分：操作指南 (你每天要做的事)

这是你最关心的部分：如何写，才能让文章出现在网站的正确位置？

1. 核心规矩：文件夹决定去向

我们在 Python 脚本里写死了“路由规则”。你在 Obsidian 里把文件放在哪个文件夹，决定了它发布后出现在网站的哪个栏目。

请务必在你的 Obsidian 根目录下建立以下 4 个文件夹（必须完全一致，区分大小写）：

Obsidian 文件夹名 网站对应栏目 适用内容
10_Tech 技术项目 Python代码、服务器维护日志、学习笔记。
20_Humanities 人文社科 法律思考、社会学分析、读书笔记。
30_Poetry 附庸风雅 诗词、散文、摄影感悟。
40_Journal 不悟不修 私人日记、年终总结、碎片想法。

2. 发布开关：Front-matter (元数据)

这是最关键的一步。为了保护你的隐私，所有文章默认都是“私密”的，不会被发布。

只有当你显式地告诉系统“我要发布”，它才会出现在网上。

在每篇你要发布的文章第一行，必须加上这样的“文件头”：

YAML

t d p t i a u a t t b g l e l s e : i : : s 2 h [ 这 0 : 标 里 2 签 写 6 t 1 文 - r , 章 0 u 标 1 e 标 题 - 签 1 2 3 ]

  • title: 必填。网站上显示的标题。

  • date: 必填。决定文章的排序（越新越靠前）。

  • publish: true: 核心开关。

    • 写了 true -> 发布。

    • 写了 false 或者没写这行 -> 仅本地可见（私密）。

  • tags: 选填。便于以后归档。

3. 操作流程 (Workflow)

  1. 写：在 Obsidian 里通过 Ctrl+N 新建笔记，写内容。

  2. 拖：写完后，把笔记拖入对应的文件夹（比如写了首诗，拖进 30_Poetry）。

  3. 头：在文章开头插入 YAML 头，并设置 publish: true。

  4. 推：

    • 自动模式：什么都不用做，等待 Obsidian Git 插件自动运行（如果你设置了每10分钟）。

    • 手动模式：按下 Ctrl + P -> 输入 git push -> 回车。

第二部分：项目全景回顾 (我们做了什么)

我们不仅仅是搭了一个博客，我们构建了一套自动化内容分发系统 (CI/CD)。

1. 项目目标 (Goal)

创建一个**“主权在己”**的知识库。

  • 数据安全：所有数据都在本地（Obsidian）和私有云（阿里云）各存一份，不依赖任何第三方平台（如知乎、微信公众号）。

  • 极简高效：用最轻量的工具（Hugo + Nginx），实现毫秒级的访问速度。

  • 自动化：写作即发布，消除排版、上传、部署的繁琐过程。

2. 架构层级 (Architecture)

  • L1 本地层 (Windows + Obsidian)：

    • 你的“大脑”和“编辑器”。

    • 使用 Obsidian Git 插件作为传输器。

  • L2 传输层 (SSH + Git)：

    • 一条加密的隧道。我们配置了 SSH Key，实现了免密传输。

    • 阿里云上的 /data/.../blog.git 是一个裸仓库，只存版本记录。

  • L3 逻辑层 (Python + Hugo)：

    • Python 脚本 (deploy.py)：这是我们写的“管家”。它负责把 Git 里的文件解压，筛选出 publish: true 的文章，并分拣到不同目录。

    • Hugo：这是“印刷机”。它把 Markdown 文本瞬间渲染成 HTML 网页。

  • L4 展示层 (Nginx)：

    • 高性能 Web 服务器。它负责把 Hugo 生成的 HTML 展示给访问者。

  • L5 存储层 (Alist + Docker)：

    • 我们还部署了 Alist，挂载了阿里云盘，作为你的“无限云端硬盘”。

3. 我们克服的困难 (Milestones)

  • ✅ Docker 化部署：用 Docker 运行 Nginx 和 Alist，保证系统干净。

  • ✅ SSH 免密打通：解决了 Windows 与 Linux 的连接权限问题。

  • ✅ 版本兼容性：解决了 Ubuntu 自带 Hugo 版本过低的问题，手动升级到 v0.146.0。

  • ✅ Python 自动化：手写了定制化的发布脚本，解决了中文乱码和隐私过滤问题。

  • ✅ 模块化架构：成功将网站拆分为技术、人文、诗词等独立板块。

第三部分：未来的路 (Next Steps)

虽然地基已经打好，但装修才刚刚开始。以下是你可以考虑的升级方向：

1. 图片解决方案 (图床)

  • 现状：目前如果你在文章里插图，图片存在 Git 里会导致仓库越来越大，同步变慢。

  • 目标：搭建一个“图床”（比如用 PicGo + 阿里云 OSS，或者 PicList + 你的 Alist）。

  • 效果：Obsidian 里粘贴图片，自动上传云端，文章里只留一个链接，轻量化。

2. 视觉美化 (CSS 魔改)

  • 现状：PaperMod 主题是白色的标准样式，很极简，但不够“风雅”。

  • 目标：

    • 给“附庸风雅”板块增加古风背景。

    • 让诗词页面支持竖排文字。

    • 修改字体（比如引入霞鹜文楷）。

3. 功能增强

  • 搜索：开启 PaperMod 自带的搜索功能（Search），方便查找过往文章。

  • 评论：接入 Giscus 或 Waline，让读者（或者朋友）可以评论你的文章。

  • HTTPS：申请一个免费的 SSL 证书，把 http://yunfei.life 变成 https://，让浏览器不再提示“不安全”。

4. 更多自动化

  • 自动备份：写一个脚本，每天凌晨把你的 Obsidian 仓库打包备份到阿里云盘（通过 Alist），防止 Git 崩溃。

云飞的数字庭院：Serverless 自动化写作流技术文档

1. 项目概述

本系统旨在实现“写完即发布”的无感化写作体验。通过 Git 钩子触发 Python 脚本，自动完成 Obsidian 笔记的分类、图片资产同步、路径纠错、Hugo 静态构建以及 Nginx 部署。

2. 核心目录职能表

所有文件均位于服务器的 /data/my-knowledge-system/ 目录下。

目录名称 具体位置 (Absolute Path) 职能定义 比喻
Git 传达室 obsidian-git/blog.git/ 接收本地推送到服务器的数据包。 声控收信箱
原材料仓 obsidian-raw/ 存放 Git 解压后的原始 Markdown 和图片。 物料堆场
加工车间 hugo-site/ Hugo 程序的根目录，负责将文字转为网页。 印刷工厂
指挥中心 scripts/ 存放核心自动化 Python 脚本。 总调度室
成品展厅 web-site/ 存放最终生成的网页文件，对外提供访问。 精品柜台

3. 关键文件功能详解

3.1 自动化引擎：deploy.py

  • 位置：/data/my-knowledge-system/scripts/deploy.py

  • 功能：

    • Git 检出：将 Git 仓库的内容刷新到 obsidian-raw。

    • 资产搬运：将图片文件夹同步至 Hugo 的静态资源目录。

    • 路径纠错：扫描 Markdown 内容，自动将 99_Assets/ 转换为 /99_Assets/，解决网页图片不显示的问题。

    • 分类投放：根据文件夹名（如 10_Tech），将笔记投放到 Hugo 对应的频道（如 tech）。

3.2 自动触发器：post-receive (Git Hook)

  • 位置：/data/my-knowledge-system/obsidian-git/blog.git/hooks/post-receive

  • 功能：

    • 监听器：时刻监控 Git 仓库。

    • 自动激活：一旦检测到本地有 push 动作，立即唤醒 deploy.py 执行部署任务。

3.3 站点配置文件：hugo.toml

  • 位置：/data/my-knowledge-system/hugo-site/hugo.toml

  • 功能：

    • 外观定义：指定使用 PaperMod 主题。

    • 语法高亮：配置代码块的显示样式（如 monokai）、开启行号和复制按钮。

    • 菜单管理：定义网站顶部的“技术项目”、“人文社科”等导航栏。

4. 路径转换逻辑 (核心机制)

系统最核心的逻辑在于解决了 “Obsidian 物理路径” 与 “Web 逻辑路径” 的冲突：

  1. 本地写入：你在 Obsidian 中插入图片，路径是 99_Assets/pic.png。

  2. 物理存储：服务器上图片被存在 /static/99_Assets/pic.png。

  3. 网页请求：浏览器访问网址 yunfei.life/99_Assets/pic.png。

  4. 脚本转换：deploy.py 自动在路径前加上 /。这个斜杠是绝对路径的标志，它告诉浏览器：“不要在文章所在的文件夹里找，去网站的最顶层找！”

5. 自动化流水线流程图

  1. 本地 (Local)：

    • 在 Obsidian 写作，保存。

    • 点击 Git 插件的 Push。

  2. 云端 (Server)：

    • obsidian-git 接收数据。

    • Hook (post-receive) 被触发。

    • Script (deploy.py) 运行：

      • 提取原稿 -> 修正路径 -> 搬运图片 -> 启动 Hugo 构建。

  3. 发布 (Nginx)：

    • web-site/ 目录更新，网页立即可见。

6. 后期维护建议

  • 图片命名：建议不要在图片名中使用特殊符号，空格没关系（脚本已处理）。

  • 文件夹规范：如果你想增加新分类，只需在 KnowledgeBase 下新建文件夹（如 50_Cookbook），并在 deploy.py 的 FOLDER_MAPPING 里加上映射关系即可。

  • 代码美化：写作时务必在代码块开头加上语言标识（如 ```python），排版会非常漂亮。