从零搭建Obsidian全栈知识系统

Mon, 06 Apr 2026 00:00:00 +0000

从零搭建 Obsidian 全栈知识系统：同步、博客、AI 一体化实战指南

核心理念

笔记不应该被困在一台设备里。 本文记录如何用一台云服务器，打通 Obsidian 的多端同步、自动博客发布、在线阅读、AI Agent 协作，构建一个完整的个人知识管理系统。

一、系统全景架构

1.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│ Albert Intelligence 知识系统 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Windows │ │ iPhone │ │ Chrome │ │
│ │ Obsidian │ │ Obsidian │ │ Web Clip │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ │ Remotely Save │ Remotely Save │ WebDAV │
│ │ (插件) │ (插件) │ │
│ └───────┬───────┘───────┬───────┘ │
│ │ │ │
│ ┌─────▼───────────────▼─────┐ │
│ │ 阿里云服务器 (Ubuntu) │ │
│ │ 47.250.14.82 │ │
│ │ │ │
│ │ ┌─────────────────────┐ │ │
│ │ │ Nginx WebDAV :18080│ │ ┌──────────────────┐ │
│ │ │ + fancyindex UI │──┼───→│ 浏览器在线阅读 │ │
│ │ │ + Markdown Viewer │ │ │ /_viewer/ │ │
│ │ └────────┬────────────┘ │ └──────────────────┘ │
│ │ │ │ │
│ │ ┌────────▼────────────┐ │ │
│ │ │ inotify 文件监听 │ │ │
│ │ │ (2秒防抖) │ │ │
│ │ └────────┬────────────┘ │ │
│ │ │ │ │
│ │ ┌────────▼────────────┐ │ │
│ │ │ Python 处理器 │ │ │
│ │ │ · 过滤 public:true │ │ │
│ │ │ · 转换 wikilinks │ │ │
│ │ │ · 注入 title/date │ │ │
│ │ └────────┬────────────┘ │ │
│ │ │ │ │
│ │ ┌────────▼────────────┐ │ ┌──────────────────┐ │
│ │ │ Hugo 静态站点生成 │──┼───→│ 公开博客 :18081 │ │
│ │ │ Stack 主题 │ │ │ 搜索/归档/标签 │ │
│ │ └─────────────────────┘ │ └──────────────────┘ │
│ │ │ │
│ │ ┌─────────────────────┐ │ │
│ │ │ Let's Encrypt SSL │ │ │
│ │ │ Certbot + DNS-01 │ │ │
│ │ │ (Cloudflare API) │ │ │
│ │ └─────────────────────┘ │ │
│ └───────────────────────────┘ │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ Claude │ │ Obsidian │ │
│ │ Code │◄──►│ Agent Client │ AI 协作层 │
│ │ (终端) │ │ (ACP 协议) │ │
│ └──────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘

1.2 技术栈一览

层级	组件	用途
客户端	Obsidian (Win/iOS)	笔记编辑器
客户端	Chrome + Obsidian Web Clipper	网页剪藏
客户端	Agent Client 插件	AI Agent 交互
同步层	Remotely Save 插件	WebDAV 双向同步
存储层	Nginx WebDAV	文件存储和访问
展示层	fancyindex + Viewer	在线浏览笔记
发布层	Hugo + Stack 主题	静态博客生成
自动化	inotify + systemd	文件变更监听和自动构建
安全层	Let’s Encrypt + Cloudflare	HTTPS 加密 + DNS 管理
AI 层	Claude Code + OpenCode	AI 辅助写作和开发

1.3 端口规划

端口	服务	域名	访问权限
18080	WebDAV + 在线阅读	obsidian.hialbert.online	Basic Auth (私密)
18081	Hugo 博客	blog.hialbert.online	公开访问
2026	SSH	—	密钥认证

二、核心数据流

2.1 写作 → 同步 → 发布流程

你在 Obsidian 写了一篇笔记
 │
 ▼
 在 frontmatter 加入 public: true
 │
 ▼
 Remotely Save 自动同步到阿里云 WebDAV
 (/var/www/webdav/obsidian/)
 │
 ▼
 inotify 检测到文件变化（2秒防抖）
 │
 ▼
 obsidian-to-hugo.sh 启动：
 ├─ 1. 清空 Hugo content/post/ 目录
 ├─ 2. 扫描所有 .md 文件
 ├─ 3. 过滤出 public: true 的文件
 ├─ 4. Python 处理器：
 │ ├─ 规范化 frontmatter
 │ ├─ 自动注入 title（从文件名）
 │ ├─ 自动注入 date（从 created 字段）
 │ ├─ 转换 wikilinks 为标准链接
 │ └─ 移除 !嵌入 语法
 └─ 5. 复制到 Hugo content/post/
 │
 ▼
 Hugo 构建静态站点 → /var/www/hugo-blog/public/
 │
 ▼
 博客自动更新 ✅
 https://blog.hialbert.online:18081/

2.2 下架文章的三种方式

方式	操作	效果
改为 `public: false`	修改 frontmatter	笔记保留，博客消失（推荐）
删除 `public` 字段	删掉那一行	笔记保留，博客消失
删除整篇笔记	Obsidian 里删除	笔记和博客都消失

💡 安全机制

同步脚本每次运行都会先清空再重建 Hugo 的文章目录。没有 public: true 标记的笔记绝对不会出现在博客上。

2.3 在线阅读流程（Markdown Viewer）

浏览器访问 fancyindex 文件目录
 │
 ▼
 点击 .md 文件（链接已被 JS 重写）
 │
 ▼
 跳转到 /_viewer/?file=Diary/领域/xxx.md
 │
 ▼
 viewer.html 加载：
 ├─ fetch GET 读取原始 .md 文件（只读，不修改原文件）
 ├─ 去掉 YAML frontmatter
 ├─ marked.js 渲染 Markdown → HTML
 ├─ highlight.js 代码高亮
 └─ 显示渲染后的页面
 │
 ▼
 工具栏：← 返回目录 | 📥 下载原文 | 🌙 深浅色切换

📌 只读保证

Viewer 只发 HTTP GET 请求，绝不会修改、删除、覆盖原始文件。你的 Obsidian 笔记安全无虞。

三、Obsidian Vault 目录结构

3.1 本地 Vault 结构

Diary/ ← Vault 根目录
├── .obsidian/ ← Obsidian 配置（插件、主题、快捷键等）
│ └── plugins/
│ ├── remotely-save/ ← WebDAV 同步插件
│ ├── obsidian-local-rest-api/ ← REST API 插件
│ ├── agent-client/ ← AI Agent 客户端插件
│ └── obsidian42-brat/ ← Beta 插件管理器
├── 收件箱/ ← 📥 临时笔记、快速捕捉
├── Clippings/ ← 📰 Chrome Web Clipper 剪藏
├── 领域/ ← 🎯 深度研究主题
│ ├── Obsidian多端同步搭建全记录.md
│ ├── Obsidian核心用法指南.md
│ ├── 大模型记忆与检索机制研究/
│ └── 新agent/
├── 收藏夹/ ← ⭐ 精选内容
├── 项目/ ← 📁 进行中的项目
├── 归档/ ← 🗄️ 已完成的内容
├── 永久笔记.md ← 📝 MOC 索引
└── MOC.md ← 🗺️ 全局地图

3.2 服务器端目录结构

/var/www/
├── webdav/obsidian/ ← WebDAV 同步根目录
│ └── Diary/ ← Vault 内容（与客户端实时同步）
│ ├── 收件箱/
│ ├── Clippings/
│ ├── 领域/
│ └── ...
├── hugo-blog/ ← Hugo 博客项目
│ ├── hugo.yaml ← Hugo 配置
│ ├── content/
│ │ ├── post/ ← 自动同步的博客文章（public: true）
│ │ ├── page/
│ │ │ └── search/ ← 搜索页面
│ │ ├── about/ ← 关于页面
│ │ └── archives/ ← 归档页面
│ ├── static/img/ ← 头像等静态资源
│ ├── themes/stack/ ← Stack 主题（Git submodule）
│ ├── layouts/_partials/ ← 主题覆写（sidebar 头像修复）
│ └── public/ ← Hugo 构建输出（Nginx 直接 serve）
└── obsidian-ui/ ← WebDAV 美化 UI
 ├── header.html ← fancyindex 页头（导航栏 + CSS）
 ├── footer.html ← fancyindex 页脚（.md 链接重写 JS）
 ├── viewer.html ← Markdown 在线阅读器
 └── avatar.jpg ← 头像（WebDAV UI 用）

四、功能模块详解

4.1 多端同步（Remotely Save + WebDAV）

原理： 每台设备上的 Obsidian 通过 Remotely Save 插件连接到同一个 WebDAV 服务器，实现双向增量同步。

配置要点：

# Remotely Save 插件设置
服务类型: WebDAV
地址: https://obsidian.hialbert.online:18080/obsidian/
用户名: obsidian
密码: ******
Depth Header: infinity

安全措施：

HTTPS 全链路加密（Let’s Encrypt 证书）
Basic Auth 身份验证
非标准端口 18080（避开常见扫描）
DNS-01 验证方式（无需开放 80 端口）

💡 冲突解决

Remotely Save 根据文件的修改时间戳判断版本新旧。如果两端同时修改同一文件，会保留最新的版本。建议一次只在一台设备编辑。

4.2 WebDAV 文件管理界面（fancyindex）

访问 https://obsidian.hialbert.online:18080/obsidian/ 即可看到 GitHub 风格的深色目录列表，特性包括：

📁 文件夹图标和 📝 Markdown 文件图标自动识别
🖼️ 图片、🎬 视频、🎵 音频文件类型图标
圆形头像 + “Personal Knowledge Base by Albert” 品牌展示
按名称、日期、大小排序
响应式布局，手机端也能用

4.3 Markdown 在线阅读器（Viewer）

点击任意 .md 文件即可在浏览器中渲染阅读，无需下载。

技术实现：

marked.js — Markdown → HTML 实时渲染
highlight.js — 代码块语法高亮（支持 Python、JavaScript、Bash 等）
纯前端 — 零后端依赖，不占服务器资源
只读 — 只发 GET 请求，绝不修改原文件

功能：

面包屑导航（obsidian / Diary / 领域 / xxx.md）
← 返回目录按钮
📥 下载原文按钮
🌙/☀️ 深浅色切换（localStorage 记忆）
自动剥离 YAML frontmatter
图片相对路径自动转换
wikilinks 和 !embeds 显示为行内代码

4.4 Hugo 静态博客（Stack 主题）

访问 https://blog.hialbert.online:18081/ 即可看到自动发布的博客。

博客特性：

🔍 全文搜索 — 侧栏搜索框，Fuse.js 模糊匹配
📂 分类和标签 — 自动从 frontmatter 提取
📅 归档 — 按时间线展示所有文章
🌗 深浅色切换 — 跟随系统或手动切换
📱 响应式 — 手机端完美适配
📖 目录导航 — 文章内自动生成 TOC
⏱️ 阅读时长 — 自动计算
🔗 RSS 订阅 — 支持全文 RSS

发布控制：

只需在 Obsidian 笔记的 frontmatter 中加一行：

---
public: "true" # 加这一行，文章自动发布到博客
---

不加或改为 false，文章只存在于你的私人 Vault 中。

4.5 自动构建管道（inotify + systemd）

┌──────────────┐ ┌───────────────┐ ┌──────────────┐
│ inotify │────→│ 防抖 2秒 │────→│ obsidian-to- │
│ 监听文件 │ │ 合并多次 │ │ hugo.sh │
│ 变更事件 │ │ 触发 │ │ 过滤+转换 │
└──────────────┘ └───────────────┘ └──────┬───────┘
 │
 ┌──────▼───────┐
 │ Hugo 构建 │
 │ 静态 HTML │
 └──────────────┘

systemd 保障：

Restart=always — 进程崩溃自动重启
RestartSec=5 — 5 秒后重启
开机自动启动
日志记录到 /var/log/obsidian-hugo.log

查看实时日志：

tail -f /var/log/obsidian-hugo.log

4.6 SSL 证书管理（Certbot + Cloudflare DNS-01）

为什么用 DNS-01 而不是 HTTP-01？

HTTP-01 需要开放 80 端口（安全风险）
DNS-01 通过 Cloudflare API 验证域名所有权，无需开放任何额外端口

证书信息：

域名	用途	证书路径
obsidian.hialbert.online	WebDAV	`/etc/letsencrypt/live/obsidian.hialbert.online/`
blog.hialbert.online	博客	`/etc/letsencrypt/live/blog.hialbert.online/`

自动续期： Certbot 自带 systemd timer，每 12 小时检查一次是否需要续期。

五、Chrome Web Clipper — 一键剪藏到 Obsidian

5.1 是什么？

Obsidian Web Clipper 是 Chrome 浏览器扩展，可以一键将网页内容保存为 Markdown 格式，直接存入 Obsidian Vault。

5.2 工作流程

在 Chrome 中浏览文章
 │
 ▼
 点击 Web Clipper 扩展图标
 │
 ▼
 选择保存模板（剪藏/书签/高亮）
 │
 ▼
 自动转换为 Markdown 格式
 │
 ▼
 保存到 Vault 的 Clippings/ 目录
 │
 ▼
 Remotely Save 同步到云端
 │
 ▼
 所有设备都能看到这篇剪藏 ✅

5.3 Frontmatter 自动生成

Web Clipper 剪藏的笔记会自动生成结构化的 frontmatter：

---
title: "文章标题"
source: https://原文链接
author: 作者名
published: 2026-04-01
created: 2026-04-06T13:26:35+08:00
tags:
 - 状态/收件箱
 - 来源/文章
 - 主题/
---

💡 配合 Inbox 工作流

剪藏的文章默认打上 状态/收件箱 标签，提醒你稍后阅读和整理。处理完后改为 状态/完成 并移动到对应的领域文件夹。

六、AI 协作层 — Agent Client + Claude Code

6.1 Agent Client 插件

Agent Client 插件通过 Agent Client Protocol (ACP) 将 AI Agent（如 Claude Code、Codex、Gemini CLI）引入 Obsidian，实现直接在编辑器中与 AI 对话。

核心功能：

@笔记引用 — 在对话中用 @笔记名 引用 Vault 中的笔记内容
图片粘贴 — 直接拖拽图片到对话框
斜杠命令 — 使用 / 调用 Agent 提供的命令
多 Agent 切换 — 同时运行 Claude Code、Codex 等
会话历史 — 恢复或分叉之前的对话
导出为笔记 — 将对话保存为 Markdown

安装方式：

先安装 BRAT 插件（Beta 插件管理器）
BRAT → Add Beta Plugin → 粘贴 https://github.com/RAIT-09/obsidian-agent-client
启用 Agent Client

6.2 Local REST API 插件

让外部程序（如 Claude Code、脚本）通过 HTTP API 操控 Obsidian。

API 端点：

端点	方法	用途
`/vault/`	GET	列出 Vault 根目录文件
`/vault/{path}`	GET	读取指定文件内容
`/vault/{path}`	PUT	创建或更新文件
`/vault/{path}`	DELETE	删除文件
`/vault/{path}`	PATCH	追加内容到文件

示例 — 用 curl 读取笔记：

curl http://127.0.0.1:27123/vault/领域/Obsidian核心用法指南.md \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Accept: text/markdown"

示例 — 用 curl 创建笔记：

curl -X PUT http://127.0.0.1:27123/vault/收件箱/新笔记.md \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: text/markdown" \
 -d "# 新笔记标题

这是正文内容。"

6.3 Claude Code + Obsidian 联动

Claude Code（终端 AI 助手）可以通过 Local REST API 直接与 Obsidian 交互：

用户在终端对 Claude Code 说：
 "在 Obsidian 里面创建一篇关于 XXX 的笔记"
 │
 ▼
 Claude Code 调用 REST API：
 PUT /vault/领域/XXX.md
 Content-Type: text/markdown
 Body: 生成的 Markdown 内容
 │
 ▼
 笔记立即出现在 Obsidian 中 ✅
 │
 ▼
 Remotely Save 同步到所有设备
 │
 ▼
 如果 frontmatter 包含 public: true
 → 自动发布到博客 🚀

📝 实际使用体验

本文就是通过 Claude Code 调用 Obsidian REST API 直接创建的——写作、保存、同步、发布，全链路自动化。

七、安全架构

7.1 多层安全防护

Internet
 │
 ▼
┌───────────────────┐
│ Cloudflare DNS │ DNS 层：隐藏真实 IP（Proxy 模式可选）
└────────┬──────────┘
 │
┌────────▼──────────┐
│ 阿里云防火墙 │ 网络层：只开放 18080、18081、2026
└────────┬──────────┘
 │
┌────────▼──────────┐
│ Let's Encrypt SSL │ 传输层：TLS 1.2/1.3 加密
│ (DNS-01 验证) │ 无需开放 80 端口
└────────┬──────────┘
 │
┌────────▼──────────┐
│ Nginx Basic Auth │ 应用层：用户名密码认证
│ (.htpasswd) │ WebDAV 和 Viewer 都受保护
└────────┬──────────┘
 │
┌────────▼──────────┐
│ SSH Key Only │ 管理层：仅密钥登录，禁用密码
│ (Port 2026) │ 非标准端口
└───────────────────┘

7.2 公私分离设计

内容	访问方式	认证
全部 Vault 笔记	WebDAV (:18080)	Basic Auth 必须
在线阅读 Viewer	/_viewer/ (:18080)	Basic Auth 必须
博客文章 (public: true)	Hugo (:18081)	无需认证，公开
博客搜索	/search/ (:18081)	无需认证，公开

核心原则：私密笔记永远不会意外暴露。 只有你明确标记 public: true 的文章才会通过 Hugo 发布到公开博客。

八、核心配置文件速览

8.1 Nginx 配置（双域名双端口）

# WebDAV + 在线阅读
server {
 listen 18080 ssl;
 server_name obsidian.hialbert.online;

 location /_viewer/ {
 # Markdown 在线阅读器（Basic Auth 保护）
 }

 location /obsidian/ {
 # WebDAV 文件同步
 dav_methods PUT DELETE MKCOL COPY MOVE;
 dav_ext_methods PROPFIND OPTIONS;
 fancyindex on;
 }
}

# Hugo 博客
server {
 listen 18081 ssl;
 server_name blog.hialbert.online;
 root /var/www/hugo-blog/public;
}

8.2 Hugo 配置（核心参数）

baseURL: "https://blog.hialbert.online:18081/"
title: "Albert Intelligence"
theme: "stack"
defaultContentLanguage: "zh"

params:
 sidebar:
 subtitle: "Knowledge, AI & Life"
 avatar: "/img/avatar.jpg"
 widgets:
 homepage:
 - type: search  # 全文搜索
 - type: archives  # 归档
 - type: categories  # 分类
 - type: tag-cloud  # 标签云

8.3 发布控制（frontmatter 标记）

---
tags:
 - 类型/永久笔记
 - 主题/Obsidian
created: 2026-04-06
public: "true" # ← 这一行控制是否发布
---

九、已安装的 Obsidian 插件清单

插件	用途	必要性
Remotely Save	WebDAV 多端同步	必须
Local REST API	外部程序控制 Obsidian	推荐（AI 协作必需）
Agent Client	在 Obsidian 内使用 AI Agent	可选（提升效率）
BRAT	安装 Beta 插件	可选（Agent Client 依赖）
Obsidian Web Clipper	Chrome 网页剪藏	推荐

十、常见问题 FAQ

Q1: 同步冲突怎么办？

Remotely Save 以最后修改时间为准。建议同一时间只在一台设备上编辑。如果发生冲突，可以在 Remotely Save 设置中查看同步日志。

Q2: 博客文章标题/日期显示异常？

确保 frontmatter 中包含 title 和 date（或 created）字段。同步脚本会自动从文件名和 created 字段注入，但手动指定更可靠：

---
title: "你的文章标题"
date: 2026-04-06
---

Q3: SSL 证书过期了怎么办？

Certbot 会自动续期。如果手动续期：

certbot renew --dns-cloudflare \
 --dns-cloudflare-credentials /etc/letsencrypt/cloudflare/credentials.ini

Q4: 在线阅读器会修改我的笔记吗？

绝对不会。 Viewer 只发 HTTP GET 请求读取文件，渲染过程完全在浏览器端完成。服务器上的 .md 文件纹丝不动，不会影响任何设备的 Obsidian 同步。

Q5: 服务器配置要求？

最低 1 核 1G 就够用。当前使用阿里云 2 核 2G（马来西亚），内存占用约 445MB（28%），磁盘 3.4G/40G（10%），非常轻量。

Q6: 这套系统的运行成本？

项目	费用
域名 (.online)	¥7/年（首年）
阿里云服务器	视套餐而定
SSL 证书	免费（Let’s Encrypt）
Cloudflare DNS	免费
Hugo + Stack 主题	免费开源
Obsidian 客户端	免费
所有插件	免费

十一、未来可扩展方向

Excalidraw 支持 — 在线渲染手绘图
评论系统 — 博客接入 Giscus (GitHub Discussions)
图床 — 将笔记中的图片上传到 CDN
全文搜索增强 — 在 WebDAV 端也加搜索功能
移动端 PWA — 博客添加 manifest.json 支持离线访问
自动备份 — 定期将 Vault 备份到 S3 或 OSS
Graph View 在线版 — 用 D3.js 渲染 Vault 的关系图谱

十二、总结

这套系统的核心理念是 “写一次，到处用”：

写 — 在任意设备的 Obsidian 中写笔记
同步 — Remotely Save 自动同步到云端
阅读 — 浏览器在线阅读，无需安装 Obsidian
发布 — 加一行 public: true 自动变成博客
剪藏 — Chrome 一键保存网页到 Vault
AI — Claude Code 直接读写你的笔记

所有环节都是自动化的。 你只需要专注于一件事——写好你的笔记。

Quote

“The best note-taking system is the one you actually use.” 最好的笔记系统，是你真正会用的那个。

本文由 Claude Code 通过 Obsidian Local REST API 自动创建，写作 → 保存 → 同步 → 发布，全链路自动化。

主题/技术分享 on Albert Intelligence