博客自动化部署配置全记录

记录从零开始搭建 Hugo + Obsidian + GitHub Actions 自动化博客系统的完整过程。

🎯 目标

实现一个完全自动化的博客发布流程：

在 Obsidian 中编写 Markdown 文章
提交到 Git 仓库
自动编译并发布到 GitHub Pages

🏗️ 架构设计

仓库结构

hugo-server (主仓库)
├── jesse-blog/
│   ├── content/          → obsidian-notes (子模块)
│   ├── public/           → JiashuaiXu.github.io (子模块)
│   ├── themes/
│   └── hugo.toml
└── flake.nix

obsidian-notes (内容仓库)
├── posts/
├── about/
├── archive/
└── .github/workflows/
    └── deploy.yml        # 自动部署工作流

JiashuaiXu.github.io (部署仓库)
└── (Hugo 生成的静态文件)

三个仓库的职责

仓库	用途	操作频率
`hugo-server`	Hugo 项目配置、主题管理	偶尔更新
`obsidian-notes`	编写内容（日常操作）	频繁提交
`JiashuaiXu.github.io`	托管静态网站	自动更新

📝 实施步骤

1. 子模块化内容管理

问题： 原来 content/ 目录直接在主仓库中，不便于独立管理。

解决方案：

# 备份现有内容
cp -r jesse-blog/content ~/hugo-content-backup

# 从主仓库删除 content
cd hugo-server
git rm -rf jesse-blog/content
git commit -m "Remove content directory to prepare for submodule"

# 添加为子模块
git submodule add https://github.com/JiashuaiXu/obsidian-notes.git jesse-blog/content

# 迁移内容
cp -r ~/hugo-content-backup/* jesse-blog/content/
cd jesse-blog/content
git add .
git commit -m "Initial commit: Import existing content"
git push origin main

关键点： 必须在 .gitmodules 中正确配置子模块 URL，否则 GitHub Actions 无法初始化。

2. GitHub Actions 工作流

创建 .github/workflows/deploy.yml：

name: Deploy Hugo Site

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      # 1. 检出主仓库（包含所有子模块）
      - name: Checkout hugo-server repository
        uses: actions/checkout@v4
        with:
          repository: JiashuaiXu/hugo-server
          token: ${{ secrets.GH_PAT }}
          submodules: recursive
      
      # 2. 安装 Nix
      - name: Install Nix
        uses: DeterminateSystems/nix-installer-action@main
      
      # 3. 设置 Nix 缓存（加速构建）
      - name: Setup Nix cache
        uses: DeterminateSystems/magic-nix-cache-action@main
      
      # 4. 使用 Nix 环境编译 Hugo 站点
      - name: Build Hugo site
        run: |
          cd jesse-blog
          nix develop --command bash -c "hugo -D"
      
      # 5. 推送到 GitHub Pages
      - name: Deploy to GitHub Pages
        run: |
          cd jesse-blog/public
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add .
          if ! git diff --staged --quiet; then
            git commit -m "Deploy: $(date +'%Y-%m-%d %H:%M:%S')"
            git push origin main
          fi
      
      # 6. 更新主仓库的子模块引用
      - name: Update submodule reference
        run: |
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          cd jesse-blog
          git add public
          if ! git diff --staged --quiet; then
            git commit -m "Update public submodule reference"
            git push origin main
          fi

3. 配置 GitHub Token

创建 Personal Access Token：

访问 https://github.com/settings/tokens
生成 classic token
权限：
- ✅ repo (完整仓库访问)
- ✅ workflow (工作流权限)

添加 Secret：

访问 obsidian-notes 仓库设置
Settings → Secrets and variables → Actions
新建 Secret：
- Name: GH_PAT
- Value: 粘贴 token

4. 修复子模块配置

遇到的问题：

No url found for submodule path 'jesse-blog/content' in .gitmodules

原因： .gitmodules 中缺少 content 子模块配置。

解决方案：

cd hugo-server
git submodule add -f https://github.com/JiashuaiXu/obsidian-notes.git jesse-blog/content
git add .gitmodules jesse-blog/content
git commit -m "Fix: Add content submodule to .gitmodules"
git push origin main

⚙️ 技术选型说明

为什么使用 Nix？

优势：

✅ 环境一致性：本地和 CI 使用相同的 Hugo 版本 (v0.152.2)
✅ 声明式配置：flake.nix 定义所有依赖
✅ 可复现构建：任何人都能获得相同环境

劣势：

⚠️ 首次运行慢：需要下载 Nix 和依赖（3-5分钟）
⚠️ 学习曲线：Nix 语法较复杂

替代方案：

如果觉得 Nix 太重，可以使用 peaceiris/actions-hugo：

- name: Setup Hugo
  uses: peaceiris/actions-hugo@v2
  with:
    hugo-version: '0.152.2'
    extended: true

更快（30秒内完成），但失去环境一致性保证。

最终决定： 保持 Nix，因为本地已在使用，保证一致性更重要。

🚀 工作流程

日常写作流程

# 1. 在 Obsidian 中编写文章（或直接编辑 Markdown）

# 2. 提交到 obsidian-notes
cd obsidian-notes
git add posts/my-new-article.md
git commit -m "Add: 新文章标题"
git push origin main

# 3. 等待 1-3 分钟，自动部署完成
# 4. 访问 https://JiashuaiXu.github.io/ 查看结果

本地测试流程

cd hugo-server

# 进入 Nix 开发环境
nix develop

# 启动本地服务器
cd jesse-blog
hugo server -D

# 访问 http://localhost:1313

📊 构建时间对比

方案	首次运行	后续运行	环境一致性
Nix	3-5 分钟	1-2 分钟	✅ 完美
actions-hugo	30 秒	30 秒	⚠️ 可能不一致
Docker	2-3 分钟	1 分钟	✅ 良好

🎉 成果

✅ 完全自动化的发布流程
✅ 使用 Obsidian 舒适地写作
✅ 内容与配置分离（子模块化）
✅ 环境可复现（Nix）
✅ 无需手动部署

📚 相关资源

💡 后续优化

添加评论系统（Giscus）
配置 RSS feed
添加站点统计（umami）
自动生成 Open Graph 图片
集成全文搜索（Algolia）

完美的博客自动化系统搭建完成！🎊

博客自动化部署配置全记录#

🎯 目标#

🏗️ 架构设计#

仓库结构#

三个仓库的职责#

📝 实施步骤#

1. 子模块化内容管理#

2. GitHub Actions 工作流#

3. 配置 GitHub Token#

4. 修复子模块配置#

⚙️ 技术选型说明#

为什么使用 Nix？#

🚀 工作流程#

日常写作流程#

本地测试流程#

📊 构建时间对比#

🎉 成果#

📚 相关资源#

💡 后续优化#