个人网站与知识库搭建

#website #obsidian #github-actions #vercel

个人网站与知识库搭建

本文记录 linbo.lol 个人服务入口和 note.linbo.lol 知识库的实际架构、发布流程与恢复方法。它取代旧的 Digital Garden 插件发布说明和 Vercel 私有 submodule 方案。

当前站点

地址	用途	承载方式
linbo.lol	个人服务导航	VPS 上的 Nginx
note.linbo.lol	Obsidian 公开知识库	GitHub + Vercel

linbo.lol 目前统一提供以下入口：

Linbo 笔记；
OpenDelivery；
Clash / Mihomo 订阅；
3X-UI 管理；
Headscale / Headplane 管理。

网络和代理部分单独记录在 Tailscale + Clash + VPS 中继方案。

知识库架构

Obsidian Vault
    │
    │ Obsidian Git / git push
    ▼
Yu-Linbo/obsidian_backup          私有、完整、唯一数据源
    │
    │ GitHub Actions
    │ 筛选公开目录、转换双链、复制附件
    ▼
Yu-Linbo/obsidian_note            网站代码与公开内容
    │
    │ Vercel 自动构建
    ▼
https://note.linbo.lol/

两个仓库职责必须保持清晰：

obsidian_backup 保存完整 Vault，也是日常唯一需要同步的仓库；
obsidian_note 保存 Eleventy 网站、美化代码和 CI 生成的公开内容；
笔记内容只从 backup 单向同步到 note，不做双向合并；
Vercel 只连接 note，不能直接部署含私人笔记的 backup。

发布范围

现在不再依赖 Digital Garden 插件，也不需要 dg-publish property。

默认发布仓库内的所有 Markdown，但以下目录始终排除：

self/**
ud_work/**
所有隐藏目录，例如 .obsidian/**、.trash/**、.github/**

因此：

普通公开笔记放在 ROS/、SLAM/、UBUNTU/、docs/ 等目录；
个人计划、上下文和私人资料放入 self/；
工作资料和公司项目放入 ud_work/；
公开笔记移入排除目录后，下次发布会自动从网站仓库删除；
排除目录中的内容不会被复制到 obsidian_note。

Properties 约定

大部分笔记不需要 properties。文件路径会自动生成网页 URL，一级标题会作为页面标题。

只有确实需要时才添加：

---
title: 页面显示名称
permalink: /稳定的网页地址/
tags:
  - topic
status: evergreen
updated: 2026-09-08
---

建议：

title：显示名称与文件名不同时使用；
permalink：已有外部链接、需要长期保持 URL 时使用；
tags：确实需要分类或页面展示时使用；
status、updated：维护长期文档时可选；
不再在源笔记中使用 dg-publish、dg-home、dg-permalink、dgPassFrontmatter、noteIcon。

首页固定使用仓库根目录的 Welcome.md，无需额外 property。

自动发布流程

当 obsidian_backup/master 收到提交时，.github/workflows/publish-digital-garden.yml 会执行：

检出 backup；
使用 GARDEN_REPO_TOKEN 检出 obsidian_note/main；
安装网站锁定的 Node.js 依赖；
执行 scripts/export-digital-garden.cjs；
清理 note 中旧的受管笔记和附件；
导出公开 Markdown、Obsidian 双链和图片；
检查重复 permalink；
以 github-actions[bot] 提交到 note；
Vercel 检测到新提交后自动部署。

如果内容没有变化，Action 不会创建空提交。

GitHub Token

跨仓库推送使用 fine-grained personal access token：

Repository access：只选择 Yu-Linbo/obsidian_note；
Repository permissions：Contents: Read and write；
在 obsidian_backup 的 Settings → Secrets and variables → Actions 中保存；
Secret 名称固定为 GARDEN_REPO_TOKEN。

Token 不得写入 Vault、.env、脚本或普通 Git 文件。到期后生成新 Token，并更新同名 Secret 即可。

本地验证

网站仓库首次使用前安装依赖：

cd ../obsidian_note
npm ci

从 backup 导出到本地网站仓库：

cd ../first_test
node scripts/export-digital-garden.cjs ../obsidian_note

构建网站：

cd ../obsidian_note
npm run build

导出命令会清理目标仓库中的旧笔记内容。执行前应确认 obsidian_note/src/site/notes 和 src/site/img/user 没有需要保留的手工修改。网页模板、组件和样式不在清理范围内。

域名与部署职责

推荐保持当前边界：

根域名 linbo.lol 指向 VPS，由 Nginx 提供服务导航和反向代理；
note.linbo.lol 在 Vercel 项目中绑定，由 Vercel 负责 HTTPS 和静态网站发布；
服务导航只保存入口，不在首页暴露管理密钥或内部地址；
Headscale、3X-UI 等管理入口应继续使用认证、访问控制和最小暴露原则。

DNS 或 Vercel 配置变更后，应依次验证：

curl -I https://linbo.lol/
curl -I https://note.linbo.lol/

恢复与排障

更换电脑或恢复 Vault

clone obsidian_backup；
用 Obsidian 打开仓库目录；
安装或启用 Obsidian Git；
不需要安装 Digital Garden 插件；
正常提交到 master 即可触发网站发布。

Action 无法检出或推送 note

检查：

GARDEN_REPO_TOKEN 是否存在；
Token 是否过期；
Token 是否只选择了正确的 note 仓库；
Contents 是否为 Read and write；
obsidian_note/main 是否设置了禁止机器人直接推送的分支保护。

Vercel 没有部署

先检查 obsidian_note/main 是否出现 Publish notes from obsidian_backup ... 提交：

没有提交：问题在 GitHub Actions；
已有提交但没有部署：检查 Vercel 项目的 Git 集成和 Production Branch；
部署失败但页面未更新：检查 Vercel Deployment 日志和 CDN 缓存。

私有 submodule

当前方案不再使用私有 Git submodule，也不需要在 Vercel Build Command 中拼接 GitHub Token。若将来重新引入私有 submodule，应优先使用只读 deploy key 或权限受限的 Token，避免 classic PAT 的整个 repo 权限。

日常维护

git pull
# 在 Obsidian 中编辑
git add .
git commit -m "vault backup: YYYY-MM-DD HH:mm:ss"
git push

推送后检查链路：

backup 的 Publish Notes Website Action 成功；
note 出现机器人提交；
Vercel Production Deployment 成功；
首页、搜索、新页面和至少一个图片附件可访问。