🪴 Notes Shared

从 Obsidian 到生产级知识库

7分钟阅读

【实战教程】从 Obsidian 到生产级知识库：基于 Quartz 4.x 的全自动部署方案

作者：LuoXingDing
适用场景：Obsidian 笔记库 → 静态知识库 → 服务器自部署 + Nginx + 自动同步

前言

在日常的知识整理中，我主要使用 Obsidian 作为个人笔记管理工具，随着笔记内容的积累，我希望将部分整理好的内容，发布为公开的在线知识库，便于查阅、分享与归档。

经过多次尝试与踩坑，最终我选择了 Quartz 4.x 作为生成静态知识库的框架，配合 rsync 自动部署与 Nginx 服务器发布，形成了一整套高效、稳定、可维护的生产部署流程。

本文完整记录了我从 0 到 1 的配置与实战经验，适合希望用 Obsidian 建立自己的在线数字花园的朋友参考。

为什么选择 Quartz？

相比于传统的静态站点生成器（如 Hugo、Hexo、Jekyll 等），Quartz 专为知识库场景而设计：

  • 完美支持 Obsidian 格式（WikiLink、嵌入、标签）

  • 内置完整双链图谱与标签导航

  • 4.x 版本彻底重构，支持自定义主题、组件与配置

  • 不需要复杂数据库、服务端，纯静态架构，超稳定

系统准备

本地环境

  • 系统：Arch Linux / Ubuntu / macOS

  • 安装组件：

    • git

    • node.js 版本 >= 22

    • npm 版本 >= 10.9.2

    • rsync（用于部署同步）

远程环境

  • Ubuntu 服务器一台

  • nginx 已部署，SSL 证书已配置

项目初始化

1. 拉取官方 Quartz 模板

git clone https://github.com/jackyzha0/quartz quartz-site
cd quartz-site

2. 安装依赖

建议使用 nvm 管理 Node 版本：

nvm install 22
nvm use 22
npm install

3. 初始化内容目录（软链接到 Obsidian）

npx quartz create

  • 选择 Symlink an existing folder

  • 输入 Obsidian 笔记库路径，例如：

    /home/ding/Disk/Sync/Obsidian/wiki/

  • 链接解析格式选择 Treat links as shortest path（与 Obsidian 默认兼容）

配置生产过滤规则

因为我的 Obsidian 笔记中包含了一些模板与临时笔记（如 02-Templates、00-Inbox），这些内容不需要被公开构建。

Quartz 4.x 支持非常灵活的文件过滤：

编辑 quartz.config.ts

import { defineConfig } from "@jackyzha0/quartz"
 
export default defineConfig({
  siteMetadata: {
    title: "我的数字花园",
    author: "LuoXingDing",
    description: "记录我的自托管、技术积累与生活笔记",
    language: "zh-CN",
  },
 
  // 忽略掉不需要发布的目录
  ignorePatterns: [
    "02-Templates/**",
    "00-Inbox/**",
  ],
 
  // 站点基础地址，适配 sitemap 与 SEO
  baseUrl: "https://docs.luoxingding.com/",
 
  theme: {
    typography: {
      header: "serif",
      body: "sans-serif"
    },
    colors: {
      light: { primary: "#007acc" },
      dark: { primary: "#66ccff" }
    }
  },
 
  enableTagPage: true,
})

注意

  • ignorePatterns 支持通配符，非常好用；

  • 这样配置后，构建时自动跳过模板与 Inbox，不需要额外处理，非常干净。

本地预览测试

npx quartz build --serve

访问 http://localhost:8080，确保整体内容预览正常。

你可以在本地随时调试内容，确保发布时万无一失。

自动化部署脚本

每次更新后手动上传很繁琐，因此我配置了 deploy.sh 脚本，一键完成：

创建部署脚本

vim deploy.sh

内容如下：

#!/bin/bash
 
set -e
 
echo "🔧 开始构建 Quartz 静态站点..."
npx quartz build
 
echo "🚀 开始上传到服务器..."
rsync -avz public/ root@1.94.254.213:/var/www/docs/
 
echo "✅ 部署完成！"

赋予执行权限

chmod +x deploy.sh

使用方法

以后只需在本地执行：

./deploy.sh

即完成构建 + 上传 + 发布全过程。

生产环境 Nginx 配置

远程服务器使用 Nginx 负责反向代理与 HTTPS 配置，完整示例如下：

server {
    listen 80;
    server_name docs.luoxingding.com;
    return 301 https://$host$request_uri;
}
 
server {
    listen 443 ssl http2;
    server_name docs.luoxingding.com;
 
    ssl_certificate     /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
 
    root /var/www/docs;
    index index.html;
 
    location / {
        try_files $uri $uri.html $uri/ =404;
    }
}

注意：

  • root 指向的目录需与 rsync 上传目标一致；

  • try_files 确保静态路由正常处理；

  • 完整支持 SEO、搜索引擎抓取、移动端浏览与暗黑模式。

样例效果截图

（此处可附上一张你实际运行 Quartz 后的效果截图）

  • ✅ 完美支持双链、标签、搜索与嵌入

  • ✅ 完整兼容 Obsidian 内部格式

  • ✅ 自动生成 sitemap.xml、RSS 订阅、SEO 友好

升级与维护建议

  • 每次 Quartz 升级时：
git pull
npm install

  • 建议定期备份你的 Obsidian 笔记库与服务器 /var/www/docs 目录；

  • 随时可平滑迁移到其他服务器，不依赖第三方服务，非常可控。

最终成果

✨ 我最终实现了：

  • Obsidian 本地写作 → Quartz 构建 → 自动部署 → 服务器生产环境托管

  • 知识库完全私有控制，无需依赖任何第三方 SaaS

  • 数据自主可控、随时迁移、无限扩展

结语

Quartz 4.x + Obsidian 是目前我认为最适合个人长期知识管理的组合之一。
相比市面上各种收费型 SaaS，这套方案极简、高效、成本极低且安全可控，几乎零依赖，运行多年都不会出问题。

如果你也希望拥有属于自己的数字花园，希望本文能够给你一些启发。

参考链接

关系图谱

反向链接