本博客的框架与部署

本文记录本站的技术选型、关键配置和从零部署的完整流程，既是备忘，也方便未来维护。

整体架构

本站是一个零数据库、零 CMS 的纯静态博客：

Typora
  ↓
Markdown (content/posts/)
  ↓
Git
  ↓
Hugo build
  ↓
静态 HTML (public/)
  ↓
Nginx
  ↓
Cloudflare (CDN + HTTPS + WAF)
  ↓
https://meilingxiangmoyu.uk

技术栈

组件选型说明
静态生成器Hugo v0.165 (extended)单二进制，毫秒级构建
主题PaperMod免费开源，简洁现代
数学公式KaTeX（本地化）不依赖远程 CDN
代码高亮Chroma（Hugo 内置）github-dark 主题
Web 服务器Nginx 1.24直接提供静态文件
DNS/CDNCloudflareProxied + Full (strict)

不使用的：Ghost、数据库、CMS、在线编辑器、Node.js 服务端。

写作工作流

  1. Typora 打开 content/posts/<slug>/index.md
  2. 图片拖入同目录（Page Bundle），写相对路径 ![](image.png)
  3. 本地预览：hugo server -D
  4. git add . && git commit && git push
  5. 服务器 git pull && hugo，网站更新

创建新文章：

hugo new content posts/my-post/index.md

自动生成带 frontmatter 的模板（title/date/draft/description/tags/categories）。

关键配置

LaTeX 支持

Hugo 0.123+ 内置 passthrough 扩展，保护 $...$ 不被 Markdown 误解析：

[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
block = [["$$", "$$"]]
inline = [["$", "$"]]

渲染由 KaTeX 的 auto-render 完成，资源全部本地化在 static/katex/。

代码高亮

[markup.highlight]
codeFences = true
guessSyntax = true
noClasses = false
style = "github-dark"

SEO

hugo.toml 中配置了 baseURL、Open Graph、Twitter Cards、Schema 结构化数据；robots.txt 自动引用 sitemap.xml。

部署流程

服务器端

# 一次性初始化
git clone <repository> /var/www/meilingxiangmoyu
cd /var/www/meilingxiangmoyu
git submodule update --init --recursive   # 拉取 PaperMod

# 日常更新
git pull --ff-only
hugo

Nginx

Nginx 直接指向 Hugo 输出目录：

root /var/www/meilingxiangmoyu/public;
index index.html;

不需要 hugo server，不需要任何常驻进程。

Cloudflare

DNS 两条 A 记录（Proxied）：@ 与 www 指向源站 IP。SSL 模式 Full (strict)，源站使用 Cloudflare Origin Certificate。VPS 防火墙 80/443 仅放行 Cloudflare IP 段。

目录结构

meilingxiangmoyu/
├── archetypes/          # 新文章模板
├── assets/
│   └── css/extended/    # 自定义样式（代码块滚动、表格、KaTeX）
├── content/
│   ├── posts/           # 文章（Page Bundle）
│   └── about/
├── layouts/partials/    # extend_head / extend_post_content (KaTeX)
├── static/
│   ├── katex/           # 本地 KaTeX 资源
│   └── favicon.svg
├── themes/PaperMod/     # 主题 (git submodule)
├── hugo.toml
└── public/              # 构建产物（不入 Git）

为什么选 Hugo

  • 快：上千篇文章也是毫秒级构建
  • 简单：单个二进制，无 Node.js 依赖，无数据库
  • Markdown-first：文章就是普通 Markdown 文件，Typora 直接编辑
  • 免费开源：Hugo 与 PaperMod 均免费
  • 易维护：git 管理一切，回滚/备份就是 git 操作