从零搭建 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 自动创建，写作 → 保存 → 同步 → 发布，全链路自动化。