📖 夜航船 · 更新于 2026-04-27 18:57

从零搭建 AI 知识库与博客完全指南

#教程 #Hermes #Obsidian #GitHub #博客搭建 #知识库 #Astro

一句话总结：用 Obsidian 管理知识，用 Hermes Agent 自动化一切，用 GitHub Pages 部署博客。三个工具组合，零成本搭建属于自己的知识体系和公开博客。

📌 目录

一、我们做了什么
二、技术栈总览
三、整体架构
四、第一步：搭建 Obsidian 知识库
五、第二步：安装 Hermes Agent
六、第三步：配置 Telegram 网关
七、第四步：搭建 Astro 博客
八、第五步：打通 Obsidian → 博客的同步管道
九、第六步：自动化日报和定时任务
十、日常使用工作流
十一、踩坑记录与解决方案
十二、费用与资源消耗
十三、给新朋友的建议

一、我们做了什么

最终效果

组件	状态	地址
📝 知识库（Obsidian Vault）	✅ 运行中	本地 + Obsidian Cloud 同步
🤖 AI 助手（Hermes Agent）	✅ 运行中	Telegram 直接对话
🌐 公开博客	✅ 运行中	baiye1997.github.io
📰 每日早晚报	✅ 自动生成	08:00 / 22:30 自动推送
📖 每日英语	✅ 自动推送	早晚各一篇
📊 投资周报	✅ 自动生成	每周日汇总

能做什么

在 Telegram 里跟 AI 助手聊天，让它帮你写笔记、查资料、分析数据
笔记自动同步到 Obsidian Cloud，手机/电脑都能看
公开笔记自动同步到博客，全世界都能访问
定时任务自动生成日报、英语单词、投资周报
AI 记住你的偏好和习惯，越用越懂你

二、技术栈总览

┌─────────────────────────────────────────────────────┐
│                    你的设备（Mac/手机）                │
│  Obsidian App  ←→  ob sync  ←→  Obsidian Cloud      │
└──────────────┬──────────────────────────────────────┘
               │ git push
               ▼
┌─────────────────────────────────────────────────────┐
│              GitHub: obsidian-vault（私有仓库）       │
│              存放所有笔记原文                          │
└──────────────┬──────────────────────────────────────┘
               │ notify-blog.yml 触发
               ▼
┌─────────────────────────────────────────────────────┐
│              GitHub: baiye1997.github.io             │
│  deploy.yml: 克隆vault → 脱敏 → Astro build → 部署  │
└──────────────┬──────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────┐
│              GitHub Pages（静态网站）                  │
│              baiye1997.github.io                     │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│              Hermes Agent（AI 助手）                  │
│  服务器运行  ←→  Telegram Gateway  ←→  你            │
│  - 读写 Obsidian 笔记                                │
│  - 执行定时任务                                       │
│  - 管理博客部署                                       │
└─────────────────────────────────────────────────────┘

各组件职责

工具	角色	说明
Obsidian	知识管理	Markdown 笔记编辑器，双向链接、标签、图谱
ob CLI	无头同步	Obsidian Headless CLI，在服务器上同步笔记到云端
Hermes Agent	AI 大脑	开源 AI agent，连接 LLM，读写文件，执行任务
GitHub	版本控制 + CI/CD	笔记仓库 + 博客仓库，Actions 自动构建部署
GitHub Pages	博客托管	免费静态网站托管
Astro	博客框架	静态站点生成器，SSG 模式构建博客
Telegram	对话入口	通过 Hermes Gateway 连接，随时随地跟 AI 聊天

三、整体架构

数据流

你在 Telegram 说话
    ↓
Hermes Agent 接收消息
    ↓
调用 LLM 生成回复（GPT/Claude/DeepSeek 等）
    ↓
执行工具：读写文件 / 搜索网页 / 发送消息 / 管理定时任务
    ↓
写入 ~/obsidian-vault/ 笔记
    ↓
ob sync → Obsidian Cloud（手机端可见）
    ↓
git push → GitHub vault 仓库
    ↓
GitHub Actions 自动触发 deploy.yml
    ↓
克隆 vault → 过滤私密内容 → 脱敏 → Astro 构建 → 部署到 GitHub Pages

两个同步的区别（重要！）

这是新手最容易搞混的地方：

命令	同步到哪	用途
`ob sync`	Obsidian Cloud	让手机/电脑的 Obsidian App 能看到笔记
`git push`	GitHub	让博客能获取到笔记并部署

ob sync ≠ git push，它们是两件事！

笔记改完后：

所有笔记都跑 ob sync（确保手机能看）
公开笔记额外跑 git push（确保博客更新）

四、第一步：搭建 Obsidian 知识库

4.1 安装 Obsidian

去 obsidian.md 下载安装，全平台免费。

4.2 创建 Vault

打开 Obsidian → Create new vault → 取个名字（比如”落魄山知识库”）。

4.3 设计文件夹结构

好的文件夹结构是一切的基础。我们最终用的结构：

~/obsidian-vault/
├── 🏔️ 山水邸报/      # 每日早晚报（自动生成）
├── 📖 夜航船/         # 技术调研和研究报告
├── 📒 学海无涯/       # 每日英语单词
├── 💰 金精铜钱/       # 投资周报
├── 📖 本周必读/       # 每周精选文章
├── 📜 撼山拳谱/       # 技能手册
├── 🍺 二掌柜的酒铺/   # 私人日记（不同步到博客）
├── README.md          # 知识库总索引
└── graph.md           # 知识图谱

4.4 配置 Obsidian Sync

Obsidian 自带免费的 Obsidian Sync（设备间同步），也可以用 iCloud / Syncthing 等替代方案。

配置好后，你的笔记会在所有设备间实时同步。

4.5 Frontmatter 规范

每篇笔记开头加 YAML frontmatter，方便程序解析：

---
title: 笔记标题
date: 2026-04-27
type: 日记
tags:
  - 标签1
  - 标签2
---

4.6 文件命名规范

文件夹	命名格式	示例
山水邸报	`{日期}-{早报/晚报}-{标题}`	`2026-04-27-早报-央行MLF缩量续作.md`
学海无涯	`{日期}-{单词}`	`2026-04-27-subtle.md`
本周必读	`{年}-第{N}周`	`2026-第17周.md`
二掌柜的酒铺	`{日期}-{标题}`	`2026-04-27-新家选购记.md`

五、第二步：安装 Hermes Agent

5.1 什么是 Hermes

Hermes Agent 是 Nous Research 开源的 AI agent 框架。简单说，它是一个住在你服务器上的 AI 助手，可以：

通过 Telegram / Discord / Slack 等平台跟你对话
读写文件、执行命令、搜索网页
调用各种 LLM（GPT-4、Claude、DeepSeek 等）
记住你的偏好（跨会话记忆）
自动执行定时任务

5.2 安装

# 一键安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 重新加载 shell
source ~/.bashrc

# 验证安装
hermes version
hermes doctor

5.3 初始配置

# 交互式设置向导
hermes setup

# 选择模型/提供商
hermes model

支持 20+ 提供商，常用的：

提供商	环境变量	说明
OpenRouter	`OPENROUTER_API_KEY`	聚合平台，推荐
Anthropic	`ANTHROPIC_API_KEY`	Claude 系列
OpenAI	`OPENAI_API_KEY`	GPT 系列
DeepSeek	`DEEPKEEP_API_KEY`	国产，便宜好用
小米 MiMo	`XIAOMI_API_KEY`	国产新秀

API Key 放在 ~/.hermes/.env 文件里。

5.4 配置 Obsidian Headless CLI

Hermes 需要通过 ob 命令来同步 Obsidian 笔记到云端：

# 安装 Obsidian Headless CLI
npm install -g obsidian-headless

# 配置 vault 路径
cd ~/obsidian-vault
ob login  # 用 Obsidian 账号登录

# 测试同步
ob sync

5.5 配置文件

Hermes 的配置在 ~/.hermes/config.yaml：

model:
  default: openrouter/anthropic/claude-sonnet-4
  provider: openrouter

memory:
  memory_enabled: true
  user_profile_enabled: true

agent:
  max_turns: 90

terminal:
  backend: local
  cwd: /home/你的用户名

六、第三步：配置 Telegram 网关

6.1 创建 Telegram Bot

在 Telegram 搜索 @BotFather
发送 /newbot
给 bot 取名（比如”白也的小助手”）
获得 bot token（格式：123456:ABC-DEF...）

6.2 配置 Hermes Gateway

# 交互式配置
hermes gateway setup

# 选择 Telegram 平台
# 输入 bot token

或者直接编辑 ~/.hermes/config.yaml：

gateway:
  platforms:
    telegram:
      enabled: true
      token: "你的bot token"
      allowed_users:
        - 你的telegram_user_id  # 安全起见限制只有你能用

6.3 启动 Gateway

# 安装为系统服务（后台运行）
hermes gateway install
hermes gateway start

# 或者前台运行（调试用）
hermes gateway run

6.4 测试

在 Telegram 里找到你的 bot，发一条消息，应该能收到 AI 回复。

七、第四步：搭建 Astro 博客

7.1 为什么选 Astro

SSG 模式：构建时生成静态 HTML，部署超快
性能好：零 JS 默认，按需加载
生态丰富：Tailwind CSS、Sitemap、RSS 都有官方集成
Markdown 原生支持：和 Obsidian 笔记完美契合

7.2 创建项目

# 创建 Astro 项目
npm create astro@latest baiye1997.github.io

# 进入目录
cd baiye1997.github.io

# 安装 Tailwind CSS
npx astro add tailwind

# 安装其他依赖
npm install @astrojs/sitemap @astrojs/rss

7.3 项目结构

baiye1997.github.io/
├── src/
│   ├── content/
│   │   └── notes/          # Obsidian 笔记会同步到这里
│   │       ├── 🏔️ 山水邸报/
│   │       ├── 📖 夜航船/
│   │       ├── 📒 学海无涯/
│   │       └── ...
│   ├── pages/
│   │   ├── index.astro     # 首页
│   │   ├── about.astro     # 关于页
│   │   ├── notes/
│   │   │   ├── index.astro # 笔记列表
│   │   │   └── [...slug].astro # 笔记详情
│   │   └── rss.xml.ts      # RSS Feed
│   └── layouts/
│       └── Layout.astro    # 全局布局
├── public/                  # 静态资源
├── .github/workflows/
│   └── deploy.yml          # CI/CD 部署脚本
└── package.json

7.4 关键配置

astro.config.mjs：

import { defineConfig } from 'astro/config';
import tailwind from '@tailwindcss/astro';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://baiye1997.github.io',
  integrations: [tailwind(), sitemap()],
});

笔记页面（notes/[…slug].astro） 需要：

用 import.meta.glob 读取 src/content/notes/**/*.md
过滤私密内容（二掌柜的酒铺、README、规范文件等）
格式化日期（兼容中文星期后缀如 “2026-04-24 星期五”）
移动端排版优化（15px 正文、1.75 行高、表格横向滚动）

7.5 设计风格

我们选择了 iOS App Store 风格：

✅ 白色卡片 + 浅灰背景，简洁留白
✅ 图标底色用 颜色/10 透明度
✅ 标签用浅灰底 #F2F2F7
❌ 不要大色块背景（“AI 味”太重）
❌ 不要渐变 Hero 区域

深色模式用 Tailwind v4 的 class 策略：

/* global.css */
@import "tailwindcss";
@custom-variant dark (&:is(.dark *));

八、第五步：打通 Obsidian → 博客的同步管道

这是整个方案的核心。分两条线：

8.1 Obsidian → Obsidian Cloud（手机可见）

cd ~/obsidian-vault
ob sync

8.2 Obsidian → GitHub（博客可见）

8.2.1 创建 GitHub 私有仓库

cd ~/obsidian-vault
git init
git remote add origin git@github.com:你的用户名/obsidian-vault.git
git add -A
git commit -m "初始笔记"
git push -u origin main

⚠️ vault 仓库一定要设为私有，因为里面有私人日记和投资数据。

8.2.2 配置 GitHub Actions（deploy.yml）

在博客仓库创建 .github/workflows/deploy.yml：

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:
  repository_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Sync notes from Obsidian vault
        env:
          OBSIDIAN_VAULT_REPO: ${{ secrets.OBSIDIAN_VAULT_REPO }}
          OBSIDIAN_VAULT_TOKEN: ${{ secrets.OBSIDIAN_VAULT_TOKEN }}
        run: |
          # 克隆 vault 私有仓库
          git clone "https://x-access-token:${OBSIDIAN_VAULT_TOKEN}@github.com/${OBSIDIAN_VAULT_REPO}" /tmp/obsidian-vault --depth 1

          # 清空现有笔记
          rm -rf src/content/notes/*

          # 逐个文件夹复制，跳过私密内容
          for dir in /tmp/obsidian-vault/*/; do
            dirname=$(basename "$dir")
            # 跳过私密文件夹
            if "$dirname" == *"二掌柜"* || "$dirname" == *"金精铜钱"*; then
              continue
            fi
            mkdir -p "src/content/notes/$dirname"
            find "$dir" -name "*.md" ! -name "README.md" | while read f; do
              cp "$f" "src/content/notes/$dirname/"
            done
          done

          # 脱敏：移除个人收益数据
          find src/content/notes -name "*.md" -exec sed -i \
            -e '/^## 💰 收益概览/,/^## [^#]/d' \
            -e '/^## 💰 今日收益明细/,/^## [^#]/d' \
            -e '/^### 持仓明细/,/^## [^#]/d' \
            -e '/^## 🔮 盘前走势预测/,/^## [^#]/d' \
            -e '/^## 📝 投资总结/,/^## [^#]/d' \
            {} +

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install & Build
        run: |
          npm ci
          npm run build

      - name: Deploy
        uses: actions/deploy-pages@v4

8.2.3 配置 Vault 仓库的 notify-blog.yml

在 vault 仓库创建 .github/workflows/notify-blog.yml：

name: Notify Blog to Sync

on:
  push:
    branches: [main]

jobs:
  trigger-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger blog deploy
        env:
          GH_TOKEN: ${{ secrets.BLOG_TRIGGER_TOKEN }}
        run: |
          gh workflow run deploy.yml --repo 你的用户名/baiye1997.github.io

8.2.4 设置 GitHub Secrets

在两个仓库的 Settings → Secrets and variables → Actions 中添加：

vault 仓库：

OBSIDIAN_VAULT_REPO = 你的用户名/obsidian-vault
OBSIDIAN_VAULT_TOKEN = GitHub PAT（需要 repo 权限）
BLOG_TRIGGER_TOKEN = GitHub PAT（需要 workflow 权限）

博客仓库：

OBSIDIAN_VAULT_REPO = 你的用户名/obsidian-vault
OBSIDIAN_VAULT_TOKEN = 同一个 PAT

8.3 同步流程图

本地编辑笔记
    ↓
cd ~/obsidian-vault && ob sync    ←→  Obsidian Cloud（手机可见）
    ↓
git add -A && git commit && git push
    ↓
vault 仓库更新
    ↓
notify-blog.yml 触发
    ↓
deploy.yml 执行：
  1. 克隆 vault
  2. 复制公开笔记（展平子目录）
  3. sed 脱敏（移除收益数据）
  4. npm ci && npm run build（Astro 构建）
  5. 部署到 GitHub Pages
    ↓
博客更新完成 ✅

九、第六步：自动化日报和定时任务

9.1 Hermes Cron 系统

Hermes 内置 cron 调度器，可以定时执行任务并自动把结果发送到 Telegram。

# 查看所有定时任务
hermes cron list

# 手动触发
hermes cron run <job_id>

9.2 我们的定时任务

任务	时间	说明
🌅 早报	每天 08:00	天气 + A股盘前预测 + 财经新闻
🌙 晚报	每天 22:30	大盘收盘 + 投资总结 + 热点新闻
📝 每日英语	每天 08:00	一个英语单词/短语 + 例句
📊 投资周报	每周日 20:00	汇总本周山水邸报持仓数据

9.3 创建定时任务示例

通过 Hermes 对话创建：

帮我创建一个每天早上8点的定时任务，生成今天的早报。
早报内容包括：成都天气、A股盘前走势预测、最新财经新闻。
结果发送到 Telegram。

或者用 cronjob 工具直接创建：

# 早报任务
cronjob(
    action="create",
    name="山水早报",
    schedule="0 8 * * *",
    prompt="生成今天的山水早报，包括成都天气、A股盘前走势、财经新闻。",
    skills=["shan-shui-di-bao"],
    deliver="origin"  # 发回 Telegram
)

9.4 Cron 安全注意事项

⚠️ 重要：cron prompt 里不要直接写 curl 命令！

Hermes 有安全检查机制，会拦截包含 curl 的 prompt（防止数据外泄）。应该描述”做什么”而非”怎么做”：

❌ curl https://api.example.com/data | jq .
✅ 查询今天的天气数据

十、日常使用工作流

10.1 通过 Telegram 对话

最常用的场景，随时随地跟 AI 聊天：

你: 帮我写一篇关于 Docker 网络配置的学习笔记，保存到夜航船

AI: 好的，我来写一篇 Docker 网络配置的笔记...
    [写完后自动保存到 ~/obsidian-vault/📖 夜航船/]
    [执行 ob sync + git push]

你: 今天的早报准备好了吗？

AI: [自动生成早报，包括天气、新闻、行情]

10.2 直接在 Obsidian 编辑

在电脑/手机上打开 Obsidian，直接编辑笔记。改完后：

# 同步到云端（手机可见）
cd ~/obsidian-vault && ob sync

# 推送到 GitHub（博客可见）
git add -A && git commit -m "更新笔记" && git push

10.3 知识库维护

每次新增/删除笔记后，记得更新：

文件夹 README.md — 更新文档列表
主 README.md — 更新索引链接和篇数
graph.md — 更新知识图谱关系

AI 助手会自动帮你做这些，但了解流程很重要。

十一、踩坑记录与解决方案

坑 1：`ob sync` 和 `git push` 搞混

现象：笔记在手机上能看，但博客没更新。

原因：只跑了 ob sync，没跑 git push。

解决：两件事都要做。ob sync 同步到 Obsidian Cloud，git push 推送到 GitHub。

坑 2：Astro glob 路径错误

现象：首页笔记数显示为 0。

原因：import.meta.glob 的路径是相对于当前文件的，不同页面需要不同的路径。

解决：

src/pages/index.astro → ../../src/content/notes/**/*.md
src/pages/notes/index.astro → ../../../src/content/notes/**/*.md

坑 3：日期解析失败

现象：笔记排序混乱，日期显示异常。

原因：Obsidian 笔记的 date 字段可能带中文星期，如 "2026-04-24 星期五"，直接 new Date() 会返回 NaN。

解决：先 .split(' ')[0] 提取纯日期再解析。

坑 4：`read_file` 行号腐蚀

现象：用 read_file 读取文件再 write_file 写回，文件内容被破坏。

原因：read_file 返回的内容带行号前缀（如 1|---），写回时会把行号也写进去。

解决：需要读取原始内容时用 terminal("cat 文件路径") 而非 read_file。

坑 5：Git clone URL 格式

现象：deploy.yml 中 vault 克隆失败。

原因：URL 缺少 github.com。

错误：https://x-access-token:TOKEN@baiye1997/obsidian-vault 正确：https://x-access-token:TOKEN@github.com/baiye1997/obsidian-vault

坑 6：权限不足

现象：GitHub Actions 部署失败。

解决：deploy-pages 需要三个权限：

permissions:
  contents: read
  pages: write
  id-token: write

坑 7：Obsidian wiki-link 在表格中断裂

现象：表格里的 display text 链接失效。

原因：| 被当作表格列分隔符。

解决：表格内用 path 不带显示文字。

坑 8：深色模式 JS 内容不切换

现象：API 数据渲染的 HTML 在深色模式下样式不生效。

原因：JS innerHTML 的内容不经过 Tailwind 编译。

解决：用 MutationObserver 监听 <html> class 变化，重建 innerHTML。

坑 9：Astro `is:inline` script 不支持模板插值

现象：页面不报错但数据为空。

原因：<script is:inline> 中的 {variable} 不会被 Astro 编译。

解决：用 <script type="application/json" id="xxx" set:html={data}> 传递数据。

十二、费用与资源消耗

完全免费的部分

项目	费用
Obsidian App	免费
GitHub（私有仓库 + Actions + Pages）	免费（有额度限制，个人够用）
Hermes Agent	免费（开源）
域名（baiye1997.github.io）	免费

需要付费的部分

项目	费用
LLM API（GPT/Claude/DeepSeek）	按量计费，DeepSeek 很便宜
服务器（运行 Hermes）	取决于你用什么服务器

我们的选择

LLM：OpenRouter 聚合平台，按需切换不同模型
服务器：跑在本地/云服务器上
Obsidian Sync：用官方免费版（也有付费增强版）

十三、给新朋友的建议

最小可行方案（MVP）

如果你想快速体验，先做这几步：

安装 Obsidian，创建 vault，写几篇笔记
安装 Hermes，配一个 LLM provider
配置 Telegram bot，在 Telegram 里跟 AI 聊天
用 AI 帮你管理和生成笔记

博客可以之后再加，先享受知识管理的乐趣。

进阶方案

当你熟悉后，可以：

搭建 Astro 博客，展示你的知识
配置 GitHub Actions 自动部署
设置定时任务（早晚报、英语学习等）
添加更多 skill（东方财富数据、天气、搜索等）

最重要的一点

不要追求完美，先用起来。

我们也是边用边改，踩了无数坑才到今天的形态。笔记结构可以随时调整，工具可以随时替换，重要的是持续积累知识。

🔗 相关阅读

Hermes 快速参考卡 — 常用命令速查
Hermes 源码深度分析 — 深入理解架构
Hermes 迁移完整方案 — 从 OpenClaw 迁移的经验

最后更新：2026/4/27