项目简介

本项目是基于 Obsidian + Quartz + 阿里云 ESA 的个人知识发布系统，将本地 Obsidian 的笔记库，通过 Quartz 4 转化为高性能的静态网页，上传托管至 GitHub 库，通过 GitHub Actions 自动化技术部署到阿里云 ESA 的边缘节点，实现个人网站的全球极速访问。

为什么选择使用 obsidian？

首先，所有笔记都以 .md (Markdown) 格式存储在你的电脑本地，不强制依赖云端，既确保了数据的隐私安全，又方便统一格式与编辑。
Obsidian 强调“双向链接”，让笔记之间形成网状结构，可以直观看到知识点的交汇，发现潜在的逻辑关联，我们使用 Quartz 部署网站后也可以看到知识的关系图谱。

部署流程

一台云服务器（本项目使用阿里云服务器作为演示）、一个 GitHub 账号
使用 Quartz 为 Obsidian 笔记内容生成静态网站，推送到 GitHub 库中
创建具有 AliyunESAFullAccess 权限的 RAM 用户
在 GitHub 仓库中为 Actions 配置 Repository secrets
在阿里云 ESA 的 函数和Pages 创建应用，部署网站

技术方案

组件	选型	理由
内容源	Obsidian	优秀的 Markdown 本地知识库管理工具。
静态生成	Quartz 4	原生支持 Obsidian 语法、Wiki 链接、图谱，生成速度极快。
仓库托管	GitHub	确保原始笔记的私密安全性。
CI/CD	GitHub Actions	自动化编译 Quartz，无需人工干预。
托管与加速	Aliyun ESA	边缘托管 + 边缘计算，访问体验优于传统静态托管。

一、Obsidan 简单配置

Obsidian 目录结构

.obsdian 会保存插件的一些配置
.trash 会保存一些垃圾文件，比如你删除的图片附件、笔记等

如果你的需求只是将笔记推送到 GitHub 当做云备份使用，只需在根目录配置 .gitattributes 和 .gitignore 文件，用 git 将笔记文件推送到自己的仓库即可。如果你想将笔记内容部署成网站，那么这一步可以跳过。

在 Obsidian 根目录创建 .gitattributes 文件，配置如下。
由于 Windows 和 Linux 的换行符不同，如果在 Windows 电脑上更新笔记并上传到 GitHub 后，在 Mac 电脑阅读可能会出现显示问题，我们这里将所有换行符全部换成 LF 换行符

# 所有文件视为文本，但由 Git 自动处理换行符（推荐）
* text=auto

# 明确指定 Markdown 相关文件使用 LF 换行符（关键！）
*.md text eol=lf
*.markdown text eol=lf

# 避免对二进制文件进行换行符转换
*.png binary
*.jpg binary
*.pdf binary

在 Obsidian 根目录创建 .gitignore 文件，配置如下，防止上传 Obsidian 的工作区文件

.obsidian/workspace.json
.obsidian/workspace-mobile.json

配置 Obsidian

我们需要将笔记中插有的图片附件需要统一保存在笔记项目的根目录 Attachments 下，方便管理，在 Obsidian 设置如图所示

700x499

为了防止我们进行文件名重命名、删除图片等操作，导致 Attachments 找不到对应的附件链接。我们需要使用两个好用的插件：Attachment Management 和 Clearing Unused Images，打开设置中的第三方插件，关闭安全模式，搜索安装并开启两个插件。

Attachment Management：配置如下，因为我们在 Obsidian 设置了 附件默认存放位置 就是根目录下，所以 附件保存根路径 直接复制 Obsidian 的设置就好，最后同时注意勾选自动重名附件。

注意：该插件的配置生效后不会对已有的附件进行重新链接，但是该插件提供了重新链接所有附件的指令，如果你已经有了大量的笔记内容和图片附件，请慎用该指令，防止笔记内容被损坏，建议备份后再使用该指令！

700x518

Clearing Unused Images：该插件的功能是一键删除所有失去链接的附件，在 obsidian 中，如果你笔记中的图片已经删除，位于 Attachments 的已经链接好的图片不会删除，图片仍然保存在该目录下。

配置如下，Ribbon Icon 建议勾选，勾选后在 Obsidian 左侧栏会发现多了一个小图标，点击一下就可以一键清除。

如此，Obsidna 设置成功，所有的附件统一存在根目录的 Attachments 文件夹中，且笔记更改、拖动、重命名、删除等操作，附件链接不会失效

二、安装 Quartz

Quartz 本质上一个静态网站生成器，一个前端框架，他的的核心工作就是：输入 Markdown，输出 HTML/JS/CSS。

我们需要为 Quartz 新建一个文件夹 QuartzSite，在新建文件夹下执行以下命令，把 Quartz 的仓库克隆到本地，注意需提前部署 Git 和 NodeJS

下载 Git 可以查看这里：2.4.1 安装 Git
下载 NodeJS 可以查看这里：2.5.1 软件安装指令

git clone https://github.com/jackyzha0/quartz.git
npm install
npx quartz create

选择方式：建议选 Empty Quartz，之后我们只需把想要在网站上展示的文件从你自己的笔记中拖到 QuartzSite/content 文件夹即可，这样可以把你想要在网站中展示的内容和本地的笔记文件隔离 链接格式：选择 Shortest path（匹配 Obsidian 设置里的内部链接类型）

在 QuartzSite 根目录的 content 文件夹中放入你的笔记内容，并新建一个首页文件 index.md ，内容可以先随便填写，主要是为了防止 Quartz 构建时无法找到你的首页文件，之后如果要设计首页时再做修改。

这里我们的 笔记内容和Attachments 是你想展示的笔记内容，Attachments 只保存着我们笔记中的附件

执行以下命令，可以先在本地端口看一下效果

npx quartz build --serve

三、GitHub 相关

第 1 步：创建 GitHub 私有仓库

登录你的 GitHub，点击 New repository
Repository name: 为仓库创建名字
Public/Private: 建议选择 Private ，创建私有库
点击 Create repository，创建完成

第 2 步：将 QuartzSite 项目文件推送到 GitHub

在 QuartzSite 根目录下运行 PowerShell 终端（确保在 QuartzSite 的根目录下执行命令），找到刚才创建库的 GitHub 地址并复制，在 PowerShell 终端执行命令，关联自己的远程仓库

700x618

# 关联远程仓库 (替换为你自己的 GitHub 地址)
git remote add origin https://github.com/你的用户名/项目名.git

接着，执行以下命令，完成推送

# 1. 添加所有文件
git add .
# 2. 提交
git commit -m "first push"
# 3. 推送
git push -u origin main

四、配置阿里云 ESA (边缘加速)

开通 ESA 并创建应用

在阿里云搜索边缘安全加速 ESA，进入控制台，按提示步骤导入自己刚才创建的的 GitHub 仓库

这里的构建命令需要修改为 npx quartz build，使用 Quartz 的构建命令，然后点击开始部署注意这里的 项目名称 我们后期配置 esa-cli 的指令时还会用到，请记住这个名称

构建失败先不用管，因为我们还没有配置 esa-cli

获取 AccessKey ID 和 AccessKey Secret (重要)

建议使用 RAM用户 分配 ESA 的权限，RAM 就是阿里云的“子账号权限系统”，我们给该 RAM用户 添加权限 AliyunESAFullAccess，选择给 RAM 用户分配指定权限策略较安全，这样可以避免放开所有权限带来的风险

访问阿里云 RAM 控制台，打开 RAM 访问控制，在左侧栏找到用户选项，点击创建用户，开始创建

注意勾选 使用永久 AccessKey 访问

700x147

保存好生成的 AccessKey ID 和 AccessKey Secret，之后会在 GitHub 配置中用到创建用户完成后，给该用户新增 AliyunESAFullAccess 权限

700x158

打开 GitHub，在刚在创建好的库中，创建 Repository secrets ，将刚才保存的 AccessKey ID 和 AccessKey Secret 配置到这里，这里我已经配置好

一共创建两个 secrets， Name 可以填写 ESA_ACCESS_KEY_ID 和 ESA_ACCESS_KEY_SECRET，方便记忆 Secrets 分别填写刚才的生成的 AccessKey ID 和 AccessKey Secret

这样，RAM 用户权限和 GitHub 就配置成功了

五、设置 GitHub Actions 自动部署

我们要实现：你每次在本地 git push，阿里云的网站就自动更新。所以，我们要配置使用 GitHub Acitons 功能。

在 QuartzSite/.github/workflows/ 的目录下新建文件 deploy-aliyun-esa.yml，配置以下代码

name: Obsidian Quartz to Aliyun ESA

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

      - name: Install dependencies
        run: npm install

      - name: Build Quartz
        run: npx quartz build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: quartz-public
          path: public
          retention-days: 1

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v4
        with:
          name: quartz-public
          path: public

      - name: Deploy to ESA
        env:
          ACCESS_KEY_ID: ${{ secrets.ESA_ACCESS_KEY_ID }}
          ACCESS_KEY_SECRET: ${{ secrets.ESA_ACCESS_KEY_SECRET }}
        run: |
          npm i esa-cli@latest -g
          esa-cli login --access-key-id $ACCESS_KEY_ID --access-key-secret $ACCESS_KEY_SECRET
          esa-cli deploy --environment production --message "Auto deploy from GitHub"

这里部署阿里云 ESA 时需使用 esa-cli 的，我在该文件中已经配置好，感兴趣的话可以参考 esa-cli 的具体文档：esa-cli相关文档

配置好 deploy-esa.yml 文件后，接着在 QuartzSite 根目录下新建文件 esa.jsonc ，作为 ESA 的配置文件。

注意：这里的 name 填写之前你创建过的 ESA 应用的项目名称。6.1 基于 Obsidian 和阿里云ESA 自动化部署个人知识库网站

将 QuartzSite 文件夹全部项目推送到 GitHub 后，我们可以在 GitHub 的查看 Actions 中的运行情况

进入 workflow 查看运行情况

同时，我们可以在阿里云的边缘加速 ESA 看到自己之前创建失败的应用，进入应用查看他的部署情况，等待部署成功，使用他提供的临时域名访问网站

注意：如果已经购买过域名，也可以自行配置到该应用中

访问域名测试网站，就算部署成功了

之后，如果你的笔记内容有更新，你只需把新笔记内容全部更新到 QuartzSite/content 文件夹中，然后把 QuartzSite 文件夹全部推送到 GitHub 库中，通过 GitHub Actions 就会自动同步到你服务器部署的网站上。

六、项目改进

1. 实测中发现笔记中如果使用引用（块引用等）可能中会出现显示问题

在标准的 Markdown 解析逻辑中，HTML 标签被视为“原始代码块”。在 QuartzSite/quartz.config.ts 中，enableInHtmlEmbed 默认值为 false

当它是 false 时：如果你在笔记中使用了某种特殊的排版（比如把内容放在了 <div> 标签里，或者使用了复杂的 块引用 和 Callouts），Quartz 会认为这些 HTML 内部的内容是“已经写好的死代码”，从而停止对其中的 [[WikiLinks]] 进行二次解析。
当它是 true 时：Quartz 被赋予了“透视眼”，它允许在 HTML 嵌入内容中直接进行 Markdown 语法的解析。这意味着即便你的链接被包裹在多层 HTML 容器中，Quartz 依然会进去把 [[...]] 找出来并转化成真正的超链接。

所以修改 enableInHtmlEmbed 为 true ，否则当这些链接处于复杂的 HTML 容器（如 Callouts 或列表）中时，它们会被当作纯文本处理，无法被解析为链接。

因此需要我们配置更改 QuartzSite/quartz.config.ts 目录下的文件，找到 ObsidianFlavoredMarkdown ，将值改为 true ，引用的功能就可以使用，参考文档

700x156